VM-based web service

This tutorial demonstrates how to configure web services on KakaoCloud based on a 3-tier architecture.

Basic information

• Estimated time: 60 minutes
• User environment:
  • Recommended OS: MacOS, Ubuntu
  • Region: kr-central-2
• Prerequisites:
  • Access key

About this scenario

This scenario explains how to implement the KakaoCloud Library Web Service using a 3-tier architecture. A 3-tier architecture divides web applications into three layers: Web, App, and Database, making it suitable for building stable and scalable web services.

• Configuration of a 3-tier architecture for web hosting
• Strengthening security by using a bastion host as a secure access path
• High availability with KakaoCloud Load Balancer
• Database configuration using KakaoCloud MySQL

Scenario architecture

Before you start

In the preliminary stage, create the resources required for a web service based on a 3-tier architecture. Start by setting up the KakaoCloud network environment for deployment. Then, configure Web server instance, Application server instance, and a Bastion server instance in a private network for enhanced security.

1. Configure VPC and subnets

Before setting up the computing environment in KakaoCloud, configure vpc and subnets. Refer to the Building network using NAT instances in multi-availability zones guide to ensure resources in private subnets can communicate externally. The network setup for this tutorial is based on the values defined in that document.

2. Configure security groups

1. Go to KakaoCloud console > Beyond Networking Service > VPC > Security Group**.

2. Click the [Create security group] button on the right to create a new security group.

   Security group: tutorial-bastion-sg

   1. Enter the security group name and description as follows:

      Name	Description (optional)
      tutorial-bastion-sg	Security policy for bastion host

   2. Click the [+ Add] button at the bottom and configure the inbound rules as follows, then click [Apply].
      

      Check your public IP

      Click the following button to find your current public IP address:
      

      Rule name	Field	Value
      bastion inbound policy 1	Protocol	TCP
      	Source	{your public IP}/32
      	Port range	10000-10010
      	Description	bastion inbound policy 1
      bastion inbound policy 2	Protocol	TCP
      	Source	{your public IP}/32
      	Port range	81
      	Description	bastion inbound policy 2
      bastion inbound policy 3	Protocol	TCP
      	Source	{your public IP}/32
      	Port range	22
      	Description	bastion inbound policy 3

   Security group: tutorial-web-sg

   1. Enter the security group name and description as follows:

      Name	Description (optional)
      tutorial-web-sg	Security policy for web server

   2. Click the [+ Add] button at the bottom and configure the inbound rules as follows, then click [Apply].

      Rule name	Field	Value
      web inbound policy	Protocol	TCP
      	Source	10.0.0.0/20
      	Port range	80
      	Description	web inbound

   Security group: tutorial-app-sg

   1. Enter the security group name and description as follows:

      Name	Description (optional)
      tutorial-app-sg	Security policy for app server

   2. Click the [+ Add] button at the bottom and configure the inbound rules as follows, then click [Apply].

      Rule name	Field	Value
      app inbound policy	Protocol	TCP
      	Source	10.0.32.0/20
      	Port range	8080
      	Description	app inbound

3. Create Bastion instance

A bastion host serves as a gateway to cloud instances, enhancing security by blocking direct access. It facilitates efficient remote access, cloud instance management, and smooth inter-tier communication.

Below are the steps to create a bastion instance in a virtual machine (VM):

1. Go to the KakaoCloud console > Beyond Compute Service > Virtual Machine** menu.

2. In the Instances tab, click the [Create instance] button and configure the VM instance as follows:

   Category	Item	Configuration/Value	Remarks
   Basic info	Name	tutorial-bastion
   	Number of instances	1
   Image		Ubuntu 20.04
   Instance type		m2a.large
   Volume	Root volume	20
   Key pair		{USER_KEYPAIR}	⚠️ Ensure you securely save the key pair upon first generation. Lost keys cannot be recovered and require re-issuance.
   Network	VPC	tutorial
   	Subnet	main (10.0.0.0/20)
   	Security group	tutorial-bastion-sg

4. Create web instance

To set up the foundation for a web service, create a virtual machine (VM) instance.

