ALB Ingress Controller 설정

Kubernetes에서 생성한 네이버 클라우드 플랫폼의 로드밸런서를 Kubernetes의 Ingress 리소스가 아닌 콘솔 및 API를 통해 설정하시는 경우, 상태 동기화에 문제가 발생할 수 있습니다. 생성된 로드밸런서에 대한 설정 변경은 반드시 Kubernetes에서 생성된 Ingress 리소스 수정을 통해 이루어져야 합니다.

ALB Ingress Controller 설치

클러스터에 ALB Ingress Controller를 설치한 후 준비하는 방법은 다음과 같습니다.

아래의 명령어를 실행하여 ALB Ingress Controller를 설치해 주십시오.

kube-system 네임스페이스에 alb-ingress-controller가 생성되며, 필요한 ServiceAccount, ClusterRole, ClusterRoleBinding, IngressClass 가 함께 생성됩니다.

kubectl --kubeconfig=$KUBE_CONFIG apply -f https://raw.githubusercontent.com/NaverCloudPlatform/nks-alb-ingress-controller/main/docs/install/fin/install.yaml

Kubernetes 1.19 버전 미만인 경우 https://raw.githubusercontent.com/NaverCloudPlatform/nks-alb-ingress-controller/v0.3.1/docs/install/pub/install.yaml 을 설치해 주십시오.

Ingress의 리소스에 spec.ingressClassName: alb 필드를 추가해 주십시오.

Kubernetes 1.19 버전 미만인 경우에는 kubernetes.io/ingress.class: alb 어노테이션을 추가해 주십시오.

ALB Ingress Controller 설정 및 어노테이션

ALB Ingress Controller 기본 설정

ALB Ingress Controller의 기본 설정에 대한 설명은 아래와 같습니다.

Service type: NodePort
Ingress를 통해 노출시킬 Service는 모두 NodePort type으로 생성하여야 합니다.

Default Rule
Default Rule은 매칭되는 Rule이 없을 때 적용되는 Rule이며, spec.defaultBackend에 설정할 수 있습니다.
별도의 rule 및 use-annotation 설정은 불가능하며, 설정하지 않았을 경우 80 포트로 설정된 기본 타깃 그룹이 생성됩니다.

Rule Priority
Ingress에서 정의한 Rule의 순서에 따라 우선 순위가 결정됩니다. 가장 위에 있는 Rule의 우선 순위가 1로 설정됩니다.

ALB Ingress Controller 어노테이션

Kubernetes Ingress와 Service 오브젝트에 어노테이션을 사용하여 설정을 변경할 수 있습니다.

아래의 표를 참조하여 필요한 어노테이션을 사용해 주십시오. ALB Ingress Controller의 어노테이션은 모두 alb.ingress.kubernetes.io/로 시작합니다.

