--- title: "Load Balancer 인스턴스 연동" slug: "k8s-k8suse-loadbalancer" tags: ["load balancer", "Ncloud Kubernetes Service 기능사용", "Ncloud Kubernetes Service 사용", "Ncloud Kubernetes Service(VPC)"] updated: 2026-08-20T09:03:25Z published: 2026-08-20T09:03:25Z canonical: "guide-gov.ncloud-docs.com/k8s-k8suse-loadbalancer" --- > ## Documentation Index > Fetch the complete documentation index at: https://guide-gov.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # Load Balancer 인스턴스 연동 VPC 환경에서 이용 가능합니다. Ncloud Kubernetes Service를 이용하기 위해 서비스를 생성할 때, 해당 서비스와 연동되는 Load Balancer 인스턴스를 자동으로 생성할 수 있습니다. ## Kubernetes에 연동되는 Load Balancer 인스턴스 관리 주의 - Kubernetes에서 생성된 네이버 클라우드 플랫폼의 Load Balancer는 Kubernetes의 리소스로 관리됩니다. - Load Balancer를 콘솔 또는 API를 통해 직접 수정할 경우 Kubernetes와 상태 동기화가 정상적으로 이루어지지 않아 예기치 않은 문제가 발생할 수 있습니다. Load Balancer의 설정 변경이 필요한 경우 반드시 Kubernetes 리소스를 수정하는 방식으로 진행해 주십시오. - 콘솔 또는 API를 이용한 직접 변경으로 발생한 문제에는 기술 지원이 제공되지 않습니다. - 한 번 생성된 Load Balancer의 타입은 변경할 수 없습니다. ### 인스턴스 생성하기 Ncloud Kubernetes Service와 연동되는 Load Balancer 인스턴스를 생성하려면 서비스 매니페스트의 타입을 `LoadBalancer` 로 지정한 후, `service.beta.kubernetes.io/ncloud-load-balancer-layer-type` 어노테이션을 `nplb` 또는 `nlb`로 설정해 주십시오. - `nplb`: 네트워크 프록시 로드 밸런서(NPLB) 인스턴스가 생성됩니다. - `nlb`: 네트워크 로드 밸런서(NLB) 인스턴스가 생성됩니다. ### 인스턴스 속성 설정하기 서비스 매니페스트의 어노테이션을 통해 생성되는 인스턴스의 속성을 설정할 수 있습니다. 인스턴스의 속성을 설정하려면 인스턴스를 생성할 때 아래의 표를 참조하여 `metadata.annotations` 값을 입력해 주십시오. - 네트워크 프록시 로드 밸런서(NPLB) | 어노테이션 | 설명 | 비고 | | --- | --- | --- | | `service.beta.kubernetes.io/ncloud-load-balancer-layer-type` | 로드 밸런서 네트워크 레이어 타입 설정 다음 값 중 하나를 선택 : `nplb`, `nlb` | 기본값 `nplb` | | `service.beta.kubernetes.io/ncloud-load-balancer-size` | 로드 밸런서 부하 처리 성능 다음 값 중 하나를 선택 : `SMALL`, `MEDIUM`, `LARGE`, `XLARGE` | 기본값 `SMALL` | | `service.beta.kubernetes.io/ncloud-load-balancer-internal` | 사설 네트워크 타입의 로드 밸런서 생성 설정 다음 값 중 하나를 선택 : `"true"`, `"false"` | 기본값 `"false"` | | `service.beta.kubernetes.io/ncloud-load-balancer-retain-public-ip-on-termination` | 로드밸런서 제거 시 할당된 공인 IP를 보존하는 설정. 공인 아이피가 할당된 로드밸런서에만 적용. 다음 값 중 하나를 선택: `"true"`, `"false"` | 기본값 `"false"` | | `service.beta.kubernetes.io/ncloud-load-balancer-description` | 생성될 로드 밸런서 인스턴스에 대한 메모 입력 | - | | `service.beta.kubernetes.io/ncloud-load-balancer-termination-protection` | 타입이 `LoadBalancer`로 지정된 `Service` 제거 시 로드 밸런서 자동 제거 방지 옵션 다음 값 중 하나를 선택 : `"true"`, `"false"` | 기본값 `"false"` | | `service.beta.kubernetes.io/ncloud-load-balancer-subnet-id` | 로드 밸런서 생성을 위한 로드 밸런서 전용 서브넷의 ID 값 | 기본값으로 `kube-system`내의 ncloud-config 이름의 `configmap` 내 `lbSubnetNo` 사용 | | `service.beta.kubernetes.io/ncloud-load-balancer-ssl-certificate-no` | 프로토콜이 TLS인 리스너에 적용할 Certificate Manager의 인증서 번호 - 인증서 번호는 Resource Manager의 nrn에서 확인할 수 있습니다. (예: nrn:PUB:CertificateManager::000:Certificate/External/${certificateNo}) | - | | `service.beta.kubernetes.io/ncloud-load-balancer-tls-ports` | TLS를 적용할 포트 목록. e.g. "443,6443" | 기본값 `"443"`, 콤마를 사용하여 구분된 값 사용 가능 | | `service.beta.kubernetes.io/ncloud-load-balancer-tls-min-version` | TLS 최소 지원 버전 유형 코드 다음의 값 중 하나 선택 : `TLSV10`, `TLSV11`, `TLSV12`, `TLSV13` | 기본값 `TLSV10` | | `service.beta.kubernetes.io/ncloud-load-balancer-proxy-protocol` | 프록시 프로토콜 활성화 여부. 다음 값 중 하나를 선택 : `"true"`, `"false"` | 기본값 `"false"` | | `service.beta.kubernetes.io/ncloud-load-balancer-algorithm-type-code` | Algorithm 타입으로 Round Robin(RR), Source Ip Hash(SIPHS), Least Connection(LC) 중 하나를 설정 가능. 다음의 값 중 하나 선택 : `RR`, `SIPHS`, `LC` | 기본값 `RR` | | `service.beta.kubernetes.io/ncloud-load-balancer-enable-skip-acg-update` | ACG를 업데이트 설정 유무. 다음 값 중 하나를 선택 : `"true"`, `"false"` | 기본값 `"false"` | | `service.beta.kubernetes.io/ncloud-load-balancer-idle-timeout` | 로드 밸런서의 Idle Timeout 설정 (1~3600) | 기본값 `60` | | `service.beta.kubernetes.io/ncloud-load-balancer-cipher-suite-list` | 리스너에서 지원하는 Cipher Suite 목록, (예: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) | 기본값 `리스너에서 지원하는 모든 cipher suite` | | `service.beta.kubernetes.io/ncloud-load-balancer-listener-acl-id.{port}` | 리스너에 지정할 ACL ID | - | | `service.beta.kubernetes.io/ncloud-load-balancer-healthcheck-port.{port}` | 특정 리스너 포트에 대해 헬스체크에 사용할 서비스 포트를 지정 | - | | `service.beta.kubernetes.io/ncloud-load-balancer-healthcheck-interval-seconds.{port}` | 특정 리스너 포트에 대해 헬스체크 주기를 초 단위로 지정 | 미지정 시 기본값 `30` | | `service.beta.kubernetes.io/ncloud-load-balancer-healthy-threshold-count.{port}` | 특정 리스너 포트에 대해 헬스체크 성공 임계 횟수를 지정 | 미지정 시 기본값 `2` | | `service.beta.kubernetes.io/ncloud-load-balancer-unhealthy-threshold-count.{port}` | 특정 리스너 포트에 대해 헬스체크 실패 임계 횟수를 지정 | 미지정 시 기본값 `2` | - 네트워크 로드 밸런서(NLB) | 어노테이션 | 설명 | 비고 | | --- | --- | --- | | `service.beta.kubernetes.io/ncloud-load-balancer-layer-type` | 로드 밸런서 네트워크 레이어 타입 설정 다음 값 중 하나 선택 : `nplb`, `nlb` | 기본값 `nplb` 네트워크 로드 밸런서를 생성하기 위해서는 nlb를 입력 | | `service.beta.kubernetes.io/ncloud-load-balancer-size` | 로드 밸런서 부하 처리 성능 다음 값 중 하나 선택 : `SMALL`, `MEDIUM`, `LARGE`, `DYMANIC` | 기본값 DYNAMIC. **신규 생성 시 DYNAMIC만 설정 가능.** DYNAMIC 타입이 아닐 경우, 일부 로드밸런서에 한해 DYNAMIC 어노테이션 적용 시 DYNAMIC 타입으로 변경 가능. DYNAMIC 타입에서 다른 타입으로 변경 불가능. | | `service.beta.kubernetes.io/ncloud-load-balancer-internal` | 사설 네트워크 타입의 로드 밸런서 생성 설정 다음 값 중 하나를 선택 : `"true"`, `"false"` | 기본값 `"false"` | | `service.beta.kubernetes.io/ncloud-load-balancer-retain-public-ip-on-termination` | 로드밸런서 제거 시 할당된 공인 IP를 보존하는 설정. 공인 아이피가 할당된 로드밸런서에만 적용. 다음 값 중 하나를 선택: `"true"`, `"false"` | 기본값 `"false"` | | `service.beta.kubernetes.io/ncloud-load-balancer-description` | 생성될 로드 밸런서 인스턴스에 대한 메모 입력 | - | | `service.beta.kubernetes.io/ncloud-load-balancer-termination-protection` | 타입이 LoadBalancer로 지정된 Service 제거 시 로드 밸런서 자동 제거 방지 옵션 다음 값 중 하나를 선택 : `"true"`, `"false"` | 기본값 `"false"` | | `service.beta.kubernetes.io/ncloud-load-balancer-inbound-source` | ACG 규칙의 Inbound 접근 소스로 사용할 값 예시) 119.194.195.143/32,143.248.12.77/32 | 기본값 `0.0.0.0/0` | | `service.beta.kubernetes.io/ncloud-load-balancer-subnet-id` | 로드 밸런서 생성을 위한 로드밸런서 전용 서브넷의 ID 값 | 기본값으로 kube-system 내의 ncloud-config 이름의 configmap 내 lbSubnetNo 사용 | | `service.beta.kubernetes.io/ncloud-load-balancer-algorithm-type-code` | Algorithm 타입으로 Hash(MH), Round Robin(RR) 중 하나를 설정 가능. 다음의 값 중 하나 선택 : `MH`, `RR` | 기본값 `MH` | | `service.beta.kubernetes.io/ncloud-load-balancer-enable-skip-acg-update` | ACG를 업데이트 설정 유무. 다음 값 중 하나를 선택 : `"true"`, `"false"` | 기본값 `"false"` | | `service.beta.kubernetes.io/ncloud-load-balancer-sticky-session` | Sticky Session 설정 유무. 다음 값 중 하나를 선택 : `"true"`, `"false"` | 기본값 `"false"` | | `service.beta.kubernetes.io/ncloud-load-balancer-listener-acl-id.{port}` | 리스너에 지정할 ACL ID | - | | `service.beta.kubernetes.io/ncloud-load-balancer-healthcheck-port.{port}` | 특정 리스너 포트에 대해 헬스체크에 사용할 서비스 포트를 지정 | - | | `service.beta.kubernetes.io/ncloud-load-balancer-healthcheck-port.{port}` | 특정 리스너 포트에 대해 헬스체크에 사용할 서비스 포트를 지정 | - | | `service.beta.kubernetes.io/ncloud-load-balancer-healthcheck-interval-seconds.{port}` | 특정 리스너 포트에 대해 헬스체크 주기를 초 단위로 지정 | 미지정 시 기본값 `30` | | `service.beta.kubernetes.io/ncloud-load-balancer-healthy-threshold-count.{port}` | 특정 리스너 포트에 대해 헬스체크 성공 임계 횟수를 지정 | 미지정 시 기본값 `2` | | `service.beta.kubernetes.io/ncloud-load-balancer-unhealthy-threshold-count.{port}` | 특정 리스너 포트에 대해 헬스체크 실패 임계 횟수를 지정 | 미지정 시 기본값 `2` | | `service.beta.kubernetes.io/ncloud-load-balancer-enable-acl-operator` | ACL 관련 기능을 ACL-operator로 위임할지 유무. 활성화 시 acl 기능 비활성화 - 다음의 값 중 하나 선택: `"true"`, `"false"` | 기본값 `"false"` | #### 로드 밸런서의 Subnet 유형에 따른 공인 및 사설 아이피 할당 방식 로드 밸런서 Subnet은 Public Subnet와 Private Subnet의 두 가지 유형이 있습니다. 각 타입은 공인 및 사설 아이피가 부여된 로드 밸런서를 생성하기 위해 요구됩니다. 로드 밸런서를 생성할 때, kube-system 네임스페이스 내의 ncloud-config ConfigMap에서 정의된 lbPublicSubnetNo와 lbSubnetNo 필드에 있는 Subnet ID를 사용합니다. 이 Subnet ID는 로드 밸런서를 생성할 때, `service.beta.kubernetes.io/ncloud-load-balancer-subnet-id` annotation을 이용하여 다른 Subnet ID를 사용하도록 지정할 수 있습니다. **1. Public Subnet(Internet Gateway 전용)** 공인 아이피가 부여된 로드밸런서를 생성 하기 위해서는 Public Subnet이 요구됩니다. 네이버 클라우드 플랫폼 콘솔 VPC 환경의 **Menu** > **All Services** > **Networking** > **VPC** > **Public IP** 메뉴에서 공인 아이피를 신청하고, 이를 로드밸런서에 할당할 수 있습니다. 공인 아이피를 지정하지 않으면 신규 공인 아이피가 신청됩니다. **2. Private Subnet** VPC 내에서 로드 밸런서를 사설 아이피가 할당된 Private Subnet에 생성하려면 해당 서브넷이 필요합니다. ### 인스턴스 속성 설정 예제 인스턴스 속성 설정에 대한 자세한 예제는 [Load Balancer 속성 설정 예제](/docs/k8s-k8sexamples-loadbalancer)를 참조해 주십시오. ### 생성된 로드밸런서 인스턴스의 External IP확인 생성된 인스턴스의 external IP를 확인하려면 아래 명령어를 실행해 주십시오. ``` $ kubectl --kubeconfig $KUBE_CONFIG get svc example-service ``` EXTERNAL-IP 열에 해당 인스턴스의 external IP가 표시됩니다. 다음은 해당 명령어를 사용하여 external IP를 조회한 예제입니다. ``` $ 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 ``` ### 로드 밸런서 관리 일시 중지 `lb.ncloud.naver.com/pause: "true"`는 Kubernetes 1.36 이상 KVM 클러스터에서 사용할 수 있는 일시 중지 옵션입니다. 이 값이 설정되면 컨트롤러의 spec/provider reconcile이 일시 중지됩니다. | 적용 대상 | 동작 | | --- | --- | | Service | - pause 중에는 Service 변경이 Load Balancer 설정에 미반영 - pause 상태에서 Service를 삭제해도 이미 생성된 NCloud LB/TG는 삭제하지 않고 유지 | | Service 삭제 중 | - pause가 설정되어 있으면 `service.kubernetes.io/load-balancer-cleanup` finalizer를 제거하고 NCloud LB/TG 정리를 기다리지 않음 | 주의 pause는 이미 생성된 NCloud LB/TG를 보존하기 위한 옵션입니다. pause 상태에서는 누락된 Load Balancer 리소스를 새로 생성하지 않습니다. 변경 반영을 재개하려면 입력 리소스에서 pause 어노테이션을 제거해 주십시오. ### 인스턴스 삭제하기 LoadBalancer 타입으로 생성된 Kubernetes 서비스를 삭제하면 연동된 Load Balancer 인스턴스가 자동으로 함께 삭제됩니다. LoadBalancer 타입으로 생성된 Kubernetes 서비스를 확인한 후 삭제하는 방법은 다음과 같습니다. 1. 아래 명령어를 실행하여 생성된 Kubernetes 서비스를 확인해 주십시오. ``` $ kubectl --kubeconfig $KUBE_CONFIG get service ``` - 결과 값의 TYPE 열에서 각 서비스의 타입을 확인할 수 있습니다. 2. 아래 명령어를 실행하여 LoadBalancer 타입의 서비스를 삭제해 주십시오. ``` $ kubectl --kubeconfig $KUBE_CONFIG delete service my-nginx ```