1. Go to the KakaoCloud console > Beyond Compute Service > Virtual Machine** menu.

2. In the Instances tab, click [Create instance] and configure the VM as follows:

   caution

   • Ensure to generate and securely store the key pair during the first use. Lost keys cannot be recovered.
   • Use the default security group configuration. Modify it later to match detailed conditions.

   Category	Item	Configuration/Value	Remarks
   Basic info	Name	tutorial-web
   	Number of instances	2
   Image		Ubuntu 20.04
   Instance type		m2a.large
   Volume	Root volume	20
   Key pair		{USER_KEYPAIR}	Select the previously created or used key pair.
   Network	VPC	tutorial
   	Subnet	{VPC_ID}_sn_2 (10.0.16.0/20)
   	Security group	tutorial-web-sg

5. Create app instance

To establish the foundation for the application layer where business logic is executed, create a VM instance.

1. Go to the KakaoCloud console > Beyond Compute Service > Virtual Machine** menu.

2. In the Instances tab, click [Create instance] and configure the VM as follows:

   Category	Item	Configuration/Value	Remarks
   Basic info	Name	tutorial-app
   	Number of instances	2
   Image		Ubuntu 20.04
   Instance type		m2a.large
   Volume	Root volume	20
   Key pair		{USER_KEYPAIR}	Select the previously created or used key pair.
   Network	VPC	tutorial
   	Subnet	{VPC_ID}_sn_4 (10.0.48.0/20)
   	Security group	tutorial-app-sg

Getting started

The following details the steps to configure the web service:

Step 1. Set up bastion host

A bastion host acts as a gateway to web and app servers. Associate a public IP for external access.

info

If you encounter a bad permissions error with the key file, resolve it by adding the sudo command.

1. Go to Virtual Machine > Instance, select the Bastion instance you created earlier, and click [Associate public IP].

   • Verify the associated public IP in the Network tab.

2. Open a terminal on your local environment and navigate to the folder where you downloaded the key pair file using the cd command.

   • By default, the key file is stored in the Downloads folder if it was newly created (cd ~/Downloads).

3. Execute the following command to access the instance via SSH:

   chmod 400 ${PRIVATE_KEY}.pem # grant read permission  
   ssh -i ${PRIVATE_KEY}.pem ubuntu@${BASTION_PUBLIC_IP}

   Variables	Description
   PRIVATE_KEY🖌︎	key file name
   BASTION_PUBLIC_IP🖌︎	Go to virtual machine > instance menu, select the created `Bastion` instance, and check the network tab

4. To run Nginx Proxy Manager, first configure the bastion host. Execute the following command for provisioning.

   sudo curl -o /tmp/install-bastion.sh https://raw.githubusercontent.com/kakaoenterprise/kakaocloud-tutorials/bastion-host/install-bastion.sh
   bash /tmp/install-bastion.sh
   Nginx Proxy Manager(NPM)

   Nginx Proxy Manager (NPM) is an open-source project that simplifies the setup and management of web servers based on Nginx. This tool helps users effectively configure web servers and manage multiple domains.

5. Open a browser in the local environment and access the management page by entering the address below.

   • http://${BASTION_PUBLIC_IP}:81/login

   • ID : admin@example.com
   • Password: changeme

   Item	Description
   {BASTION_PUBLIC_IP}	Click on the Bastion instance created in Virtual Machine > Instance, then go to the Network tab to check.

6. Go to Dashboard > Streams.

7. Enter the information for the Web and App hosts as follows:

   Category	Field	Value
   tutorial-web-1	Incoming Port	10000
   	Forward Host	Private IP of the created tutorial-web-1 instance - Click on the tutorial-web-1 instance in Virtual Machine > Instance, then check the Network tab
   	Forward Port	22
   tutorial-web-2	Incoming Port	10001
   	Forward Host	Private IP of the created tutorial-web-2 instance - Click on the tutorial-web-2 instance in Virtual Machine > Instance, then check the Network tab
   	Forward Port	22
   tutorial-app-1	Incoming Port	10002
   	Forward Host	Private IP of the created tutorial-app-1 instance - Click on the tutorial-app-1 instance in Virtual Machine > Instance, then check the Network tab
   	Forward Port	22
   tutorial-app-2	Incoming Port	10003
   	Forward Host	Private IP of the created tutorial-app-2 instance - Click on the tutorial-app-2 instance in Virtual Machine > Instance, then check the Network tab
   	Forward Port	22