어노테이션	기본값	적용 리소스	설명
`alb.ingress.kubernetes.io/listen-ports`	`[{"HTTP":80}]` (인증서 번호가 설정되었다면 `[{"HTTPS":443}]`)	Ingress	Listener의 프로토콜 및 포트 설정 리스트. 사용 가능한 프로토콜: `HTTP`,`HTTPS`
`alb.ingress.kubernetes.io/description`	`Automatically Created By NKS`	Ingress	로드 밸런서 메모
`alb.ingress.kubernetes.io/ssl-certificate-no`	N/A	Ingress	프로토콜이 `HTTPS`인 리스너에 적용할 Certificate Manager의 인증서 번호. 콤마 구분자를 통한 다중 인증서 등록 가능. (인증서 번호는 Resource Manager의 nrn에서 확인 가능) (예: nrn:PUB:CertificateManager::000:Certificate/External/${certificateNo})
`alb.ingress.kubernetes.io/ssl-min-version`	`TLSV10`	Ingress	TLS Protocol 버전 - 설정 가능한 버전 및 값 TLS v1.0: `TLSV10` TLS v1.1: `TLSV11` TLS v1.2: `TLSV12`
`alb.ingress.kubernetes.io/enable-http2`	`false`	Ingress	프로토콜이 `HTTPS`인 리스너의 HTTP/2 활성화 여부
`alb.ingress.kubernetes.io/cipher-suite-list`	리스너에서 지원하는 모든 cipher suite	Ingress	리스너에서 지원하는 Cipher Suite 목록 (예: `["TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA", "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256", "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"]`)
`alb.ingress.kubernetes.io/load-balancer-size`	`small`	Ingress	로드 밸런서의 부하처리 성능 설정 설정 가능한 값: `small`, `medium`, `large`, `xlarge`
`alb.ingress.kubernetes.io/idle-timeout`	`60`	Ingress	로드 밸런서의 Idle Timeout 설정
`alb.ingress.kubernetes.io/network-type`	`public`	Ingress	로드 밸런서의 네트워크 유형 설정(값 변경 시 로드 밸런서가 재생성됨) 사설: `private`, 공인: `public`
`alb.ingress.kubernetes.io/subnet-id`	`kube-system` `configmap(ncloud-config)`의 `lbSubnetNo`값	Ingress	로드 밸런서 생성을 위한 로드 밸런서 전용 서브넷의 ID 값(생성 시에만 사용)
`alb.ingress.kubernetes.io/actions.${actionName}`	N/A	Ingress	Listener Rule의 기능들을 사용하기 위한 설정(하단 설명 참고)
`alb.ingress.kubernetes.io/conditions.${conditionName}`	N/A	Ingress	Ingress Rule의 Host, Path 조건에 추가 조건을 적용하기 위한 설정(하단 설명 참고)
`alb.ingress.kubernetes.io/enable-access-log`	false	Ingress	액세스 로그 수집 설정 (Cloud Log Analytics 상품 이용 신청 필요)
`alb.ingress.kubernetes.io/load-balancer-name`	N/A	Ingress	로드 밸런서 이름 (생성 시에만 적용) 이름 명명 규칙: 길이 3 ~ 30자, 영어/숫자/'-' 만 허용, 영어로 시작
`alb.ingress.kubernetes.io/ssl-redirect`	N/A	Ingress	SSL Redirect 대상 포트 설정
`alb.ingress.kubernetes.io/algorithm-type`	`round-robin`	Ingress, Service	Target Group의 로드 밸런싱 알고리즘 설정 설정 가능한 값: `round-robin`, `least-connection`, `source-ip-hash`
`alb.ingress.kubernetes.io/unhealthy-threshold-count`	`2`	Ingress, Service	Health Check 실패 임계값
`alb.ingress.kubernetes.io/healthy-threshold-count`	`2`	Ingress, Service	Health Check 성공 임계값
`alb.ingress.kubernetes.io/healthcheck-port`	TargetGroup 포트	Ingress, Service	Health Check 포트
`alb.ingress.kubernetes.io/healthcheck-path`	`/`	Ingress, Service	Health Check URL 경로
`alb.ingress.kubernetes.io/healthcheck-interval-seconds`	`30`	Ingress, Service	Health Check 주기(초)
`alb.ingress.kubernetes.io/healthcheck-protocol`	`HTTP`	Ingress, Service	Health Check 프로토콜 `HTTP`, `HTTPS`
`alb.ingress.kubernetes.io/backend-protocol`	`HTTP`	Ingress, Service	Target Group의 프로토콜 `HTTP`, `HTTPS`
`alb.ingress.kubernetes.io/enable-sticky-session`	`false`	Ingress, Service	Target Group의 Sticky Session 설정

어노테이션

기본값

적용 리소스

설명

alb.ingress.kubernetes.io/listen-ports

[{"HTTP":80}] (인증서 번호가 설정되었다면 [{"HTTPS":443}])

Ingress

Listener의 프로토콜 및 포트 설정 리스트.
사용 가능한 프로토콜: HTTP,HTTPS

alb.ingress.kubernetes.io/description

Automatically Created By NKS

Ingress

로드 밸런서 메모

alb.ingress.kubernetes.io/ssl-certificate-no

N/A

Ingress

