Create and manage load balancers

A load balancer receives client requests and distributes traffic across multiple servers. It is a core technology for avoiding problems that can occur when a single server handles every request.

In Kubernetes Engine, you can create and manage a load balancer by declaring Service.type=LoadBalancer and configuring spec.loadBalancerClass. Depending on the configured value, a Network Load Balancer (NLB) or Application Load Balancer (ALB) is created automatically.

Availability from August 25, 2026

This guide applies to Kubernetes Engine Services that use spec.loadBalancerClass and loadbalancer.kakaocloud.com/* annotations. These features are supported only on clusters running v1.30 or later.

• Specify the load balancer type with spec.loadBalancerClass.
• Use only loadbalancer.kakaocloud.com/* annotations.
• If an existing cluster uses legacy annotations, see the legacy guide.

Create a load balancer

Scope

The protocols, annotations, and restrictions described in this guide apply to Kubernetes Engine Service integration.
They can differ from the full feature set of the KakaoCloud Load Balancing service.

Use the following procedure to create a load balancer in Kubernetes Engine.

caution

Load balancers created by Kubernetes Engine in the kr-central-2 region use a high-availability configuration. They are automatically distributed across all Availability Zones (AZs) included in the cluster network.

Even if workloads run in only some AZs, resources are allocated for the load balancer across all AZs. Load balancers created in each AZ are billable.

Prerequisites

Step 1. Install and configure kubectl

To create a Service object in Kubernetes, install kubectl and configure access to the cluster.
For instructions, see Configure kubectl.

Step 2. Register and manage SSL certificates (optional)

To terminate TLS on an ALB or NLB, configure loadbalancer.kakaocloud.com/tls-container-refs and register the SSL certificate first. Register or delete certificates in Management > Certificate Manager, and then specify the generated certificate ID in tls-container-refs.

Register a certificate

1. In the KakaoCloud console, go to Management > Certificate Manager.
2. On the Certificates page, select [Register certificate].
3. Enter the required information, and then select [Register].
4. Verify the registered certificate in the certificate list.

Delete a certificate

1. In the KakaoCloud console, go to Management > Certificate Manager.
2. On the Certificates page, select [More] for the certificate, and then select Delete certificate.
3. Enter the required information, and then select [Delete].
4. Verify that the certificate was removed from the list.

Step 1. Check the Service specification

The following fields are required to create a load balancer.

Field	Value
spec.type	LoadBalancer
spec.loadBalancerClass	loadbalancer.kakaocloud.com/nlb or loadbalancer.kakaocloud.com/alb
metadata.annotations	Use the loadbalancer.kakaocloud.com/* format

NLB Service specification

NLB Service specification

kind: Service
apiVersion: v1
metadata:
  name: my-nlb-service
  annotations:
    loadbalancer.kakaocloud.com/load-balancer-scheme: 'internal'
spec:
  loadBalancerClass: loadbalancer.kakaocloud.com/nlb
  selector:
    app: myApp
  type: LoadBalancer
  ports:
    - name: http
      protocol: TCP
      port: 80
      targetPort: 80

ALB Service specification

ALB Service specification

kind: Service
apiVersion: v1
metadata:
  name: my-alb-service
  annotations:
    loadbalancer.kakaocloud.com/load-balancer-scheme: 'internal'
    loadbalancer.kakaocloud.com/tls-container-refs: 'https://key-manager.{region}/v1/secrets/{secret-id}'
spec:
  loadBalancerClass: loadbalancer.kakaocloud.com/alb
  selector:
    app: myApp
  type: LoadBalancer
  ports:
    - name: https
      port: 443
      targetPort: 443

Step 2. Select the load balancer type

Specify the load balancer type with spec.loadBalancerClass.

caution

You cannot change spec.loadBalancerClass after creating a Service. To change an existing LoadBalancer Service from NLB to ALB or vice versa, create a new Service with the required spec.loadBalancerClass value.

Type	Value	Description
NLB	loadbalancer.kakaocloud.com/nlb	L4 load balancer for TCP- or UDP-based services. When tls-container-refs is set, a TLS listener and TCP target group are created.
ALB	loadbalancer.kakaocloud.com/alb	L7 load balancer that uses HTTP by default. When tls-container-refs is set, an HTTPS listener and HTTP target group are created.

info

• For tls-container-refs, enter a certificate path in the format https://key-manager.{region}/v1/secrets/{secret-id}.
• An ALB without a certificate uses an HTTP listener. An NLB uses a TCP or UDP listener according to the Service protocol.

Step 3. Configure public exposure

Use loadbalancer.kakaocloud.com/load-balancer-scheme to configure an internal or internet-facing load balancer.

Annotation	Value	Description
loadbalancer.kakaocloud.com/load-balancer-scheme	internal	Internal load balancer that uses private addresses (default)
loadbalancer.kakaocloud.com/load-balancer-scheme	internet-facing	External load balancer that can be publicly exposed

caution

When you set internet-facing, a new public IP is created and attached to the load balancer.
You cannot change internet-facing or internal after creation. If you used the wrong value, create a new Service with the correct setting, migrate traffic, and then delete the old Service.

If loadbalancer.kakaocloud.com/delete-floatingip is omitted or set to false, the public IP remains detached after Service deletion and can continue to incur charges.

Step 4. Create and check the Service

Apply the YAML file, and then check the Service status.

Create the Service

kubectl --kubeconfig=$KUBE_CONFIG apply -f {SERVICE_YAML_FILE}

Check the Service status

kubectl --kubeconfig=$KUBE_CONFIG get svc {SERVICE_NAME}

Check detailed Service events

kubectl --kubeconfig=$KUBE_CONFIG describe svc {SERVICE_NAME}

• Creating the load balancer can take several minutes. While creation is in progress, EXTERNAL-IP can display Pending or an IP address can appear before creation completes.
• Even if EXTERNAL-IP has a value, requests might fail while the load balancer or high-availability group is in the Creating state.
• You can inspect the load balancer and high-availability group in the console. Traffic can be handled normally after all related resources enter the Active state.

Protocol mapping and restrictions

Supported protocol combinations

The following combinations are supported for Kubernetes Engine Service integration.

LB type	Listener protocol	Target group protocol
ALB	HTTP	HTTP
ALB	HTTPS (TERMINATED_HTTPS)	HTTP
NLB	TCP	TCP
NLB	TCP	PROXY
NLB	UDP	UDP
NLB	TLS (TERMINATED_HTTPS)	TCP

Appendix

Complete annotation list

Configuration and management

• Disabling health monitoring: Setting enable-health-monitor=false is not recommended in production because traffic can continue to be sent to unhealthy nodes.
• Configuration reconciliation: If you directly change a setting controlled by the Service spec or annotations in the console, a Kubernetes resource change or controller reconciliation can restore the value defined in the Service. Make changes through the Kubernetes resource.
• Mixing annotations: Mixing ALB-only and NLB-only annotations can prevent normal operation.
• Traffic loss: A delay between pod termination and load balancer or service endpoint updates can cause temporary traffic loss. The effect can be greater with externalTrafficPolicy: Local because external traffic is sent only to node-local endpoints. Configure a preStop hook and sufficient terminationGracePeriodSeconds to allow draining before termination. The recommended wait time is at least the LB health check propagation time (health-monitor-delay × health-monitor-max-retries). For more information, see the Kubernetes documentation.

The following loadbalancer.kakaocloud.com/* annotations are available on current-version clusters.

Notation

Select a Details link to review the supported values, defaults, and considerations for an annotation.

Complete annotation list

Scope	Annotation	Description	Details
ALB	x-forwarded-for	Configure client IP forwarding	Details
ALB	x-forwarded-port	Add the client port header	Details
ALB	x-forwarded-proto	Add the client protocol header	Details
NLB	proxy-protocol	Forward client information in a PROXY header	Details
Common	tls-container-refs	Configure certificates for TLS termination	Details
Common	tls-minimum-version	Set the minimum TLS version	Details
Common	load-balancer-scheme	Configure an internal or external load balancer	Details
Common	delete-floatingip	Delete the public IP with the Service	Details
Common	enable-health-monitor	Enable health checks	Details
Common	health-monitor-http-version	Set the health check HTTP version	Details
Common	health-monitor-protocol	Set the health check protocol	Details
Common	health-monitor-delay	Set the health check interval	Details
Common	health-monitor-timeout	Set the health check timeout	Details
Common	health-monitor-max-retries	Set successful health check retries	Details
Common	health-monitor-max-retries-down	Set failed health check retries	Details
Common	health-monitor-url-path	Set the HTTP/HTTPS health check path	Details
Common	health-monitor-http-method	Set the health check method	Details
Common	health-monitor-expected-code	Set the expected response status code	Details
Common	timeout-client-data	Set the client idle timeout	Details
Common	timeout-member-data	Set the member idle timeout	Details
Common	load-balancer-subnet-ids	Select load balancer subnets	Details
Common	blb-name	Set the high-availability group name	Details
Common	node-selector	Filter load balancer member nodes	Details
Common	lb-method	Set the target group traffic distribution algorithm	Details

---

ALB-only annotations

x-forwarded-for

Field	Details
Annotation	loadbalancer.kakaocloud.com/x-forwarded-for
Description	Configures how client IPs are handled in the X-Forwarded-For header.
Values/default	"append" / "preserve" / "remove"; default: "append"
Changes/notes	Can be changed after Service creation.

x-forwarded-port

Field	Details
Annotation	loadbalancer.kakaocloud.com/x-forwarded-port
Description	Configures whether to add the client connection port to the X-Forwarded-Port header.
Values/default	"true" / "false"; default: "false"
Changes/notes	Can be changed after Service creation.

x-forwarded-proto

Field	Details
Annotation	loadbalancer.kakaocloud.com/x-forwarded-proto
Description	Configures whether to add the client connection protocol to the X-Forwarded-Proto header.
Values/default	"true" / "false"; default: "false"
Changes/notes	Can be changed after Service creation.

---

NLB-only annotations

proxy-protocol

Field	Details
Annotation	loadbalancer.kakaocloud.com/proxy-protocol
Description	Forwards the original client IP and port in a PROXY header.
Values/default	"true" / "false"; no default
Changes/notes	Cannot be changed after Service creation. Create a new Service to change it.

---

Common annotations

tls-container-refs

Field	Details
Annotation	loadbalancer.kakaocloud.com/tls-container-refs
Description	Specifies certificates for TLS termination on an ALB or NLB.
Values/default	"https://key-manager.{region}/v1/secrets/{secret-id}"; no default
Changes/notes	Only an annotation specified at Service creation can be updated; adding or removing it later is not supported. Specify up to six unique certificates, separated by commas. The first is the default certificate and the others are optional certificates. Configuring it at creation is recommended.

tls-minimum-version

Field	Details
Annotation	loadbalancer.kakaocloud.com/tls-minimum-version
Description	Sets the minimum TLS version allowed for connections.
Values/default	"TLSv1" / "TLSv1.1" / "TLSv1.2" / "TLSv1.3"; default: "TLSv1.3"
Changes/notes	Can be changed after Service creation. Applies to an ALB or NLB that terminates TLS.

load-balancer-scheme

Field	Details
Annotation	loadbalancer.kakaocloud.com/load-balancer-scheme
Description	Configures an internal or external load balancer.
Values/default	"internal" / "internet-facing"; default: "internal"
Changes/notes	Cannot be changed after Service creation. Create a new Service to change it.

delete-floatingip

Field	Details
Annotation	loadbalancer.kakaocloud.com/delete-floatingip
Description	Configures whether to delete the attached public IP when the Service is deleted.
Values/default	"true" / "false"; default: "false"
Changes/notes	Can be changed after Service creation and takes effect on deletion. Valid only for an internet-facing load balancer.

enable-health-monitor

Field	Details
Annotation	loadbalancer.kakaocloud.com/enable-health-monitor
Description	Enables or disables health checks.
Values/default	"true" / "false"; default: "true"
Changes/notes	Can be changed after Service creation. false is not recommended in production because traffic can continue to be sent to unhealthy nodes.

health-monitor-http-version

Field	Details
Annotation	loadbalancer.kakaocloud.com/health-monitor-http-version
Description	Sets the HTTP version used for health checks.
Values/default	"1.1" / "1.0"; no default
Changes/notes	Can be changed after Service creation.

health-monitor-protocol

Field	Details
Annotation	loadbalancer.kakaocloud.com/health-monitor-protocol
Description	Sets the health check protocol.
Values/default	"TCP" / "HTTP" / "HTTPS" / "PING" / "UDP-CONNECT"; default: "HTTP"
Changes/notes	Can be changed after Service creation. Changing it deletes the existing health monitor and creates a new one. A non-default protocol can cause traffic loss during node scale-in.

health-monitor-delay

Field	Details
Annotation	loadbalancer.kakaocloud.com/health-monitor-delay
Description	Sets the health check interval in seconds.
Values/default	Integer; default: "5"
Changes/notes	Can be changed after Service creation. Must be greater than or equal to health-monitor-timeout.

health-monitor-timeout

Field	Details
Annotation	loadbalancer.kakaocloud.com/health-monitor-timeout
Description	Sets the health check timeout in seconds.
Values/default	Integer; default: "5"
Changes/notes	Can be changed after Service creation. Must be less than or equal to health-monitor-delay.

health-monitor-max-retries

Field	Details
Annotation	loadbalancer.kakaocloud.com/health-monitor-max-retries
Description	Sets the number of successful retries required for a state transition.
Values/default	Integer; default: "1"
Changes/notes	Can be changed after Service creation.

health-monitor-max-retries-down

Field	Details
Annotation	loadbalancer.kakaocloud.com/health-monitor-max-retries-down
Description	Sets the number of failed health checks required for a state transition.
Values/default	Integer; default: "6"
Changes/notes	Can be changed after Service creation.

health-monitor-url-path

Field	Details
Annotation	loadbalancer.kakaocloud.com/health-monitor-url-path
Description	Sets the health check path.
Values/default	String; default: "/healthz"
Changes/notes	Can be changed after Service creation. Applies only when the protocol is HTTP or HTTPS.

health-monitor-http-method

Field	Details
Annotation	loadbalancer.kakaocloud.com/health-monitor-http-method
Description	Sets the health check method.
Values/default	"GET" / "HEAD" / "OPTIONS" / "POST" / "PUT" / "TRACE" / "PATCH" / "DELETE" / "CONNECT"; default: "GET"
Changes/notes	Can be changed after Service creation. Applies only when the protocol is HTTP or HTTPS.

health-monitor-expected-code

Field	Details
Annotation	loadbalancer.kakaocloud.com/health-monitor-expected-code
Description	Sets the expected response status code for a health check.
Values/default	Integer from 100 through 999; default: "200"
Changes/notes	Can be changed after Service creation. Applies only when the protocol is HTTP or HTTPS.

timeout-client-data

Field	Details
Annotation	loadbalancer.kakaocloud.com/timeout-client-data
Description	Sets the idle timeout between the client and load balancer.
Values/default	Integer from 1000 through 4000000 ms; default: "50000"
Changes/notes	Can be changed after Service creation.

timeout-member-data

Field	Details
Annotation	loadbalancer.kakaocloud.com/timeout-member-data
Description	Sets the idle timeout between the load balancer and member.
Values/default	Integer from 1000 through 4000000 ms; default: "50000"
Changes/notes	Can be changed after Service creation.

load-balancer-subnet-ids

Field	Details
Annotation	loadbalancer.kakaocloud.com/load-balancer-subnet-ids
Description	Specifies the subnets in which the load balancer is created.
Values/default	Comma-separated subnet IDs such as "{subnet-id}"; no default
Changes/notes	Applied only at Service creation. Later changes do not affect the existing load balancer. When multiple subnets are specified, the first subnet for each AZ takes priority. For an unspecified AZ, a subnet from the cluster configuration is selected automatically.

blb-name

Field	Details
Annotation	loadbalancer.kakaocloud.com/blb-name
Description	Sets the high-availability group name.
Values/default	String of 4–26 alphanumeric characters and hyphens; no default
Changes/notes	Applied only at Service creation and only in regions that support high-availability groups. Later changes do not affect the existing load balancer.

node-selector

Field	Details
Annotation	loadbalancer.kakaocloud.com/node-selector
Description	Filters nodes used as load balancer target group members.
Values/default	List of key or key=value expressions; no default
Changes/notes	Can be changed after Service creation. Reconfiguring members can temporarily affect traffic. Only nodes whose labels include every specified expression are used.

lb-method

Field	Details
Annotation	loadbalancer.kakaocloud.com/lb-method
Description	Sets the target group traffic distribution algorithm.
Values/default	"ROUND_ROBIN" / "SOURCE_IP" / "LEAST_CONNECTIONS"; no default
Changes/notes	Can be changed after Service creation. Applying the target group change can temporarily affect traffic.

Kubernetes Service annotation changes

caution

Current-version clusters do not support legacy annotations. When creating or updating a Service, use the current annotations in the following table.

Feature	Legacy annotation	Current annotation
LB type	loadbalancer.ke.kakaocloud.com/load-balancer-type	Cannot be set with an annotation. Use spec.loadBalancerClass (loadbalancer.kakaocloud.com/nlb or loadbalancer.kakaocloud.com/alb).
Public IP usage	service.beta.kubernetes.io/openstack-internal-load-balancer	loadbalancer.kakaocloud.com/load-balancer-scheme
TLS certificate	loadbalancer.openstack.org/default-tls-container-ref	loadbalancer.kakaocloud.com/tls-container-refs
X-Forwarded-For	loadbalancer.openstack.org/x-forwarded-for	loadbalancer.kakaocloud.com/x-forwarded-for
Proxy Protocol	loadbalancer.openstack.org/proxy-protocol	loadbalancer.kakaocloud.com/proxy-protocol
Client idle timeout	loadbalancer.openstack.org/timeout-client-data	loadbalancer.kakaocloud.com/timeout-client-data
Member idle timeout	loadbalancer.openstack.org/timeout-member-data	loadbalancer.kakaocloud.com/timeout-member-data
Health checks	loadbalancer.openstack.org/enable-health-monitor	loadbalancer.kakaocloud.com/enable-health-monitor
Health check delay, timeout, and retries	loadbalancer.openstack.org/health-monitor-*	loadbalancer.kakaocloud.com/health-monitor-*
LB algorithm	loadbalancer.openstack.org/lb-method	loadbalancer.kakaocloud.com/lb-method
Subnets	loadbalancer.ke.kakaocloud.com/load-balancer-subnet-ids	loadbalancer.kakaocloud.com/load-balancer-subnet-ids
High-availability group name	loadbalancer.ke.kakaocloud.com/blb-name	loadbalancer.kakaocloud.com/blb-name
Public IP deletion policy	loadbalancer.ke.kakaocloud.com/delete-floatingip	loadbalancer.kakaocloud.com/delete-floatingip

info

Do not use loadbalancer.ke.kakaocloud.com/*, loadbalancer.openstack.org/*, or service.beta.kubernetes.io/openstack-internal-load-balancer on current-version clusters.

All-options examples

NLB (all options)

NLB all-options example

kind: Service
apiVersion: v1
metadata:
  name: my-nlb-service
  annotations:
    loadbalancer.kakaocloud.com/load-balancer-scheme: 'internet-facing'
    loadbalancer.kakaocloud.com/tls-container-refs: 'https://key-manager.kr-central-2.kakaoi.io/v1/secrets/bf89955a-98b2-4cd0-b103-29607c570df1'
    loadbalancer.kakaocloud.com/tls-minimum-version: 'TLSv1.3'
    loadbalancer.kakaocloud.com/delete-floatingip: 'true'
    loadbalancer.kakaocloud.com/proxy-protocol: 'v1'
    loadbalancer.kakaocloud.com/enable-health-monitor: 'true'
    loadbalancer.kakaocloud.com/health-monitor-http-version: '1.1'
    loadbalancer.kakaocloud.com/health-monitor-protocol: 'http'
    loadbalancer.kakaocloud.com/health-monitor-http-method: 'GET'
    loadbalancer.kakaocloud.com/health-monitor-expected-code: '200'
    loadbalancer.kakaocloud.com/health-monitor-url-path: '/healthz'
    loadbalancer.kakaocloud.com/health-monitor-delay: '600'
    loadbalancer.kakaocloud.com/health-monitor-timeout: '300'
    loadbalancer.kakaocloud.com/health-monitor-max-retries: '10'
    loadbalancer.kakaocloud.com/health-monitor-max-retries-down: '6'
    loadbalancer.kakaocloud.com/timeout-client-data: '10000'
    loadbalancer.kakaocloud.com/timeout-member-data: '10000'
    loadbalancer.kakaocloud.com/node-selector: 'env,foo=bar'
    loadbalancer.kakaocloud.com/lb-method: 'ROUND_ROBIN'
    loadbalancer.kakaocloud.com/load-balancer-subnet-ids: 'subnet-id1,subnet-id2'
spec:
  loadBalancerClass: 'loadbalancer.kakaocloud.com/nlb'
  type: LoadBalancer
  selector:
    app: myApp
  ports:
    - name: http
      protocol: TCP
      port: 80
      targetPort: 80

ALB (all options)

ALB all-options example

kind: Service
apiVersion: v1
metadata:
  name: my-alb-service
  annotations:
    loadbalancer.kakaocloud.com/load-balancer-scheme: 'internet-facing'
    loadbalancer.kakaocloud.com/x-forwarded-for: 'true'
    loadbalancer.kakaocloud.com/x-forwarded-port: 'true'
    loadbalancer.kakaocloud.com/x-forwarded-proto: 'true'
    loadbalancer.kakaocloud.com/tls-container-refs: 'https://key-manager.kr-central-2.kakaoi.io/v1/secrets/bf89955a-98b2-4cd0-b103-29607c570df1,https://key-manager.kr-central-2.kakaoi.io/v1/secrets/650819f7-49dc-4cca-ad09-062d26359bab'
    loadbalancer.kakaocloud.com/tls-minimum-version: 'TLSv1.3'
    loadbalancer.kakaocloud.com/delete-floatingip: 'true'
    loadbalancer.kakaocloud.com/enable-health-monitor: 'true'
    loadbalancer.kakaocloud.com/health-monitor-http-version: '1.1'
    loadbalancer.kakaocloud.com/health-monitor-protocol: 'http'
    loadbalancer.kakaocloud.com/health-monitor-http-method: 'GET'
    loadbalancer.kakaocloud.com/health-monitor-expected-code: '200'
    loadbalancer.kakaocloud.com/health-monitor-url-path: '/healthz'
    loadbalancer.kakaocloud.com/health-monitor-delay: '600'
    loadbalancer.kakaocloud.com/health-monitor-timeout: '300'
    loadbalancer.kakaocloud.com/health-monitor-max-retries: '10'
    loadbalancer.kakaocloud.com/health-monitor-max-retries-down: '6'
    loadbalancer.kakaocloud.com/timeout-client-data: '10000'
    loadbalancer.kakaocloud.com/timeout-member-data: '10000'
    loadbalancer.kakaocloud.com/node-selector: 'env,foo=bar'
    loadbalancer.kakaocloud.com/lb-method: 'ROUND_ROBIN'
    loadbalancer.kakaocloud.com/load-balancer-subnet-ids: 'subnet-id1,subnet-id2'
spec:
  loadBalancerClass: 'loadbalancer.kakaocloud.com/alb'
  type: LoadBalancer
  selector:
    app: myApp
  ports:
    - name: http
      port: 80
      targetPort: 80

Delete a LoadBalancer-type Service

Deleting a Service of type LoadBalancer also deletes the associated load balancer.

Delete the Service

kubectl --kubeconfig=$KUBE_CONFIG delete svc {SERVICE_NAME}

• If loadbalancer.kakaocloud.com/delete-floatingip is "false", the public IP is detached when the load balancer is deleted.
• If loadbalancer.kakaocloud.com/delete-floatingip is "true", the attached public IP is deleted with the load balancer.
• An internal load balancer has no public IP, so delete-floatingip does not apply.