Deploy Kubernetes cluster using Kubernetes Engine

You can use Kubernetes Engine to create a Kubernetes cluster and deploy a web service on top of it.

info

• Estimated time: 30 minutes
  
• Recommended OS: macOS
• Prerequisites:
  • IAM access key

Before you start

1. Set up network environment

Before building a computing environment on KakaoCloud, you must first configure the network. Refer to Build a network using a NAT instance across multiple availability zones to create a network environment suitable for Kubernetes clusters. This document explains how to safely connect to the internet from a private subnet using a NAT instance. The configuration in this guide is based on the values defined in the network setup document linked above.

2. Deploy example project container image

This tutorial uses an example project. Refer to Storing and using images with Container Registry to upload the example project container image to KakaoCloud's Container Registry.

Getting started

Step 1. Create Kubernetes cluster

Kubernetes Engine is a VPC-based managed Kubernetes service. It enables you to easily create and manage Kubernetes clusters without the need for complex manual processes. In this step, you'll log in to the KakaoCloud console and manually create the necessary resources for your service. Follow these steps to create a Kubernetes cluster via the console:

1. Go to KakaoCloud Console > Container Pack > Kubernetes Engine > Clusters and click Create cluster.

2. Refer to the settings below to configure the cluster and associated VPC.

   Category	Field	Value
   Basic settings	Cluster name	tutorial
   	Kubernetes version	1.29
   Cluster network settings	VPC	tutorial
   	Subnets	- main - {VPC_ID}_sn_1 - {VPC_ID}_sn_2 - {VPC_ID}_sn_6

3. In the cluster list, select the created cluster and go to the Node pools tab, then click Create node pool.

4. Refer to the following configuration for the node pool:

   Node pool type	Instance type	Volume	Node count
   Virtual Machine	m2a.large	50	2

Step 2. Call Kubernetes API with kubectl

The kubectl CLI tool is used to interact with the Kubernetes API. All interactions with the cluster are performed via API calls to the Kubernetes API server in the control plane.

Install kubectl

Install kubectl based on your operating system.

Mac

1. Use either Homebrew or curl to install kubectl.

   Using Homebrew

   brew install kubectl
   Using curl (Intel)

   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"
   Using curl (Apple Silicon)

   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

2. Verify installation:

   Check version

   kubectl version --client

Linux (Ubuntu)

1. Use curl to install kubectl.

   Using curl

   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"

2. Verify installation:

   Check version

   kubectl version --client

Download and configure kubeconfig

1. In Kubernetes Engine, click the kubectl file button for your cluster.

2. In the pop-up window, click Download kubeconfig file to save the file locally.

3. Edit the downloaded kubeconfig file to configure access. Update the users > user > exec > env section with your access key ID and secret.

   users:
   - name: ${cluster-name}-admin
     user:
       exec:
         apiVersion: client.authentication.k8s.io/v1beta1
         args: null
         command: kic-iam-auth
         env:
         - name: "OS_AUTH_URL"
           value: "https://iam.kakaocloud.com/identity/v3"
         - name: "OS_AUTH_TYPE"
           value: "v3applicationcredential"
         - name: "OS_APPLICATION_CREDENTIAL_ID"
           value: "${access-key-id}"
         - name: "OS_APPLICATION_CREDENTIAL_SECRET"
           value: "${access-key-secret}"
         - name: "OS_REGION_NAME"
           value: "kr-central-2"

4. Copy the file to the default path used by kubectl:

   mkdir $HOME/.kube
   cp ${KUBECONFIG_FILE_PATH} $HOME/.kube/config

   Example: cp ~/Downloads/kubeconfig-cluster.yaml ~/.kube/config

Download and configure KakaoCloud authentication client

Download the KakaoCloud authentication client, grant execute permission, and move it to a directory in your PATH.

sudo chmod +x ${IAM_FILE_PATH}
mv ${IAM_FILE_PATH} /usr/local/bin

Name	Description
IAM_FILE_PATH	Path to the downloaded client file

Call Kubernetes API

Verify cluster connectivity using the following command:

kubectl get nodes

Step 3. Deploy service on Kubernetes

1. Create a secret to authenticate with the private Container Registry.

   Create Container Registry auth secret

   kubectl create secret docker-registry kc-cr-secret \
   --docker-server={PROJECT_NAME}.kr-central-2.kcr.dev \
   --docker-username={ACCESS_KEY} \
   --docker-password={ACCESS_SECRET_KEY}

   Field	Description
   PROJECT_NAME	KakaoCloud project name
   ACCESS_KEY	IAM access key
   ACCESS_SECRET_KEY	IAM access secret key

2. Deploy the server of the example project:

   Server deployment

   cat <<EOF | kubectl create -f-
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: server-deployment
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: server
     template:
       metadata:
         labels:
           app: server
       spec:
         containers:
         - name: server
           image: {PROJECT_NAME}.kr-central-2.kcr.dev/tutorial/kakaocloud-library-server:latest
           env:
           - name: PROFILE
             value: "local"
           ports:
           - containerPort: 8080
         imagePullSecrets:
         - name: kc-cr-secret
   EOF

3. Create a ClusterIP service for the server:

   Server service

   cat <<EOF | kubectl create -f-
   apiVersion: v1
   kind: Service
   metadata:
     name: server-service
   spec:
     type: ClusterIP
     selector:
       app: server
     ports:
     - protocol: TCP
       port: 8080
       targetPort: 8080
   EOF

4. Deploy the client of the example project:

   Client deployment

   cat <<EOF | kubectl create -f-
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: client-deployment
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: client
     template:
       metadata:
         labels:
           app: client
       spec:
         containers:
         - name: client
           image: {PROJECT_NAME}.kr-central-2.kcr.dev/tutorial/kakaocloud-library-client:latest
           env:
           - name: SERVER_ENDPOINT
             value: "http://server-service.default.svc.cluster.local:8080"
           ports:
           - containerPort: 80
         imagePullSecrets:
         - name: kc-cr-secret
   EOF

5. Create a LoadBalancer service for the client:

   Client service

   cat <<EOF | kubectl create -f-
   apiVersion: v1
   kind: Service
   metadata:
     name: client-service
   spec:
     type: LoadBalancer
     selector:
       app: client
     ports:
     - protocol: TCP
       port: 80
       targetPort: 80
   EOF

Step 4. Configure load balancer in the console

After deploying the client service as a LoadBalancer, you can see it listed under Load Balancer in the KakaoCloud console. Click More > Associate public IP to allow external access to the service.

Step 5. Verify service access

Open your browser and access the registered public IP. If everything is configured correctly, the "KakaoCloud Library" service screen will be displayed.