프로토콜이 HTTPS인 리스너에 적용할 Certificate Manager의 인증서 번호. 콤마 구분자를 통한 다중 인증서 등록 가능.
(인증서 번호는 Resource Manager의 nrn에서 확인 가능)
(예: nrn:PUB:CertificateManager::000:Certificate/External/${certificateNo})

alb.ingress.kubernetes.io/ssl-min-version

TLSV10

Ingress

TLS Protocol 버전
- 설정 가능한 버전 및 값
TLS v1.0: TLSV10
TLS v1.1: TLSV11
TLS v1.2: TLSV12

alb.ingress.kubernetes.io/enable-http2

false

Ingress

프로토콜이 HTTPS인 리스너의 HTTP/2 활성화 여부

alb.ingress.kubernetes.io/cipher-suite-list

리스너에서 지원하는 모든 cipher suite

Ingress

리스너에서 지원하는 Cipher Suite 목록
(예:

["TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA", "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256", "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"]

)

alb.ingress.kubernetes.io/load-balancer-size

small

Ingress

로드 밸런서의 부하처리 성능 설정
설정 가능한 값: small, medium, large, xlarge

alb.ingress.kubernetes.io/idle-timeout

60

Ingress

로드 밸런서의 Idle Timeout 설정

alb.ingress.kubernetes.io/network-type

public

Ingress

로드 밸런서의 네트워크 유형 설정(값 변경 시 로드 밸런서가 재생성됨)
사설: private, 공인: public

alb.ingress.kubernetes.io/subnet-id

kube-system configmap(ncloud-config)의 lbSubnetNo값

Ingress

로드 밸런서 생성을 위한 로드 밸런서 전용 서브넷의 ID 값(생성 시에만 사용)

alb.ingress.kubernetes.io/actions.${actionName}

N/A

Ingress

Listener Rule의 기능들을 사용하기 위한 설정(하단 설명 참고)

alb.ingress.kubernetes.io/conditions.${conditionName}

N/A

Ingress

Ingress Rule의 Host, Path 조건에 추가 조건을 적용하기 위한 설정(하단 설명 참고)

alb.ingress.kubernetes.io/enable-access-log

false

Ingress

액세스 로그 수집 설정 (Cloud Log Analytics 상품 이용 신청 필요)

alb.ingress.kubernetes.io/load-balancer-name

N/A

Ingress

로드 밸런서 이름 (생성 시에만 적용)
이름 명명 규칙: 길이 3 ~ 30자, 영어/숫자/'-' 만 허용, 영어로 시작

alb.ingress.kubernetes.io/ssl-redirect

N/A

Ingress

SSL Redirect 대상 포트 설정

alb.ingress.kubernetes.io/algorithm-type

round-robin

Ingress, Service

Target Group의 로드 밸런싱 알고리즘 설정
설정 가능한 값: round-robin, least-connection, source-ip-hash

alb.ingress.kubernetes.io/unhealthy-threshold-count

2

Ingress, Service

Health Check 실패 임계값

alb.ingress.kubernetes.io/healthy-threshold-count

2

Ingress, Service

Health Check 성공 임계값

alb.ingress.kubernetes.io/healthcheck-port

TargetGroup 포트

Ingress, Service

Health Check 포트

alb.ingress.kubernetes.io/healthcheck-path

/

Ingress, Service

Health Check URL 경로

alb.ingress.kubernetes.io/healthcheck-interval-seconds

30

Ingress, Service

Health Check 주기(초)

alb.ingress.kubernetes.io/healthcheck-protocol

HTTP

Ingress, Service

Health Check 프로토콜
HTTP, HTTPS

alb.ingress.kubernetes.io/backend-protocol

HTTP

Ingress, Service

Target Group의 프로토콜
HTTP, HTTPS

alb.ingress.kubernetes.io/enable-sticky-session

false

Ingress, Service

Target Group의 Sticky Session 설정

alb.ingress.kubernetes.io/actions.${actionName}: actions 모델에 맞게 JSON 형태의 string으로 작성하여 Listener Rule의 추가 기능들을 설정할 수 있습니다. Ingress에 설정된 Rule의 service.name을 사용하고자 하는 ${actionName}으로 설정하고, service.port.name를 use-annotation으로 설정하면 어노테이션이 적용됩니다.