8. Traffic to internal hosts is forwarded through the Bastion. To allow the Web and App hosts to receive traffic sent from the Bastion, configure the security groups as follows:

   Web instance

   1. Go to Virtual Machine > Instance and click on the created Web instance.
   2. In the Security tab, click the hyperlink for tutorial-web-sg↗️, then select Manage inbound rules.
   3. Click the [Add] button and configure the inbound rules as follows, then click [Apply].

   Note

   Rules will not be saved unless you click the [Apply] button.

   Category	Field	Value
   Web	Protocol	TCP
   	Source	{BASTION_PRIVATE_IP}/32 - Click on the Bastion instance created in Virtual Machine > Instance, then go to the Network tab to check.
   	Port	22
   	Description (optional)	Web inbound policy

   App instance

   1. Go to Virtual Machine > Instance and click on the created App instance.
   2. In the Security tab, click the hyperlink for tutorial-app-sg↗️, then select Manage inbound rules.
   3. Click the [Add] button and configure the inbound rules as follows, then click [Apply].

   Note

   Rules will not be saved unless you click the [Apply] button.

   Category	Field	Value
   App	Protocol	TCP
   	Source	{BASTION_PRIVATE_IP}/32 - Click on the Bastion instance created in Virtual Machine > Instance, then go to the Network tab to check.
   	Port	22
   	Description (optional)	App inbound policy

9. Check whether you can access each host from your local environment. Use the forwarding information configured earlier to connect to the internal hosts on their respective ports. Navigate to the folder containing the key pair file and run the following commands:

   *tutorial-web-1  
   ssh -i ${PRIVATE_KEY}.pem ubuntu@${BASTION_PUBLIC_IP} -p 10000
   
   \*tutorial-web-2  
   ssh -i ${PRIVATE_KEY}.pem ubuntu@${BASTION_PUBLIC_IP} -p 10001
   
   \*tutorial-app-1
   ssh -i ${PRIVATE_KEY}.pem ubuntu@${BASTION_PUBLIC_IP} -p 10002
   
   \*tutorial-app-2  
   ssh -i ${PRIVATE_KEY}.pem ubuntu@${BASTION_PUBLIC_IP} -p 10003

   Variables	Description
   PRIVATE_KEY🖌︎	Key file name
   BASTION_PUBLIC_IP🖌︎	Click on the `Bastion` instance created in Virtual Machine > Instance menu, then go to the Network tab to check.

Step 2. Create managed MySQL database

KakaoCloud's MySQL is a fully managed database service provided in the VPC environment. This service allows you to provision MySQL instances easily through the console without a complicated installation process and use them securely in a logically separated network.

1. Go to the KakaoCloud Console > Data Store > MySQL menu.

2. In the Instance Group tab, click the [Create instance group] button and refer to the following to create an instance group.

   Category	Item	Setting/Input value
   Basic settings	Instance group name	tutorial-mysql
   	Description	Optional
   MySQL settings	Engine version	Use the specified value
   	MySQL user name	admin
   	MySQL password	root1234
   Instance availability/number		Single (Primary instance)
   Instance type		m2a.large
   Storage type/size		100
   Log storage type/size		100
   Network settings	VPC	tutorial
   	Subnet	{VPC_ID}_sn_5 (10.0.64.0/20)
   Automatic backup	Automatic backup option	Not used

Step 3. Create application server

The WAS (Web Application Server) connects to the DB and provides features for complex services like user registration, login, and comments.

