---
title: "Load Balancer instance integrations"
slug: "k8s-k8suse-loadbalancer"
tags: ["Load Balancer", "Ncloud Kubernetes Service", "Ncloud Kubernetes Service(VPC)"]
updated: 2026-09-17T09:33:15Z
published: 2026-09-17T09:33:15Z
canonical: "guide.ncloud-docs.com/k8s-k8suse-loadbalancer"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Load Balancer instance integrations

Available in VPC

When creating a service to use Ncloud Kubernetes Service, you can automatically create a Load Balancer instance integrated with the service.

## Manage Load Balancer instances integrated with Kubernetes

              Caution

              

- A Load Balancer created in Kubernetes on NAVER Cloud Platform is managed as a Kubernetes resource.
- If you edit a Load Balancer directly through the console or API, state synchronization with Kubernetes may not work correctly, which can cause unexpected issues. If you need to change Load Balancer settings, edit the Kubernetes resources instead.
- Technical support is not provided for issues caused by direct changes through the console or API.
- You cannot change the type of a Load Balancer after it is created.

### Create an instance

To create a Load Balancer instance integrated with Ncloud Kubernetes Service, set the service manifest type to LoadBalancer and the `service.beta.kubernetes.io/ncloud-load-balancer-layer-type` annotation to either nplb or nlb.

- nplb: Creates a Network Proxy Load Balancer (NPLB) instance.
- nlb: Creates a Network Load Balancer (NLB) instance.

### Configure instance properties

You can configure instance properties using annotations in the service manifest. To configure instance properties, set the metadata.annotations values according to the table below when creating the instance.

- Network Proxy Load Balancer (NPLB)

| Annotation | Description | Remarks |
| --- | --- | --- |
| `service.beta.kubernetes.io/ncloud-load-balancer-layer-type` | Sets the network layer type of the Load Balancer. - Select one of the following values: nplb, nlb | Default: nplb |
| `service.beta.kubernetes.io/ncloud-load-balancer-size` | Sets the load processing performance of the Load Balancer. - Select one of the following values: SMALL, MEDIUM, LARGE, XLARGE | Default: SMALL |
| `service.beta.kubernetes.io/ncloud-load-balancer-internal` | Configures whether to create a private network-type Load Balancer. - Select one of the following values: `"true"`, `"false"` | Default: `"false"` |
| `service.beta.kubernetes.io/ncloud-load-balancer-retain-public-ip-on-termination` | Configures whether to retain the allocated public IP when the Load Balancer is deleted. Applies only to Load Balancers with an assigned public IP. - Select one of the following values: `"true"`, `"false"` | Default: `"false"` |
| `service.beta.kubernetes.io/ncloud-load-balancer-description` | Enters a description for the Load Balancer instance to be created. | - |
| `service.beta.kubernetes.io/ncloud-load-balancer-termination-protection` | Configures whether to prevent automatic deletion of the Load Balancer when a service with type LoadBalancer is deleted. - Select one of the following values: `"true"`, `"false"` | Default: `"false"` |
| `service.beta.kubernetes.io/ncloud-load-balancer-subnet-id` | Specifies the ID of the subnet dedicated to Load Balancer creation. | Default: lbSubnetNo in the ConfigMap named ncloud-config in the kube-system |
| `service.beta.kubernetes.io/ncloud-load-balancer-ssl-certificate-no` | Specifies the certificate number from Certificate Manager to be applied to listeners using the TLS protocol. - The certificate number can be found in the Resource Manager nrn. (Example: nrn:PUB:CertificateManager::000:Certificate/External/${certificateNo}) | - |
| `service.beta.kubernetes.io/ncloud-load-balancer-tls-ports` | Specifies the list of ports to which TLS is applied. (Example: `"443,6443"`) | Default: `"443"`; comma-separated values supported |
| `service.beta.kubernetes.io/ncloud-load-balancer-tls-min-version` | Specifies the minimum supported TLS version type code. - Select one of the following values: TLSV10, TLSV11, TLSV12, TLSV13 | Default: TLSV10 |
| `service.beta.kubernetes.io/ncloud-load-balancer-proxy-protocol` | Configures whether to enable the proxy protocol. - Select one of the following values: `"true"`, `"false"` | Default: `"false"` |
| `service.beta.kubernetes.io/ncloud-load-balancer-algorithm-type-code` | Configures the load balancing algorithm type; select from Round Robin (RR), Source IP Hash (SIPHS), or Least Connection (LC). - Select one of the following values: RR, SIPHS, LC | Default: RR |
| `service.beta.kubernetes.io/ncloud-load-balancer-enable-skip-acg-update` | Configures whether to update ACG settings. - Select one of the following values: `"true"`, `"false"` | Default: `"false"` |
| `service.beta.kubernetes.io/ncloud-load-balancer-idle-timeout` | Sets the idle timeout of the Load Balancer (1-3600). | Default: 60 |
| `service.beta.kubernetes.io/ncloud-load-balancer-cipher-suite-list` | Specifies the list of cipher suites supported by the listener. (Example: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) | Default: All cipher suites supported by the listener |
| `service.beta.kubernetes.io/ncloud-load-balancer-listener-acl-id.{port}` | Specifies the ACL ID to be assigned to the listener. | - |
| `service.beta.kubernetes.io/ncloud-load-balancer-healthcheck-port.{port}` | Specifies the service port to be used for health checks for a specific listener port. | - |
| `service.beta.kubernetes.io/ncloud-load-balancer-healthcheck-interval-seconds.{port}` | Specify the health check interval in seconds for a specific listener port. | Default value if not specified: `30` |
| `service.beta.kubernetes.io/ncloud-load-balancer-healthy-threshold-count.{port}` | Specify the health check success threshold for a specific listener port. | Default value if not specified: `2` |
| `service.beta.kubernetes.io/ncloud-load-balancer-unhealthy-threshold-count.{port}` | Specify the health check failure threshold for a specific listener port. | Default value if not specified: `2` |