속성	타입	설명
`type`	string	`action`의 `type`을 정의 설정 가능한 값 `targetGroup`, `redirection`
`targetGroup`	object	`action`의 `type`을 `targetGroup`으로 설정한 경우 사용
`targetGroup.targetGroups`	array	트래픽을 전달할 Service의 목록
`targetGroup.targetGroups[n].serviceName`	string	`service name`
`targetGroup.targetGroups[n].servicePort`	number	`service port`
`targetGroup.enableStickySession`	boolean	sticky session 활성화 여부 기본값: `false`
`redirection`	object	action의 `type`을 `redirection`으로 설정한 경우 사용
`redirection.host`	string	기본값: `#{host}`
`redirection.path`	string	기본값: `/#{path}`
`redirection.query`	string	기본값: `#{query}`
`redirection.port`	string	redirection 포트 기본값: `#{port}`
`redirection.protocol`	string	설정 가능한 프로토콜: `HTTP`, `HTTPS` 기본값: `#{protocol}`
`redirection.statusCode`	number	설정 가능한 코드: `301`, `302`

속성

타입

설명

type

string

action의 type을 정의
설정 가능한 값 targetGroup, redirection

targetGroup

object

action의 type을 targetGroup으로 설정한 경우 사용

targetGroup.targetGroups

array

트래픽을 전달할 Service의 목록

targetGroup.targetGroups[n].serviceName

string

service name

targetGroup.targetGroups[n].servicePort

number

service port

targetGroup.enableStickySession

boolean

sticky session 활성화 여부
기본값: false

redirection

object

action의 type을 redirection으로 설정한 경우 사용

redirection.host

string

기본값: #{host}

redirection.path

string

기본값: /#{path}

redirection.query

string

기본값: #{query}

redirection.port

string

redirection 포트
기본값: #{port}

redirection.protocol

string

설정 가능한 프로토콜: HTTP, HTTPS
기본값: #{protocol}

redirection.statusCode

number

설정 가능한 코드: 301, 302

alb.ingress.kubernetes.io/conditions.${conditionName}: conditions 모델에 알맞은 JSON 형태의 string으로 작성하여 Ingress에 정의된 Host, Path 조건 외에 다른 조건들을 추가로 설정할 수 있습니다. 해당 조건들은 Ingress Rule에서 ${conditionName}과 일치하는 serviceName을 가진 Service에 적용됩니다.

속성	타입	설명
`field`	string	추가할 조건을 정의 설정 가능한 값 `hostHeader`, `pathPattern`
`hostHeader`	object	condition의 field를 `hostHeader`으로 설정한 경우 사용
`hostHeader.values`	array	`host` 목록
`hostHeader.values[n]`	string	`host` 값
`pathPattern`	object	`condition`의 `field`를 `pathPattern`으로 설정한 경우 사용
`pathPattern.values`	array	`path` 목록
`pathPattern.values[n]`	string	`path` 값
`httpHeader`	object	condition의 field를 httpHeader으로 설정한 경우 사용
`httpHeader.key`	string	header key 값
`httpHeader.values`	array	header value 값 목록

속성

타입

설명

field

string

추가할 조건을 정의
설정 가능한 값 hostHeader, pathPattern

hostHeader

object

condition의 field를 hostHeader으로 설정한 경우 사용

hostHeader.values

array

host 목록

hostHeader.values[n]

string

host 값

pathPattern

object

condition의 field를 pathPattern으로 설정한 경우 사용

pathPattern.values

array

path 목록

pathPattern.values[n]

string

path 값

httpHeader

object

condition의 field를 httpHeader으로 설정한 경우 사용

httpHeader.key

string

header key 값

httpHeader.values

array

header value 값 목록

예제 코드

ALB Ingress Controller에 대한 자세한 예제는 ALB Ingress Controller 활용 예제를 참조해 주십시오.

ALB Ingress Controller 설정

ALB Ingress Controller 설치