Legacy guide

End-of-support notice

The annotation method described in this guide is scheduled to reach end of support on December 31, 2026.

No new features or improvements will be provided for this method, and normal operation is not guaranteed after the end-of-support date.

To use the new annotation method, you must create a new Service and load balancer. Before support ends, follow the current guide, verify the behavior of the new resources, and then migrate traffic.

A load balancer distributes large volumes of incoming traffic across multiple servers, ensuring stable service operation.
In the Kubernetes Engine service, depending on the annotation options used when creating a service of type LoadBalancer, a Network Load Balancer (NLB) or an Application Load Balancer (ALB) is created.

Create load balancer

Here is how to create a load balancer in the Kubernetes Engine service.

Create a load balancer in a multi-AZ cluster

To ensure high availability across multiple Availability Zones (AZ), you can configure a cluster network across different AZs.
When creating a load balancer in a multi-AZ cluster, a load balancer is automatically created in each AZ that is part of the cluster network.

:::caution
Even if a node pool in a multi-AZ cluster is configured in only one AZ, load balancers are still created in all AZs. All load balancer types (NLB or ALB) are billable, so please consider this when deploying. :::

Prerequisites

Step 1. Install and configure kubectl

To create a Service object in Kubernetes, you need to install kubectl and configure access to your cluster.
For detailed instructions, refer to Configure kubectl control.

Step 2. Register and manage SSL certificates

If you're creating an Application Load Balancer (ALB) with the listener protocol set to TERMINATED_HTTPS, an SSL certificate is required.
You can register and manage SSL certificates as follows:

Register a certificate

1. Go to the KakaoCloud console > Management > Certificate Manager.

2. Select the [Register certificate] button in the Certificates menu.

3. Enter the required information in the popup window and select [Register].

4. Confirm that the certificate appears in the list.

Delete a certificate

1. Go to the KakaoCloud console > Management > Certificate Manager.

2. In the Certificates menu, select the [More] icon for the certificate and select Delete certificate.

3. Enter the required information in the popup and select [Delete].

4. Verify the certificate has been successfully deleted.

Step 1. Check service specifications for load balancer type

Review the YAML file for a service of type LoadBalancer associated with app: nginx, paying attention to:

Field	Description
spec.type	Value: LoadBalancer — required to create a load balancer
metadata.annotations	Set load balancer type loadbalancer.ke.kakaocloud.com/load-balancer-type: - NLB (default): Create a Network Load Balancer - ALB: Create an Application Load Balancer - Omit to default to NLB Set public IP usage service.beta.kubernetes.io/openstack-internal-load-balancer: - true (default): Use private IP - false: Use public IP

Example: NLB service spec

NLB service specification

kind: Service
apiVersion: v1
metadata:
  name: default-http-nginx-service
  annotations:
    service.beta.kubernetes.io/openstack-internal-load-balancer: 'true'
    loadbalancer.ke.kakaocloud.com/load-balancer-type: 'NLB'
spec:
  selector:
    app: nginx
  type: LoadBalancer
  ports:
    - name: http
      port: 80
      targetPort: 80

Example: ALB service spec

ALB service specification

kind: Service
apiVersion: v1
metadata:
  name: default-http-nginx-service
  annotations:
    service.beta.kubernetes.io/openstack-internal-load-balancer: 'true'
    loadbalancer.ke.kakaocloud.com/load-balancer-type: 'ALB'
    loadbalancer.openstack.org/default-tls-container-ref: 'https://key-manager.{region certificate path}/v1/secrets/{certificate ID}'
spec:
  selector:
    app: nginx
  type: LoadBalancer
  ports:
    - name: https
      port: 443
      targetPort: 443

Step 2. Set load balancer type

Create 'Network Load Balancer (NLB)'

By default, creating a LoadBalancer-type service in Kubernetes Engine will provision a Network Load Balancer (NLB), operating at OSI Layer 4.

Annotation	Value
loadbalancer.ke.kakaocloud.com/load-balancer-type	Set to "NLB"

Create 'Application Load Balancer (ALB)'

You can create an Application Load Balancer (ALB) to handle traffic at OSI Layer 7.