1. Access the VM mapped to the port set in nginx-proxy-manager.

   # tutorial-app-1
   ssh -i ${PRIVATE_KEY}.pem ubuntu@${BASTION_PUBLIC_IP} -p 10002
   
   # tutorial-app-2
   ssh -i ${PRIVATE_KEY}.pem ubuntu@${BASTION_PUBLIC_IP} -p 10003

   Variables	Description
   PRIVATE_KEY🖌︎	Key file name
   BASTION_PUBLIC_IP🖌︎	Click on the `Bastion` instance created in Virtual Machine > Instance menu, then go to the Network tab to check.

2. Install the example project.

   git clone -b kakaocloud-library https://github.com/kakaoenterprise/kakaocloud-tutorials

3. Navigate to the folder where the example project is located.

   cd kakaocloud-tutorials

4. Install the packages required to build and run the example project.

   bash install-requirements.sh

5. Enter the environment variables and run the example application.

   sudo docker run -it \
   -e MYSQL_HOST=${MYSQL_HOST} \
   -e DB_USERNAME=${DB_USERNAME} \
   -e DB_PASSWORD=${DB_PASSWORD} \
   -p 8080:8080 \
   --name kakaocloud-library-server -d \
   $(sudo docker build -q -f ./server/deploy/Dockerfile ./server)

   Variables	설정값	Description
   MYSQL_HOST🖌︎	MYSQL_ENDPOINT	Address of the MySQL host, click on the `tutorial-mysql` instance group created in MySQL > Instance Group tab, and check the endpoint at the top
   DB_USERNAME🖌︎	admin	Database user name
   DB_PASSWORD🖌︎	root1234	Database user password

Step 4. Create load balancer on application server

1. Go to KakaoCloud Console > Beyond Networking Service > Load Balancing** and click Create Load Balancer.

2. Enter the name and description of the load balancer to be created, and configure the VPC and subnet mappings. Refer to the following details for listener settings and click Create.

   Category	Item	Configuration/Value
   Type	Network Load Balancer (L4)
   Basic info	Load balancer name	tutorial-app-lb
   Network	VPC	tutorial
   	Subnet	{VPC_ID}_sn_3 (10.0.32.0/20)
   Listener	Protocol	TCP
   Port		8080

3. Wait until the provisioning status of the created load balancer changes to Active.

   • This may take 1–3 minutes.

4. In the left sidebar, click Target Group, and then click Create target group.

5. Configure the following information and click Next.

   Category	Item	Configuration/Value
   Load balancer	Availability zone	kr-central-2-a
   	Load balancer	tutorial-app-lb
   	Listener	TCP:8080
   Basic info	Target group name	tutorial-app-target-group
   	Protocol	TCP
   	Algorithm	Round Robin
   	Sticky session	Not used
   Health check	Enabled	Yes
   	Type	TCP
   	Interval	10
   	Timeout	5
   	Success threshold	3
   	Failure threshold	3

6. Select the application instances to be added to the target group.

7. Enter the following port information, click Add target, and then click Next.

   Target instance	Port
   tutorial-app-1	8080
   tutorial-app-2	8080

8. Verify the configuration and click Create.

9. Ensure the application server can be accessed by the load balancer and health checks. Add the following inbound rules to the security group tutorial-app-sg for the application server:

   1. Go to VPC > Security Group, and select tutorial-app-sg.

   2. Click Manage inbound rules and add the following policies. All health check IPs must be added. In this example, two health check IPs are assumed.

      Inbound rule	Description	Protocol	Source	Port
      app inbound policy 1	Access for load balancer and health check IP 1	TCP	{healthcheck-ip1}/32 - Load Balancing > Target Group > Targets tab > Health check IP per subnet	8080
      app inbound policy 2	Access for load balancer and health check IP 2	TCP	{healthcheck-ip2}/32 - Load Balancing > Target Group > Targets tab > Health check IP per subnet	8080

Step 5. Create a web server

A web server serves static data such as HTML, CSS, and JavaScript files over the internet using the HTTP protocol. To serve static data, install the nginx web server application and configure the example React project to provide static data upon access. Requests under the /api path are forwarded to the application server.