- Network Load Balancer (NLB)

| Annotation | Description | Remarks |
| --- | --- | --- |
| `service.beta.kubernetes.io/ncloud-load-balancer-layer-type` | Sets the network layer type of the Load Balancer. - Select one of the following values: nplb, nlb | Default: nplb - Enter nlb to create a Network Load Balancer. |
| `service.beta.kubernetes.io/ncloud-load-balancer-size` | Sets the load processing performance of the Load Balancer. - Select one of the following values: SMALL, MEDIUM, LARGE, DYNAMIC | Default: DYNAMIC - Only DYNAMIC can be set during creation. - For certain Load Balancers with non-DYNAMIC types, applying the DYNAMIC annotation changes the type to DYNAMIC. - Changing from DYNAMIC to another type is not supported. |
| `service.beta.kubernetes.io/ncloud-load-balancer-internal` | Configures whether to create a private network-type Load Balancer. - Select one of the following values: `"true"`, `"false"` | Default: `"false"` |
| `service.beta.kubernetes.io/ncloud-load-balancer-retain-public-ip-on-termination` | Configures whether to retain the allocated public IP when the Load Balancer is deleted. Applies only to Load Balancers with an assigned public IP. - Select one of the following values: `"true"`, `"false"` | Default: `"false"` |
| `service.beta.kubernetes.io/ncloud-load-balancer-description` | Enters a description for the Load Balancer instance to be created. | - |
| `service.beta.kubernetes.io/ncloud-load-balancer-termination-protection` | Configures whether to prevent automatic deletion of the Load Balancer when a service with type LoadBalancer is deleted. - Select one of the following values: `"true"`, `"false"` | Default: `"false"` |
| `service.beta.kubernetes.io/ncloud-load-balancer-inbound-source` | Specifies the value to be used as the inbound source for ACG rules. - Example: 119.194.195.143/32,143.248.12.77/32 | Default: 0.0.0.0/0 |
| `service.beta.kubernetes.io/ncloud-load-balancer-subnet-id` | Specifies the ID of the subnet dedicated to Load Balancer creation. | Default: lbSubnetNo in the ConfigMap named ncloud-config in the kube-system namespace |
| `service.beta.kubernetes.io/ncloud-load-balancer-algorithm-type-code` | Configures the load balancing algorithm type; select from Hash (MH) or Round Robin (RR). - Select one of the following values: MH, RR | Default: MH |
| `service.beta.kubernetes.io/ncloud-load-balancer-enable-skip-acg-update` | Configures whether to update ACG settings. - Select one of the following values: `"true"`, `"false"` | Default: `"false"` |
| `service.beta.kubernetes.io/ncloud-load-balancer-sticky-session` | Configures whether to enable sticky sessions. - Select one of the following values: `"true"`, `"false"` | Default: `"false"` |
| `service.beta.kubernetes.io/ncloud-load-balancer-listener-acl-id.{port}` | Specifies the ACL ID to be assigned to the listener. | - |
| `service.beta.kubernetes.io/ncloud-load-balancer-healthcheck-port.{port}` | Specifies the service port to be used for health checks for a specific listener port. | - |
| `service.beta.kubernetes.io/ncloud-load-balancer-healthcheck-interval-seconds.{port}` | Specify the health check interval in seconds for a specific listener port. | Default value if not specified: `30` |
| `service.beta.kubernetes.io/ncloud-load-balancer-healthy-threshold-count.{port}` | Specify the health check success threshold for a specific listener port. | Default value if not specified: `2` |
| `service.beta.kubernetes.io/ncloud-load-balancer-unhealthy-threshold-count.{port}` | Specify the health check failure threshold for a specific listener port. | Default value if not specified: `2` |
| `service.beta.kubernetes.io/ncloud-load-balancer-enable-acl-operator` | Configures whether to delegate ACL-related features to the ACL operator. When enabled, built-in ACL features are disabled. - Select one of the following values: `"true"`, `"false"` | Default: `"false"` |

