로드 밸런서 생성 및 제어

로드 밸런서(Load Balancer)는 클라이언트의 요청을 수신하여 여러 서버로 트래픽을 분산하는 서비스입니다. 이는 단일 서버에서 모든 요청을 처리할 때 발생할 수 있는 문제를 해결하기 위한 핵심 기술입니다.

Kubernetes Engine에서는 Service.type=LoadBalancer 선언과 spec.loadBalancerClass 설정을 통해 로드 밸런서를 간편하게 생성하고 제어할 수 있습니다. 설정값에 따라 Network Load Balancer(NLB) 또는 Application Load Balancer(ALB)가 자동으로 생성됩니다.

지원 범위 안내 (2026년 8월 25일부터 적용)

spec.loadBalancerClass 필드와 loadbalancer.kakaocloud.com/* annotation을 사용하는 Kubernetes Engine 서비스는 v1.30 이상 버전 클러스터에서 지원됩니다.

spec.loadBalancerClass로 로드 밸런서 유형을 지정합니다.
loadbalancer.kakaocloud.com/* annotation만 사용합니다.
기존 클러스터에서 이전 annotation을 사용 중이라면 이전 버전 가이드를 참고하시기 바랍니다.

로드 밸런서 생성

Kubernetes Engine에서 로드 밸런서를 생성하는 방법은 다음과 같습니다.

적용 범위

이 문서에서 설명하는 프로토콜, annotation, 제약 사항은 Kubernetes Engine의 Service 연동 기준입니다. 카카오클라우드 Load Balancing 서비스에서 제공하는 기능과 일부 차이가 있을 수 있습니다.

고가용성 및 과금 안내

Kubernetes Engine에서 생성된 로드 밸런서는 고가용성(High Availability)으로 구성됩니다. 클러스터 네트워크에 포함된 모든 가용 영역(AZ)에 자동으로 분산 배치됩니다.

실제 워크로드가 일부 AZ에서만 동작하더라도 로드 밸런서는 전체 AZ를 기준으로 리소스를 할당합니다. 따라서 각 AZ에 생성된 로드 밸런서가 모두 과금 대상에 포함됩니다.

사전 작업

로드 밸런서 생성 전에 kubectl을 설정하고, 필요한 경우 SSL 인증서를 등록합니다.

kubectl 설치 및 제어 설정

Kubernetes에서 Service 객체를 생성하려면 kubectl 설치 및 제어 설정이 필요합니다. 자세한 방법은 kubectl 제어 설정을 참고하시기 바랍니다.

SSL 인증서 등록 및 관리(선택)

ALB 또는 NLB에서 TLS 종료를 사용하려면 loadbalancer.kakaocloud.com/tls-container-refs 설정이 필요하며, 사용할 SSL 인증서를 먼저 등록해야 합니다. 인증서 등록 및 삭제는 Management > Certificate Manager에서 수행한 뒤, 생성된 인증서 ID를 tls-container-refs에 지정하세요.

인증서 등록하기

카카오클라우드 콘솔에서 Management > Certificate Manager 메뉴로 이동합니다.
인증서 메뉴에서 [인증서 등록] 버튼을 클릭합니다.
인증서 등록 팝업창에서 필요한 정보를 입력한 후, [등록] 버튼을 클릭합니다.
인증서 목록에서 등록한 인증서 정보를 확인합니다.

인증서 삭제하기

카카오클라우드 콘솔에서 Management > Certificate Manager 메뉴로 이동합니다.
인증서 메뉴에서 삭제할 인증서의 [⋮] 버튼 > 인증서 삭제를 선택합니다.
인증서 삭제 팝업창에서 필요한 정보를 입력한 후, [삭제] 버튼을 클릭합니다.
인증서 목록에서 해당 인증서가 정상적으로 삭제되었는지 확인합니다.

Step 1. Service 명세 확인

로드 밸런서 생성에 필요한 Service 명세는 아래와 같습니다.

항목	설정 값
`spec.type`	`LoadBalancer`
`spec.loadBalancerClass`	`loadbalancer.kakaocloud.com/nlb` 또는 `loadbalancer.kakaocloud.com/alb`
`metadata.annotations`	`loadbalancer.kakaocloud.com/*` 형식 사용

NLB 로드 밸런서 유형 서비스 명세 확인

NLB 로드 밸런서 유형 서비스 명세 확인
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 로드 밸런서 유형 서비스 명세 확인

ALB 로드 밸런서 유형 서비스 명세 확인
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. 로드 밸런서 유형 선택

로드 밸런서 유형은 spec.loadBalancerClass로 지정합니다.

주의

spec.loadBalancerClass 필드의 값은 Service 생성 후 변경할 수 없습니다. 기존 LoadBalancer 서비스의 타입을 변경(NLB ↔ ALB)하려면, spec.loadBalancerClass에 원하는 타입을 명시하여 서비스를 새롭게 생성해 주시기 바랍니다.

유형	설정 값	설명
NLB	`loadbalancer.kakaocloud.com/nlb`	L4 로드 밸런서입니다. TCP 또는 UDP 기반 서비스에 사용합니다. `tls-container-refs`를 설정하면 TLS 리스너와 TCP 대상 그룹으로 생성됩니다.
ALB	`loadbalancer.kakaocloud.com/alb`	L7 로드 밸런서입니다. 기본은 HTTP로 동작하며, `tls-container-refs`를 설정하면 HTTPS 리스너와 HTTP 대상 그룹으로 생성됩니다.

안내

tls-container-refs에는 https://key-manager.{region}/v1/secrets/{secret-id} 형식의 인증서 경로를 입력합니다.
ALB에 인증서를 지정하지 않으면 HTTP 리스너로 생성됩니다. NLB는 지정한 Service 프로토콜에 따라 TCP 또는 UDP 리스너로 생성됩니다.

Step 3. 로드 밸런서 퍼블릭 노출 여부 설정

loadbalancer.kakaocloud.com/load-balancer-scheme으로 내부형 또는 외부형 로드 밸런서를 설정합니다.

설정 키	값	설명
`loadbalancer.kakaocloud.com/load-balancer-scheme`	`internal`	프라이빗 주소를 사용하는 내부형 로드 밸런서(기본값)
`loadbalancer.kakaocloud.com/load-balancer-scheme`	`internet-facing`	퍼블릭 노출이 가능한 외부형 로드 밸런서

주의

internet-facing으로 설정하면 로드 밸런서에 새로운 퍼블릭 IP가 생성되어 연결됩니다.
internet-facing 또는 internal 설정은 생성 후 변경할 수 없습니다. 잘못된 값으로 생성한 경우 올바른 설정으로 Service를 새로 생성하고 마이그레이션한 후 기존 Service를 삭제해 주세요.

loadbalancer.kakaocloud.com/delete-floatingip 값을 지정하지 않거나 false로 설정하면, Service 삭제 후에도 퍼블릭 IP는 연결 해제(detach)된 상태로 남아 과금 대상이 될 수 있으니 유의해 주세요.

Step 4. Service 생성 및 상태 확인

작성한 YAML 파일을 적용한 뒤 Service 상태를 확인합니다.

Service 생성
kubectl --kubeconfig=$KUBE_CONFIG apply -f {SERVICE_YAML_FILE}

Service 상태 확인
kubectl --kubeconfig=$KUBE_CONFIG get svc {SERVICE_NAME}

Service 상세 이벤트 확인
kubectl --kubeconfig=$KUBE_CONFIG describe svc {SERVICE_NAME}

로드 밸런서 생성까지 수 분이 소요될 수 있으며, 생성 진행 중에는 EXTERNAL-IP가 Pending으로 표시되거나 IP가 먼저 표시될 수 있습니다.
단, EXTERNAL-IP에 값이 표시되더라도 로드 밸런서 또는 고가용성 그룹이 Creating 상태이면 요청이 정상적으로 처리되지 않을 수 있습니다.
생성된 로드 밸런서와 고가용성 그룹은 콘솔에서 확인할 수 있으며, 관련 리소스가 모두 Active 상태가 되면 정상적으로 트래픽을 처리할 수 있습니다.

Protocol 매핑 및 제약

지원 프로토콜 조합

아래 표는 Kubernetes Engine의 Service 연동 기준으로 지원하는 조합입니다.

LB 유형	리스너 프로토콜	대상 그룹 프로토콜
ALB	`HTTP`	`HTTP`
ALB	`HTTPS` (`TERMINATED_HTTPS`)	`HTTP`
NLB	`TCP`	`TCP`
NLB	`TCP`	`PROXY`
NLB	`UDP`	`UDP`
NLB	`TLS` (`TERMINATED_HTTPS`)	`TCP`

부록

Annotation 전체 목록

로드 밸런서 유형과 용도에 따른 annotation을 확인합니다.

설정 및 관리 안내

헬스 모니터 비활성화: enable-health-monitor=false로 설정하면 장애 대상을 즉시 제외하지 못해 장애 노드로 트래픽이 계속 전달될 수 있으므로, 운영 환경에서는 권장하지 않습니다.
설정 재적용: spec 또는 annotation으로 제어되는 항목을 콘솔에서 직접 변경하면, Kubernetes 리소스 변경 또는 컨트롤러 재조정 시 Service에 정의된 값으로 다시 적용될 수 있습니다. 콘솔에서 직접 변경한 설정은 유지되지 않을 수 있으므로, Kubernetes 리소스를 통해 변경해 주세요.
annotation 혼용: ALB 또는 NLB 전용 annotation을 혼용할 경우 정상적으로 동작하지 않을 수 있습니다.
트래픽 유실: Pod 종료 시점과 Load Balancer 또는 서비스 엔드포인트 반영 시점 사이의 지연으로 인해 일시적인 트래픽 유실이 발생할 수 있습니다. 특히 externalTrafficPolicy: Local 사용 시에는 노드 로컬 엔드포인트에만 외부 트래픽이 전달되므로, 노드 교체 또는 삭제 과정에서 영향이 더 크게 나타날 수 있습니다. 이를 완화하려면 Pod에 preStop hook을 설정하고, terminationGracePeriodSeconds를 충분히 크게 설정하여 종료 전 드레이닝 시간을 확보해야 합니다. 권장 대기 시간은 LB 헬스 체크 반영 시간(health-monitor-delay × health-monitor-max-retries) 이상입니다. 자세한 내용은 Kubernetes 공식 문서를 참고해 주세요.

아래는 현재 버전 클러스터에서 사용할 수 있는 loadbalancer.kakaocloud.com/* annotation입니다.

표기 안내

각 annotation의 지원 값, 기본값, 유의사항은 아래 상세 보기 링크에서 확인할 수 있습니다.

구분	Annotation	설명	비고
ALB 전용	`loadbalancer.kakaocloud.com/` `x-forwarded-for`	클라이언트 IP 전달 방식 설정	상세 보기
ALB 전용	`loadbalancer.kakaocloud.com/` `x-forwarded-port`	클라이언트 접속 포트 헤더 추가 여부 설정	상세 보기
ALB 전용	`loadbalancer.kakaocloud.com/` `x-forwarded-proto`	클라이언트 접속 프로토콜 헤더 추가 여부 설정	상세 보기
NLB 전용	`loadbalancer.kakaocloud.com/` `proxy-protocol`	PROXY 헤더를 통한 클라이언트 정보 전달 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `tls-container-refs`	ALB 또는 NLB의 TLS 종료용 인증서 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `tls-minimum-version`	TLS 연결에 허용할 최소 버전 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `load-balancer-scheme`	내부형 또는 외부형 로드 밸런서 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `delete-floatingip`	Service 삭제 시 퍼블릭 IP 삭제 여부 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `enable-health-monitor`	상태 확인 사용 여부 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `health-monitor-http-version`	상태 확인에 사용할 HTTP 버전 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `health-monitor-protocol`	상태 확인 프로토콜 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `health-monitor-delay`	상태 확인 주기 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `health-monitor-timeout`	상태 확인 타임아웃 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `health-monitor-max-retries`	상태 확인 성공 판정 재시도 횟수 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `health-monitor-max-retries-down`	상태 확인 실패 판정 재시도 횟수 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `health-monitor-url-path`	HTTP/HTTPS 헬스체크 경로 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `health-monitor-http-method`	상태 확인 메서드 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `health-monitor-expected-code`	상태 확인 시 응답 받는 상태 코드 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `timeout-client-data`	클라이언트 유휴 제한 시간 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `timeout-member-data`	멤버 유휴 제한 시간 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `load-balancer-subnet-ids`	로드 밸런서 생성 서브넷 지정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `blb-name`	고가용성 그룹 이름 설정	상세 보기
공통	`loadbalancer.kakaocloud.com/` `node-selector`	로드 밸런서 멤버 노드 필터링	상세 보기
공통	`loadbalancer.kakaocloud.com/` `lb-method`	대상 그룹 트래픽 분산 알고리즘 설정	상세 보기

ALB 전용 annotation

x-forwarded-for

구분	내용
Annotation	`loadbalancer.kakaocloud.com/x-forwarded-for`
설명	`X-Forwarded-For` 헤더의 클라이언트 IP 처리 방식을 설정합니다.
값	`"append"` / `"preserve"` / `"remove"`
기본 값	`"append"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	-

x-forwarded-port

구분	내용
Annotation	`loadbalancer.kakaocloud.com/x-forwarded-port`
설명	`X-Forwarded-Port` 헤더에 클라이언트 접속 포트를 추가할지 설정합니다.
값	`"true"` / `"false"`
기본 값	`"false"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	-

x-forwarded-proto

구분	내용
Annotation	`loadbalancer.kakaocloud.com/x-forwarded-proto`
설명	`X-Forwarded-Proto` 헤더에 클라이언트 접속 프로토콜을 추가할지 설정합니다.
값	`"true"` / `"false"`
기본 값	`"false"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	-

NLB 전용 annotation

proxy-protocol

구분	내용
Annotation	`loadbalancer.kakaocloud.com/proxy-protocol`
설명	원본 클라이언트 IP와 포트 정보를 PROXY 헤더로 전달합니다.
값	`"true"` / `"false"` / `"v1"`
기본 값	-
적용 및 수정	Service 생성 후 수정할 수 없습니다.
비고	- 설정을 변경하려면 Service를 새로 생성해야 합니다.

공통 annotation

tls-container-refs

구분	내용
Annotation	`loadbalancer.kakaocloud.com/tls-container-refs`
설명	ALB 또는 NLB에서 TLS 종료에 사용할 인증서를 지정합니다.
값	`"https://key-manager.{region}/v1/secrets/{secret-id}"`
기본 값	-
적용 및 수정	Service 생성 시 지정한 Annotation에 한해 수정이 가능하며, 생성 이후 Annotation의 신규 적용 및 삭제는 지원되지 않습니다.
비고	- 콤마(`,`)로 구분하여 최대 6개까지 지정할 수 있으며, 중복 지정은 불가합니다. - 여러 인증서를 나열할 경우 첫 번째 인증서가 기본(Default) 인증서로 할당되고, 두 번째 인증서부터는 추가(Optional) 인증서로 할당됩니다. - Service 생성 시점에 함께 설정하는 것을 권장합니다.

tls-minimum-version

구분	내용
Annotation	`loadbalancer.kakaocloud.com/tls-minimum-version`
설명	TLS 연결에 허용할 최소 버전을 설정합니다.
값	`"TLSv1"` / `"TLSv1.1"` / `"TLSv1.2"` / `"TLSv1.3"`
기본 값	`"TLSv1.3"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	- TLS 종료를 사용하는 ALB 또는 NLB에 적용합니다.

load-balancer-scheme

구분	내용
Annotation	`loadbalancer.kakaocloud.com/load-balancer-scheme`
설명	로드 밸런서를 내부형 또는 외부형으로 설정합니다.
값	`"internal"` / `"internet-facing"`
기본 값	`"internal"`
적용 및 수정	Service 생성 후 수정할 수 없습니다.
비고	- 설정을 변경하려면 Service를 새로 생성해야 합니다.

delete-floatingip

구분	내용
Annotation	`loadbalancer.kakaocloud.com/delete-floatingip`
설명	Service 삭제 시 연결된 퍼블릭 IP를 함께 삭제할지 설정합니다.
값	`"true"` / `"false"`
기본 값	`"false"`
적용 및 수정	Service 생성 후 수정할 수 있으며 삭제 시 적용됩니다.
비고	- `internet-facing` 로드 밸런서에서만 유효합니다.

enable-health-monitor

구분	내용
Annotation	`loadbalancer.kakaocloud.com/enable-health-monitor`
설명	상태 확인 기능을 사용할지 설정합니다.
값	`"true"` / `"false"`
기본 값	`"true"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	- `false`로 설정하면 장애 대상을 즉시 제외하지 못해 장애 노드로 트래픽이 계속 전달될 수 있으므로 운영 환경에서는 권장하지 않습니다.

health-monitor-http-version

구분	내용
Annotation	`loadbalancer.kakaocloud.com/health-monitor-http-version`
설명	상태 확인에 사용할 HTTP 버전을 설정합니다.
값	`"1.1"` / `"1.0"`
기본 값	-
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	-

health-monitor-protocol

구분	내용
Annotation	`loadbalancer.kakaocloud.com/health-monitor-protocol`
설명	상태 확인에 사용할 프로토콜을 설정합니다.
값	`"TCP"` / `"HTTP"` / `"HTTPS"` / `"PING"` / `"UDP-CONNECT"`
기본 값	`"HTTP"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	- 프로토콜 수정 시 기존 헬스 모니터가 삭제되고, 입력한 프로토콜로 신규 생성됩니다. - 기본값 외의 프로토콜을 사용할 경우, 노드 Scale-in 과정에서 트래픽 유실이 발생할 수 있습니다.

health-monitor-delay

구분	내용
Annotation	`loadbalancer.kakaocloud.com/health-monitor-delay`
설명	상태 확인 주기를 초 단위로 설정합니다.
값	정수
기본 값	`"5"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	- `health-monitor-timeout` 값보다 크거나 같아야 합니다.

health-monitor-timeout

구분	내용
Annotation	`loadbalancer.kakaocloud.com/health-monitor-timeout`
설명	상태 확인 타임아웃을 초 단위로 설정합니다.
값	정수
기본 값	`"5"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	- `health-monitor-delay` 값보다 작거나 같아야 합니다.

health-monitor-max-retries

구분	내용
Annotation	`loadbalancer.kakaocloud.com/health-monitor-max-retries`
설명	상태 전환 기준(성공)을 위한 재시도 횟수를 설정합니다.
값	정수
기본 값	`"1"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	-

health-monitor-max-retries-down

구분	내용
Annotation	`loadbalancer.kakaocloud.com/health-monitor-max-retries-down`
설명	상태 전환 기준(실패)을 위한 상태 확인 횟수를 설정합니다.
값	정수
기본 값	`"6"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	-

health-monitor-url-path

구분	내용
Annotation	`loadbalancer.kakaocloud.com/health-monitor-url-path`
설명	상태 확인 체크 경로를 설정합니다.
값	문자열
기본 값	`"/healthz"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	- 상태 확인 프로토콜이 `HTTP`, `HTTPS`일 때만 적용 가능합니다.

health-monitor-http-method

구분	내용
Annotation	`loadbalancer.kakaocloud.com/health-monitor-http-method`
설명	상태 확인 체크 메서드를 설정할 수 있습니다.
값	`"GET"` / `"HEAD"` / `"OPTIONS"` / `"POST"` / `"PUT"` / `"TRACE"` / `"PATCH"` / `"DELETE"` / `"CONNECT"`
기본 값	`"GET"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	- 상태 확인 프로토콜이 `HTTP`, `HTTPS`일 때만 적용 가능합니다.

health-monitor-expected-code

구분	내용
Annotation	`loadbalancer.kakaocloud.com/health-monitor-expected-code`
설명	상태 확인 체크 시 응답 받는 상태 코드를 설정할 수 있습니다.
값	정수 (100 ~ 999)
기본 값	`"200"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	- 상태 확인 프로토콜이 `HTTP`, `HTTPS`일 때만 적용 가능합니다.

timeout-client-data

구분	내용
Annotation	`loadbalancer.kakaocloud.com/timeout-client-data`
설명	클라이언트와 로드 밸런서 간 유휴 제한 시간을 설정합니다.
값	정수, `1000`~`4000000`ms
기본 값	`"50000"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	-

timeout-member-data

구분	내용
Annotation	`loadbalancer.kakaocloud.com/timeout-member-data`
설명	로드 밸런서와 멤버 간 유휴 제한 시간을 설정합니다.
값	정수, `1000`~`4000000`ms
기본 값	`"50000"`
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	-

load-balancer-subnet-ids

구분	내용
Annotation	`loadbalancer.kakaocloud.com/load-balancer-subnet-ids`
설명	로드 밸런서가 생성될 서브넷을 지정합니다.
값	`"{subnet-id}"` Subnet ID 목록(콤마로 구분)
기본 값	-
적용 및 수정	Service 생성 시점에만 적용됩니다.
비고	- 생성 후 값을 수정해도 기존 로드 밸런서에는 적용되지 않습니다. - 여러 서브넷을 입력할 경우, 각 AZ별로 가장 먼저 입력된 서브넷이 우선 적용되며, 지정되지 않은 AZ는 클러스터에 설정된 서브넷 중에서 임의로 선택되어 배치됩니다.

blb-name

구분	내용
Annotation	`loadbalancer.kakaocloud.com/blb-name`
설명	고가용성 그룹 이름을 설정합니다.
값	문자열 (4~26글자 이내, 영숫자 가능, 하이픈(-)만 사용 가능)
기본 값	-
적용 및 수정	Service 생성 시점에만 적용됩니다.
비고	- 고가용성 그룹을 지원하는 리전에서만 적용 가능합니다. - 생성 후 값을 수정해도 기존 로드 밸런서에는 적용되지 않습니다.

node-selector

구분	내용
Annotation	`loadbalancer.kakaocloud.com/node-selector`
설명	로드 밸런서 대상 그룹에 포함할 노드를 필터링합니다.
값	`key` 또는 `key=value` 목록
기본 값	-
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	- 수정 시 멤버 재구성 과정에서 일시적인 트래픽 영향이 발생할 수 있습니다. - 지정된 모든 `key` 또는 `key=value` 레이블을 포함한 노드만 대상으로 사용됩니다.

lb-method

구분	내용
Annotation	`loadbalancer.kakaocloud.com/lb-method`
설명	대상 그룹 트래픽 분산 알고리즘을 설정합니다.
값	`"ROUND_ROBIN"`/`"SOURCE_IP"`/`"LEAST_CONNECTIONS"`
기본 값	-
적용 및 수정	Service 생성 후 수정할 수 있습니다.
비고	- 수정 시 대상 그룹 설정이 반영되는 과정에서 일시적인 트래픽 영향이 발생할 수 있습니다.

Kubernetes Service Annotation 변경 내역

주의

현재 버전 클러스터에서는 이전 버전 annotation을 지원하지 않으므로, Service 작성 또는 수정 시 이 표를 참고하여 반드시 현재 버전 annotation을 사용하시기 바랍니다.

기능	이전 버전 annotation	현재 버전 annotation
LB 타입 지정	`loadbalancer.ke.kakaocloud.com/load-balancer-type`	- annotation으로 지정할 수 없습니다. - `spec.loadBalancerClass` 필드로 지정합니다 (`loadbalancer.kakaocloud.com/nlb`, `loadbalancer.kakaocloud.com/alb`)
퍼블릭 IP 사용 여부 지정	`service.beta.kubernetes.io/openstack-internal-load-balancer`	`loadbalancer.kakaocloud.com/load-balancer-scheme`
TLS 인증서	`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`
클라이언트 유휴 제한 시간	`loadbalancer.openstack.org/timeout-client-data`	`loadbalancer.kakaocloud.com/timeout-client-data`
멤버 유휴 제한 시간	`loadbalancer.openstack.org/timeout-member-data`	`loadbalancer.kakaocloud.com/timeout-member-data`
상태 확인 사용 여부	`loadbalancer.openstack.org/enable-health-monitor`	`loadbalancer.kakaocloud.com/enable-health-monitor`
상태 확인 delay/timeout/retries	`loadbalancer.openstack.org/health-monitor-*`	`loadbalancer.kakaocloud.com/health-monitor-*`
LB 알고리즘	`loadbalancer.openstack.org/lb-method`	`loadbalancer.kakaocloud.com/lb-method`
Subnet 지정	`loadbalancer.ke.kakaocloud.com/load-balancer-subnet-ids`	`loadbalancer.kakaocloud.com/load-balancer-subnet-ids`
고가용성 그룹 이름	`loadbalancer.ke.kakaocloud.com/blb-name`	`loadbalancer.kakaocloud.com/blb-name`
퍼블릭 IP 삭제 정책	`loadbalancer.ke.kakaocloud.com/delete-floatingip`	`loadbalancer.kakaocloud.com/delete-floatingip`

안내

현재 버전 클러스터에서는 loadbalancer.ke.kakaocloud.com/*, loadbalancer.openstack.org/*, service.beta.kubernetes.io/openstack-internal-load-balancer를 사용하지 않습니다.

All-options 예시

NLB(all options)

NLB all-options 예시
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.{region}/v1/secrets/{secret-id}'
    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 예시
kind: Service
apiVersion: v1
metadata:
  name: my-alb-service
  annotations:
    loadbalancer.kakaocloud.com/load-balancer-scheme: 'internet-facing'
    loadbalancer.kakaocloud.com/x-forwarded-for: 'append'
    loadbalancer.kakaocloud.com/x-forwarded-port: 'true'
    loadbalancer.kakaocloud.com/x-forwarded-proto: 'true'
    loadbalancer.kakaocloud.com/tls-container-refs: 'https://key-manager.{region}/v1/secrets/{secret-id-1},https://key-manager.{region}/v1/secrets/{secret-id-2}'
    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

LoadBalancer Type Service 삭제

LoadBalancer 유형으로 생성한 Service를 삭제하면 연동된 로드 밸런서도 함께 삭제됩니다.

Service 삭제
kubectl --kubeconfig=$KUBE_CONFIG delete svc {SERVICE_NAME}

loadbalancer.kakaocloud.com/delete-floatingip를 "false"로 설정하면, 로드 밸런서 삭제 시 퍼블릭 IP는 분리(detach)됩니다.
loadbalancer.kakaocloud.com/delete-floatingip를 "true"로 설정하면, 로드 밸런서 삭제 시 연결된 퍼블릭 IP도 함께 삭제됩니다.
internal 유형에서는 퍼블릭 IP가 생성되지 않으므로 delete-floatingip는 적용되지 않습니다.

로드 밸런서 생성​

사전 작업​

kubectl 설치 및 제어 설정​

SSL 인증서 등록 및 관리(선택)​

Step 1. Service 명세 확인​

NLB 로드 밸런서 유형 서비스 명세 확인​

ALB 로드 밸런서 유형 서비스 명세 확인​

Step 2. 로드 밸런서 유형 선택​

Step 3. 로드 밸런서 퍼블릭 노출 여부 설정​

Step 4. Service 생성 및 상태 확인​

Protocol 매핑 및 제약​

지원 프로토콜 조합​

부록​

Annotation 전체 목록​

ALB 전용 annotation​

x-forwarded-for​

x-forwarded-port​

x-forwarded-proto​

NLB 전용 annotation​

proxy-protocol​

공통 annotation​

tls-container-refs​

tls-minimum-version​

load-balancer-scheme​

delete-floatingip​

enable-health-monitor​

health-monitor-http-version​

health-monitor-protocol​

health-monitor-delay​

health-monitor-timeout​

health-monitor-max-retries​

health-monitor-max-retries-down​

health-monitor-url-path​

health-monitor-http-method​

health-monitor-expected-code​

timeout-client-data​

timeout-member-data​

load-balancer-subnet-ids​

blb-name​

node-selector​

lb-method​

Kubernetes Service Annotation 변경 내역​

All-options 예시​

NLB(all options)​

ALB(all options)​

LoadBalancer Type Service 삭제​