1. Connect to the VM using the port mapped in the Nginx Proxy Manager. Navigate to the folder containing the key pair file and run the following:

   # tutorial-web-1
   ssh -i ${PRIVATE_KEY}.pem ubuntu@${BASTION_PUBLIC_IP} -p 10000
   # tutorial-web-2
   
   ssh -i ${PRIVATE_KEY}.pem ubuntu@${BASTION_PUBLIC_IP} -p 10001

   Variables	Description
   PRIVATE_KEY🖌︎	Key file name
   BASTION_PUBLIC_IP🖌︎	Click on the `Bastion` instance created in Virtual Machine > Instance menu, then go to the Network tab to check.

2. Install the example project.

   git clone -b kakaocloud-library https://github.com/kakaoenterprise/kakaocloud-tutorials

3. Navigate to the folder where the example project is located.

    cd kakaocloud-tutorials

4. Install the packages required to build and run the example project.

   bash install-requirements.sh

5. Enter the environment variables and run the example application.

   sudo docker run -it \
   -e SERVER_ENDPOINT=${SERVER_ENDPOINT} \
   -p 80:80 -p 443:443 \
   --name kakaocloud-library-client -d \
   $(sudo docker build -q -f ./client/deploy/Dockerfile ./client)

   Variables	Values	Description
   SERVER_ENDPOINT🖌︎	http://{APP_LB_PRIVATE_IP}:8080	Enter the private IP of the created application load balancer in `{APP_LB_PRIVATE_IP}`.

Step 6. Create load balancer on web server

This step involves creating a load balancer to handle client requests and distribute traffic to multiple web servers.

1. Go to KakaoCloud Console > Beyond Networking Service > Load Balancing** and click Create Load Balancer.

2. Enter the name and description of the load balancer, map the VPC and subnet, and set up the listener based on the following details. Click Create.

   Category	Item	Configuration/Value
   Type		Application Load Balancer
   Basic info	Load balancer name	tutorial-web-lb
   Network	VPC	tutorial
   	Subnet	main
   Listener	Protocol	HTTP
   	Port	80

3. Wait until the provisioning status of the load balancer becomes Active. This may take 1–3 minutes.

4. In the left sidebar, click Target Group, then click Create target group.

5. Set up the configuration using the following details and click Next.

   Category	Item	Configuration/Value
   Load balancer	Availability zone	kr-central-2-a
   	Load balancer	tutorial-web-lb
   	Listener	HTTP:80
   Basic info	Target group name	tutorial-web-target-group
   	Protocol	HTTP
   	Algorithm	Round Robin
   	Sticky session	Not used
   Health check	Enabled	Yes
   	Type	HTTP
   	HTTP method	GET
   	HTTP version	1.1
   	HTTP status code	200
   	Path	/
   	Interval	10
   	Timeout	5
   	Success threshold	3
   	Failure threshold	3

6. Select the instances to add to the target group.

7. Enter the port information as shown below, click Add target, and then click Next.

   Target instance	Port
   tutorial-web-1	80
   tutorial-web-2	80

8. Verify the configuration and click Create.

9. Ensure that the load balancer and health checks can access the web server. Add the following inbound rules to the security group tutorial-web-sg.

   1. Go to VPC > Security Group and select tutorial-web-sg.

   2. Click Manage inbound rules and add the following policies. All health check IPs must be added. This example assumes two health check IPs.

      Inbound rule	Description	Protocol	Source	Port
      web inbound policy 1	Access for load balancer and health check IP 1	TCP	{healthcheck-ip1}/32 - Check in Load Balancing > Target Group > Targets tab > Health check IP per subnet	80
      web inbound policy 2	Access for load balancer and health check IP 2	TCP	{healthcheck-ip2}/32 - Check in Load Balancing > Target Group > Targets tab > Health check IP per subnet	80

Step 7. Associate public IP to web server load balancer

1. Go to Load Balancing > Load Balancer, and select the previously created web load balancer.
2. Click Associate public IP.
3. Go to the Details tab to find the public IP.

Step 8. Verify service access

Open a browser and access the registered public IP to verify the service. If successful, you should see the "KakaoCloud Library" service page as shown below: