Deploy Kubernetes cluster with 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 keys

Scenario overview

This tutorial walks you through the process of creating a Kubernetes cluster on KakaoCloud using Kubernetes Engine, and deploying a web service to the cluster.
You will pull a container image of a sample project from the Container Registry, deploy it as a service within the cluster, and configure a load balancer for external access.

The key steps include:

Create a Kubernetes cluster and node pool
Set up kubectl and authentication to access the cluster
Configure a secret to integrate with Container Registry
Deploy the sample application and setting up a load balancer
Verify external access via public IP

This scenario is designed as a basic deployment example for users who are starting with Kubernetes-based operations on KakaoCloud.

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:

Go to KakaoCloud console > Container Pack > Kubernetes Engine > Clusters and select Create cluster.
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
In the cluster list, select the created cluster and go to the Node pools tab, then select Create node pool.
Refer to the following configuration for the node pool:

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

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`

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
Linux (Ubuntu)

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"

Verify installation:
Check version
```
kubectl version --client
```

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"

Verify installation:
Check version
```
kubectl version --client
```

Download and configure kubeconfig

In Kubernetes Engine, select the kubectl file button for your cluster.
Select Download kubeconfig file to save the file locally.

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"

By default, kubectl accesses the cluster using the information stored in the $HOME/.kube/config file. Copy the configured kubeconfig file to the $HOME/.kube/config path.
```
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

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

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

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

Name	Description
PROJECT_NAME	Name of the project in KakaoCloud console where the Container Registry was created

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

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

Name	Description
PROJECT_NAME	Name of the project in KakaoCloud Console where the Container Registry was created

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. Select 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.

Scenario overview​

Before you start​

1. Set up network environment​

2. Deploy example project container image​

Getting started​

Step 1. Create Kubernetes cluster​

Step 2. Call Kubernetes API with kubectl​

Install kubectl​

Download and configure kubeconfig​

Download and configure KakaoCloud authentication client​

Call Kubernetes API​

Step 3. Deploy service on Kubernetes​

Step 4. Configure load balancer in the console​

Step 5. Verify service access​