로드 밸런서 생성 및 제어
로드 밸런서(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/* 어노테이션을 사용하는 Kubernetes Engine 서비스를 대상으로 하며, v1.30 이상 버전 클러스터에서만 지원됩니다.
spec.loadBalancerClass로 로드 밸런서 유형을 지정합니다.loadbalancer.kakaocloud.com/*annotation만 사용합니다.- 기존 클러스터에서 이전 annotation을 사용 중이라면 이전 버전 가이드를 참고하시기 바랍니다.
로드 밸런서 생성
범위 안내
이 문서에서 설명하는 프로토콜, annotation, 제약 사항은 Kubernetes Engine의 Service 연동 기준입니다.
카카오클라우드 Load Balancing 서비스 전체 기능과 일부 차이가 있을 수 있습니다.
Kubernetes Engine에서 로드 밸런서를 생성하는 방법은 다음과 같습니다.
주의
kr-central-2 리전의 Kubernetes Engine에서 생성된 로드 밸런서는 고가용성(High Availability)으로 구성됩니다. 클러스터 네트워크에 포함된 모든 가용 영역(AZ)에 자동으로 분산 배치되어, 별도의 설정 없이도 안정적인 서비스 운영이 가능합니다.
따라서 실제 워크로드가 일부 AZ에서만 동작하더라도, 로드밸런서는 전체 AZ 기준으로 리소스가 할당됩니다. 이로 인해 각 AZ에 생성된 로드밸런서가 모두 과금 대상에 포함되므로 유의해 주세요.
사전 작업
Step 1. kubectl 설치 및 제어 설정하기
Kubernetes에서 Service 객체를 생성하려면 kubectl 설치 및 제어 설정이 필요합니다.
자세한 방법은 kubectl 제어 설정을 참고하시기 바랍니다.
Step 2. 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를 삭제해주세요.
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 전체 목록
설정 및 관리 안내
- 헬스 모니터 비활성화 주의:
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 전체 목록
| 구분 | 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" |
| 기본 값 | - |
| 적용 및 수정 | 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~4000000ms |
| 기본 값 | "50000" |
| 적용 및 수정 | Service 생성 후 수정할 수 있습니다. |
| 비고 | - |
timeout-member-data
| 구분 | 내용 |
|---|---|
| Annotation | loadbalancer.kakaocloud.com/timeout-member-data |
| 설명 | 로드 밸런서와 멤버 간 유휴 제한 시간을 설정합니다. |
| 값 | 정수, 1000~4000000ms |
| 기본 값 | "50000" |
| 적용 및 수정 | Service 생성 후 수정할 수 있습니다. |
| 비고 | - |
load-balancer-subnet-ids
| 구분 | 내용 |
|---|---|
| Annotation | loadbalancer.kakaocloud.com/load-balancer-subnet-ids |
| 설명 | 로드 밸런서가 생성될 서브넷을 지정합니다. |
| 값 | "{subnet-id}" Sunbet 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 포함한 label을 가진 노드만 대상으로 사용됩니다. |
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.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 예시
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
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는 적용되지 않습니다.