#### Public and private IP assignment methods based on the Load Balancer subnet type

There are two types of Load Balancer subnets: **Public Subnet** and **Private Subnet**. Each type is required to create a Load Balancer with a public IP address or private IP address, respectively.

When a load balancer is created, the subnet IDs in the `lbPublicSubnetNo` and `lbSubnetNo` fields defined in the ncloud-config ConfigMap in the kube-system namespace are used. To use a different subnet, specify the desired subnet ID in the `service.beta.kubernetes.io/ncloud-load-balancer-subnet-id` annotation.

**1. Public Subnet (for Internet gateway only)** A Public Subnet is required to create a Load Balancer with a public IP address. In the VPC environment of the NAVER Cloud Platform console, navigate to **Menu** > **All Services** > **Networking** > **VPC** > **Public IP** to request a public IP address, and then assign it to the Load Balancer. If you do not specify a public IP, a new one is automatically requested.

**2. Private Subnet** A Private Subnet is required to create a Load Balancer with a private IP assigned within a VPC.

#### Specify multi-zone subnet IDs

When creating a Network Proxy Load Balancer (NPLB) in a multi-zone cluster, you can specify a dedicated load balancer subnet ID for each zone in the `service.beta.kubernetes.io/ncloud-load-balancer-subnet-id` annotation. When specifying NPLB subnet IDs in a multi-zone cluster, note the following:

- Separate multiple subnet IDs with commas (,).
- Only 1 dedicated load balancer subnet can be specified for each zone.
- Load balancer creation fails if 2 or more subnet IDs belonging to the same zone are specified.
- `subnet-id` value is applied only when the load balancer is created. To change the subnets of an existing load balancer, recreate the load balancer.
- Multi-zone subnet configuration is supported only for NPLBs. Network Load Balancers (NLBs) do not support multi-zone subnet configuration.
- When multi-zone subnets are specified, a public IP address cannot be assigned.

```
metadata:
  annotations:
    service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nplb"
    service.beta.kubernetes.io/ncloud-load-balancer-subnet-id: "123456,234567"
```

### Examples of configuring instance properties

For detailed examples of configuring instance properties, see [Load Balancer property configuration examples](/docs/en/k8s-k8sexamples-loadbalancer).

### Check the external IP of the created Load Balancer instance

To check the external IP of the created instance, run the following command:

```
$ kubectl --kubeconfig $KUBE_CONFIG get svc example-service
```

The external IP of the instance is displayed in the EXTERNAL-IP column. The following is an example of viewing the external IP using the command above:

```
$ kubectl --kubeconfig $KUBE_CONFIG get svc example-service
NAME              TYPE           CLUSTER-IP       EXTERNAL-IP    PORT(S)          AGE
example-service   LoadBalancer   172.16.101.104   10.39.10.118   8765:30365/TCP   2m11s
```

### Pause Load Balancer management

`lb.ncloud.naver.com/pause: "true"` is a pause option available for KVM clusters running Kubernetes 1.36 or later. When this value is set, the controller's spec/provider reconciliation is paused.

| Applies to | Behavior |
| --- | --- |
| Service | - While paused, changes to the Service are not reflected in the Load Balancer settings. - Deleting the Service while paused does not delete existing Ncloud LB/TG resources, and they are retained. |
| Deleting the Service | - If pause is set, the `service.kubernetes.io/load-balancer-cleanup` finalizer is removed without waiting for NCloud LB/TG cleanup. |

              Caution

              

The pause option is intended to preserve existing Ncloud LB/TG resources. While paused, missing Load Balancer resources are not newly created. To resume applying changes, remove the pause annotation from the input resource.

### Delete an instance

Deleting a Kubernetes Service created with type LoadBalancer also automatically deletes the integrated Load Balancer instance. To delete a registry:

1. Run the following command to check the created Kubernetes Service:

- You can check the type of each Service in the TYPE column of the results.

```
$ kubectl --kubeconfig $KUBE_CONFIG get service
```

1. Run the following command to delete the LoadBalancer type service:

```
$ kubectl --kubeconfig $KUBE_CONFIG delete service my-nginx
```