Annotation	Value
loadbalancer.ke.kakaocloud.com/load-balancer-type	Set to "ALB"
loadbalancer.openstack.org/default-tls-container-ref	Sets the listener protocol to TERMINATED_HTTPS and requires an SSL certificate - Enter "https://key-manager.kr-central-2.kakaoi.io/v1/secrets/{certificate UUID}" - Enter the certificate ID in the {certificate UUID} field - Register the certificate first in Certificate Manager to obtain its ID - If no certificate is applied to the ALB, the listener protocol is set to HTTP

info

• Annotation paths for certificates vary by region. Use the appropriate path for your load balancer’s region.
• Certificate annotations must be set when the ALB is initially created.
• To change certificate settings, delete and recreate the Service object. The existing load balancer is detached or deleted before a new load balancer is created.

Step 3. Configure public IP for the load balancer

Set the annotation service.beta.kubernetes.io/openstack-internal-load-balancer to determine public IP usage.

• true (default): Use private IP
• false: Use public IP

caution

• Depending on the value of service.beta.kubernetes.io/openstack-internal-load-balancer, a new public IP is created and attached to the load balancer or the existing public IP is detached. If a public IP was used when the value was false, changing the value to true only detaches the public IP. The detached public IP remains billable.
• To delete a public IP used by a Kubernetes Engine load balancer, go to KakaoCloud console > VPC > Public IP. For more information, see Create and manage public IPs.

Appendix. Configure detailed load balancer options

You can specify advanced options in the annotations section of the YAML file:

Option	Description
loadbalancer.ke.kakaocloud.com/delete-floatingip	On deletion of load balancer: - true: Also deletes associated public IP - false (default): Detaches public IP but does not delete
loadbalancer.openstack.org/health-monitor-timeout	Max response time for health check (in seconds) Default: 30
loadbalancer.openstack.org/health-monitor-delay	Interval between health checks (in seconds), must be greater than timeout Default: 60
loadbalancer.openstack.org/health-monitor-max-retries	Max retries for failed health checks Default: 5 Must be between 1–10

Appendix. Example: Create NLB load balancer service

Here is an example for deploying a basic Nginx app using a LoadBalancer-type service.

Nginx LoadBalancer service example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: internal-http-nginx-deployment
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        ports:
        - containerPort: 80
---
kind: Service
apiVersion: v1
metadata:
  name: default-http-nginx-service
  annotations:
    service.beta.kubernetes.io/openstack-internal-load-balancer: "true"
    loadbalancer.ke.kakaocloud.com/load-balancer-type: "NLB"
spec:
  selector:
    app: nginx
  type: LoadBalancer
  ports:
  - name: http
    port: 80
    targetPort: 80

1. Apply the deployment using the following command. Load balancer creation may take up to 5 minutes.

   Deploy

   kubectl --kubeconfig=$KUBE_CONFIG apply -f https://raw.githubusercontent.com/kakaoenterprise/kakaocloud-tutorials/refs/heads/k8se-public-guides/createLB/lb-nginx.yml

2. To verify the load balancer’s external IP:

   Check EXTERNAL-IP

   kubectl --kubeconfig=$KUBE_CONFIG get svc default-http-nginx-service

   Example output

   NAME                         TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)        AGE
   default-http-nginx-service   LoadBalancer   {CLUSTER-IP}   {EXTERNAL-IP}   80:32245/TCP   7h15m

3. Confirm traffic is received at the EXTERNAL-IP:

   Check traffic

   curl {EXTERNAL-IP}

   Example response

   <!doctype html>
   <html>
     <head><title>Welcome to nginx!</title></head>
     <body>
       <h1>Welcome to nginx!</h1>
       <p>
         If you see this page, the nginx web server is successfully installed
         and working. Further configuration is required.
       </p>
   
       <p>
         For online service and support please refer to
         <a href="http://nginx.org/">nginx.org</a>.<br/>
         Commercial support is available at
         <a href="http://nginx.com/">nginx.com</a>.
       </p>
   
       <p><em>Thank you for using nginx.</em></p>
     </body>
   </html>

info

• If you set service.beta.kubernetes.io/openstack-internal-load-balancer to false, a public IP is assigned and shown in the EXTERNAL-IP column.
• When using DNS, the EXTERNAL-IP field may show a domain name, and clients can access the load balancer using that DNS name.

Delete load balancer

You can delete load balancers that are no longer needed.
Deleting the Service object of type LoadBalancer will also delete the corresponding KakaoCloud load balancer.

Delete service

kubectl --kubeconfig=$KUBE_CONFIG delete svc default-http-nginx-service