--- title: "Load Balancer 속성 설정 예제 " slug: "k8s-k8sexamples-loadbalancer" tags: ["Kubernetes Service"] updated: 2026-08-20T09:03:27Z published: 2026-08-20T09:03:27Z canonical: "guide-gov.ncloud-docs.com/k8s-k8sexamples-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 환경에서 이용 가능합니다. [Load Balancer 인스턴스 연동](/docs/k8s-k8suse-loadbalancer)에서 소개한 각종 어노테이션을 활용하여 Load Balancer 인스턴스의 속성을 설정하는 예제입니다. 주의 Kubernetes에서 생성한 네이버 클라우드 플랫폼의 로드밸런서를 Kubernetes의 Service 리소스가 아닌 콘솔 및 API를 통해 설정하시는 경우, 상태 동기화에 문제가 발생할 수 있습니다. 생성된 로드밸런서에 대한 설정 변경은 반드시 Kubernetes에서 생성된 Service 리소스 수정을 통해 이루어져야 합니다. ## 공통 예제 로드밸런서 생성 시 공통으로 사용할 수 있는 설정 예시입니다. ### Load Balancer Class 선택 예제 Kubernetes 1.27 버전 이후 부터 `LoadBalancerClass`를 지정할 수 있습니다. LoadBalancerClass의 지정을 통해 네이버 클라우드 플랫폼이 제공하는 로드밸런서 이외의 로드밸런서를 클러스터에서 사용할 수 있습니다. 이로 인하여 LoadBalancerClass 지정 시 Network Load Balancer, Network Proxy Load Balancer는 생성되지 않습니다. 서비스를 생성한 후에는 할당된 External-IP를 확인하여 외부에서 접근이 가능한지 확인해야 합니다. 아래 예시는 [loxilb](https://github.com/loxilb-io/loxilb)를 Load BalancerClass로 지정하여 사용하는 방법을 보여줍니다. ``` apiVersion: v1 kind: Service metadata: name: my-nginx labels: app: nginx spec: selector: app: nginx ports: - port: 8765 targetPort: 80 type: LoadBalancer loadBalancerClass: "loxilb.io/loxilb" ``` ### 인스턴스가 생성될 전용 서브넷 선택 예제 인스턴스 생성 시, `kube-system` Namespace에서 `ncloud-config` 이름을 가진 `configmap` 내의 `lbSubnetNo`를 기본값으로 사용합니다. 만약 다른 로드밸런서 전용 서브넷에 인스턴스를 생성해야 하는 경우 `service.beta.kubernetes.io/ncloud-load-balancer-subnet-id` 어노테이션을 사용할 수 있습니다. 다음은 NPLB 인스턴스가 생성될 전용 서브넷을 선택하는 예제입니다. ``` kind: Service apiVersion: v1 metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nplb" service.beta.kubernetes.io/ncloud-load-balancer-subnet-id: "452772" spec: ports: - port: 80 targetPort: 80 selector: run: my-nginx type: LoadBalancer ``` ### 로드밸런서의 공인 아이피 부여 예제 `LoadBalancer` 타입의 Service 일때, `spec.loadBalancerIP` 필드에 로드밸런서에 할당할 공인아이피를 정의할 수 있습니다. 해당 필드에는 **네이버 클라우드 플랫폼 콘솔 > VPC > Public IP** 메뉴에서 확인 할 수 있는 미할당 상태의 공인 아이피만 기술할 수 있습니다. 기본적으로 로드밸런서를 삭제하면 할당된 공인 아이피도 함께 반납됩니다. 공인 아이피가 함께 반납되지 않도록 하기 위해 `service.beta.kubernetes.io/ncloud-load-balancer-retain-public-ip-on-termination: "true"` annotation을 사용할 수 있습니다. ``` apiVersion: v1 kind: Service metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nplb" service.beta.kubernetes.io/ncloud-load-balancer-retain-public-ip-on-termination: "true" spec: loadBalancerIP: 110.234.194.181 ports: - port: 80 targetPort: 8080 protocol: TCP name: http selector: run: nginx type: LoadBalancer ``` ### 사설 네트워크 타입의 로드밸런서 생성 예제 `service.beta.kubernetes.io/ncloud-load-balancer-internal` 어노테이션을 사용하여 VPC 내부에서만 접근 가능한 사설 타입의 로드밸런서를 생성할 수 있습니다. 이 어노테이션의 기본값은 false이므로, 명시적으로 지정하지 않으면 공인 타입의 로드밸런서가 생성됩니다. 사설 타입의 로드밸런서는 VPC 내부의 사설 IP를 이용해 내부 서버 간 부하를 분산 처리하며, VPC 외부에서의 접근은 허용되지 않습니다. ``` apiVersion: v1 kind: Service metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nplb" service.beta.kubernetes.io/ncloud-load-balancer-internal: "true" spec: ports: - port: 80 targetPort: 80 selector: run: my-nginx type: LoadBalancer ``` ### 부하분산 알고리즘 설정 예제 `service.beta.kubernetes.io/ncloud-load-balancer-algorithm-type-code` 어노테이션을 사용해 로드밸런서의 부하분산 알고리즘을 설정할 수 있습니다. Network Proxy LoadBalancer의 경우 Round Robin(RR), Source Ip Hash(SIPHS), Least Connection(LC) 중에서 선택할 수 있으며, Network LoadBalancer의 경우 Hash(MH), Round Robin(RR) 중에서 선택할 수 있습니다. 다음은 Network Proxy LoadBalancer를 생성하면서 부하 분산 알고리즘으로 Source Ip Hash(SIPHS)를 선택하는 예시입니다. ``` apiVersion: v1 kind: Service metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nplb" service.beta.kubernetes.io/ncloud-load-balancer-algorithm-type-code: "SIPHS" spec: ports: - port: 80 targetPort: 80 selector: run: my-nginx type: LoadBalancer ``` ### Access Control List 설정 예제 `service.beta.kubernetes.io/ncloud-load-balancer-listener-acl-id.{port}: {aclId}` 어노테이션을 사용해 로드밸런서 리스너별로 Access Control List를 설정할 수 있습니다. 다음은 해당 어노테이션을 사용해 Access Control List를 설정하는 예제입니다. ``` kind: Service apiVersion: v1 metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-listener-acl-id.80: "123" spec: ports: - port: 80 targetPort: 80 selector: run: my-nginx type: LoadBalancer ``` ## 네트워크 프록시 로드밸런서(NPLB) 속성 설정 예제 ### 네트워크 프록시 로드 밸런서(NPLB) 인스턴스 생성 예제 `service.beta.kubernetes.io/ncloud-load-balancer-layer-type` 어노테이션을 사용하여 NetworkProxyLoadBalancer 인스턴스를 생성할 수 있습니다. 다음은 NetworkProxyLoadBalancer 인스턴스를 생성하는 예제입니다. ``` kind: Service apiVersion: v1 metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nplb" service.beta.kubernetes.io/ncloud-load-balancer-internal: "true" service.beta.kubernetes.io/ncloud-load-balancer-size: "SMALL" spec: ports: - port: 80 targetPort: 80 selector: run: my-nginx type: LoadBalancer ``` ### 로드밸런서의 부하 처리 성능 설정 예제 `service.beta.kubernetes.io/ncloud-load-balancer-size` 어노테이션을 사용해 생성한 로드밸런서의 부하 처리 성능을 설정할 수 있습니다. 다음은 해당 어노테이션을 사용해 부하 처리 성능을 설정하는 예제입니다. ``` kind: Service apiVersion: v1 metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nplb" service.beta.kubernetes.io/ncloud-load-balancer-size: "MEDIUM" spec: ports: - port: 80 targetPort: 80 selector: run: my-nginx type: LoadBalancer ``` ### TLS 설정 예제 서비스 명세를 통해 TLS/SSL 인증서를 로드밸런서에 적용할 수 있습니다. Certificate Manager에 등록된 인증서 번호(nrn)를 `service.beta.kubernetes.io/ncloud-load-balancer-ssl-certificate-no`에 지정하고 TLS를 사용할 포트 번호를 service.beta.`service.beta.kubernetes.io/ncloud-load-balancer-tls-ports` 어노테이션에 설정합니다. 다음은 443 포트(HTTPS)를 통해 들어오는 트래픽을 암호화하여 80 포트(HTTP)로 전달하는 예제입니다. ``` kind: Service apiVersion: v1 metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-ssl-certificate-no: "1234" service.beta.kubernetes.io/ncloud-load-balancer-tls-ports: "443" spec: ports: - port: 443 targetPort: 80 selector: app: nginx type: LoadBalancer ``` ### 프록시 프로토콜 활성화 예제 `service.beta.kubernetes.io/ncloud-load-balancer-proxy-protocol` 어노테이션을 통해 로드밸런서의 프록시 프로토콜을 활성화 할 수 있습니다. 프록시 프로토콜은 TCP나 SSL 프로토콜을 사용할 때, 프록시 환경을 통해 연결 요청을 하는 클라이언트의 원본 IP 주소(Original Client IP address)를 알 수 있게 해주는 프로토콜입니다. 이 기능을 사용하기 위해서는 로드밸런서뿐만 아니라 연결된 어플리케이션(파드)에서도 관련 설정을 해주어야 합니다. ``` kind: Service apiVersion: v1 metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nplb" service.beta.kubernetes.io/ncloud-load-balancer-proxy-protocol: "true" spec: ports: - port: 80 targetPort: 80 selector: run: my-nginx type: LoadBalancer ``` ### 로드밸런서의 Idle Timeout 설정 예제 `service.beta.kubernetes.io/ncloud-load-balancer-idle-timeout` 을 통해 로드밸런서의 Idle Timeout 을 조정할 수 있습니다. 어플리케이션의 Idle Timeout 고려하여 조정할 필요가 있으며, 로드밸런서의 기본값은 60초입니다. 다음 예시는 로드밸런서의 Idle Timeout 값을 90초로 설정하는 방법을 보여줍니다. ``` kind: Service apiVersion: v1 metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nplb" service.beta.kubernetes.io/ncloud-load-balancer-idle-timeout: "90" spec: ports: - port: 80 targetPort: 80 selector: run: my-nginx type: LoadBalancer ``` ## 네트워크 로드밸런서(NLB) 속성 설정 예제 ### 네트워크 로드 밸런서(NLB) 인스턴스 생성 예제 `service.beta.kubernetes.io/ncloud-load-balancer-layer-type` 어노테이션을 사용하여 NetworkLoadBalancer 인스턴스를 생성할 수 있습니다. 다음은 NetworkLoadBalancer 인스턴스를 생성하는 예제입니다. ``` kind: Service apiVersion: v1 metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nlb" service.beta.kubernetes.io/ncloud-load-balancer-internal: "true" service.beta.kubernetes.io/ncloud-load-balancer-size: "SMALL" spec: ports: - port: 80 targetPort: 80 selector: run: my-nginx type: LoadBalancer ``` ### 로드밸런서 생성 시 ACG 규칙의 Inbound Source 설정 예제 Service 타입이 `LoadBalancer`인 경우, 외부와의 통신을 위해 Inbound Source에 `0.0.0.0./0`인 ACG 규칙이 기본값으로 설정됩니다. 만약 다른 IP Block을 접근 소스로 설정해야 하는 경우 `service.beta.kubernetes.io/ncloud-load-balancer-inbound-source`의 어노테이션을 사용할 수 있습니다. 여러 개의 Inbound Source를 설정하고자 할 경우에는 콤마(,)로 구분하여 입력할 수 있습니다. 다음은 NLB 인스턴스 생성 시 ACG 규칙의 Inbound Source를 설정하는 예제입니다. ``` kind: Service apiVersion: v1 metadata: name: my-nginx annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nlb" service.beta.kubernetes.io/ncloud-load-balancer-inbound-source: "10.120.0.0/16,143.248.12.77/32" spec: ports: - port: 80 targetPort: 80 selector: run: my-nginx type: LoadBalancer ``` ### 로드밸런서 생성 시 UDP 설정 예제 Network LoadBalancer는 UDP 프로토콜을 리스너로 사용할 수 있습니다. NLB 인스턴스를 생성할 때 UDP 리스너를 설정하는 예시는 다음과 같습니다. 참고 - UDP 프로토콜을 리스너로 사용하더라도 타깃 그룹의 헬스체크는 TCP로 수행되므로 Kubernetes 서비스 리소스에 TCP 포트가 열려 있어야 합니다. - UDP 포트와 TCP 포트가 동일한 경우에는 별도 설정이 필요하지 않습니다. - UDP 포트와 TCP 포트가 서로 다른 경우에는 어노테이션을 통해 헬스체크 포트를 명시적으로 지정해야 합니다. - 제약 사항으로 인해 로드밸런서에는 TCP 리스너도 함께 생성됩니다. - UDP 및 TCP 포트가 동일한 경우 - 어노테이션 미사용 ``` apiVersion: v1 kind: Service metadata: name: udp-service annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nlb" spec: selector: app: udp-service ports: - name: tcp port: 80 protocol: TCP nodePort: 30080 - name: udp port: 80 protocol: UDP nodePort: 30080 type: LoadBalancer ``` - UDP 및 TCP 포트가 동일하지 않은 경우 - 어노테이션을 통해 헬스체크 포트 지정 필요 ``` apiVersion: v1 kind: Service metadata: name: udp-service annotations: service.beta.kubernetes.io/ncloud-load-balancer-layer-type: "nlb" service.beta.kubernetes.io/ncloud-load-balancer-healthcheck-port.90: "85" #포트 90의 헬스체크는 포트 85의 노드포트 사용 spec: selector: app: udp-service ports: - name: tcp port: 85 targetPort: 80 protocol: TCP nodePort: 30091 - name: udp port: 90 targetPort: 90 protocol: UDP nodePort: 30090 type: LoadBalancer ```