Documentation Index

Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt

Use this file to discover all available pages before exploring further.

Gateway API 사용

Prev Next

VPC 환경에서 이용 가능합니다.

Gateway API를 사용하면 Kubernetes의 GatewayClass, Gateway, HTTPRoute 리소스로 Application Load Balancer(ALB) 인스턴스를 생성하고 HTTP/HTTPS 트래픽을 라우팅할 수 있습니다.

Gateway API를 이용한 ALB 연동은 Kubernetes 1.36 이상 클러스터에서 Add-on으로 제공됩니다. NKS 콘솔의 Add-on에서 Gateway API Add-on을 활성화하면 사용할 수 있습니다.

주의
  • Gateway API로 생성된 Load Balancer는 Kubernetes 리소스로 관리됩니다.
  • Load Balancer를 콘솔 또는 API로 직접 수정하면 Kubernetes 리소스와 Load Balancer 상태가 달라질 수 있습니다. 설정 변경이 필요한 경우 Kubernetes 리소스를 수정해 주십시오.
  • 콘솔 또는 API를 이용한 직접 변경으로 발생한 문제에는 기술 지원이 제공되지 않습니다.
  • Gateway API에서 사용하는 기본 GatewayClass 이름은 ncloud-alb입니다.
  • Gateway API로 연결할 backend Service는 NodePort 타입이어야 합니다.

사전 준비 및 활성화

Gateway API Add-on을 활성화할 때 클러스터에 Gateway API CRD가 없으면 Add-on이 자동으로 설치하며, 이미 설치되어 있으면 기존 CRD를 그대로 두고 설치를 건너뜁니다. CRD를 직접 설치할 필요는 없습니다.

lb-controller는 gateway.networking.k8s.io/v1 API를 사용하며, 다른 namespace의 Service를 backend로 연결할 때 사용하는 ReferenceGrant도 v1로 참조합니다. ReferenceGrant는 Gateway API v1.6.0부터 v1로 제공되므로 Add-on은 Gateway API v1.6.0(Standard channel) CRD를 설치합니다.

NKS 콘솔의 Add-on에서 Gateway API Add-on을 활성화해 주십시오. Add-on을 활성화하면 gateway-adapter 컨트롤러와 함께 다음 리소스가 자동으로 생성됩니다.

  • GatewayClass ncloud-alb

활성화가 완료되면 다음 명령으로 ncloud-alb GatewayClass가 준비되었는지 확인할 수 있습니다.

kubectl get gatewayclass ncloud-alb
참고
  • Add-on은 이미 설치된 Gateway API CRD를 덮어쓰거나 업그레이드하지 않습니다. 기존에 설치된 CRD 버전이 v1.6.0 미만이면 ReferenceGrant가 v1로 제공되지 않아 다른 namespace의 Service를 backend로 사용하는 기능이 동작하지 않으므로, 필요하면 CRD를 v1.6.0 이상으로 직접 업그레이드해 주십시오.

지원 범위

항목 지원 여부 설명
GatewayClass 지원 기본 GatewayClass 이름은 ncloud-alb
Gateway 지원 HTTP, HTTPS Listener 사용 가능
HTTPRoute 부분 지원 Host, Path, Header exact match, weighted backendRefs 지원
ReferenceGrant 지원 다른 namespace의 Service를 backend로 사용할 때 필요
Backend Service NodePort만 지원 ClusterIP, LoadBalancer, ExternalName 타입 Service는 backend로 사용 불가
HTTPS 지원 NCP Certificate Manager의 인증서 번호 사용
LoadBalancerTemplate 지원 Gateway API 표준 필드로 표현하기 어려운 ALB 속성을 설정할 때 사용

다음 항목은 지원하지 않거나 제한적으로 지원합니다. 자세한 내용은 Gateway API 미지원 필드를 참고해 주십시오.

  • TCPRoute, UDPRoute, TLSRoute, GRPCRoute
  • Secret 기반 TLS 인증서 참조
  • TLS passthrough
  • RequestRedirect, URLRewrite 등 HTTPRoute filter
  • Query parameter match, method match
  • 정규식 기반 Path 또는 Header match
  • Gateway API session persistence

Gateway 생성

Gateway API로 ALB를 생성하려면 Service, Gateway, HTTPRoute를 생성합니다.

Service 생성

Gateway API에서 backend로 사용하는 Service는 NodePort 타입이어야 합니다.

apiVersion: v1
kind: Service
metadata:
name: web
spec:
type: NodePort
selector:
app: web
ports:
- port: 80
targetPort: 80
nodePort: 30080

Gateway와 HTTPRoute 생성

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: web
spec:
gatewayClassName: ncloud-alb
listeners:
- name: http
port: 80
protocol: HTTP
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: web
spec:
parentRefs:
- name: web
hostnames:
- example.com
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: web
port: 80

LoadBalancerTemplate 설정

LoadBalancerTemplate은 Gateway API 표준 필드로 표현하기 어려운 NCP ALB 속성을 설정하는 리소스입니다. 사설 ALB, Subnet, Load Balancer 크기, HTTPS 인증서 번호, Target Group 헬스 체크, Sticky Session 등을 설정할 수 있습니다.

참고

LoadBalancerTemplate은 선택 사항입니다. GatewayClass ncloud-alb에는 parametersRef가 설정되지 않았으므로, LoadBalancerTemplate을 참조하지 않고 Gateway를 만들면 ALB는 공인(PUBLIC) 타입으로 클러스터 기본 Load Balancer Subnet에 생성되며 나머지 속성에는 필드 기본값 표의 기본값이 적용됩니다.

LoadBalancerTemplate은 다음 위치에서 참조할 수 있습니다.

참조 위치 용도 비고
GatewayClass.spec.parametersRef 클러스터 기본 ALB 설정 클러스터 공통 기본값이 필요할 때 운영자가 구성
Gateway.spec.infrastructure.parametersRef Gateway별 ALB 설정 Gateway와 같은 namespace의 LoadBalancerTemplate 참조

Gateway에서 개별 설정을 적용하려면 Gateway와 같은 namespace에 LoadBalancerTemplate을 생성한 후 Gateway.spec.infrastructure.parametersRef로 참조합니다.

apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1
kind: LoadBalancerTemplate
metadata:
name: web-template
spec:
networkType: PUBLIC
size: SMALL
idleTimeoutSeconds: 60
accessLogEnabled: false
defaults:
targetGroup:
protocol: HTTP
algorithmType: RR
healthCheck:
protocol: HTTP
method: GET
path: /
port: 0
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: web
spec:
gatewayClassName: ncloud-alb
infrastructure:
parametersRef:
group: loadbalancer.vnks.ncloud.com
kind: LoadBalancerTemplate
name: web-template
listeners:
- name: http
port: 80
protocol: HTTP

LoadBalancerTemplate 전체 스펙

LoadBalancerTemplate의 spec 필드는 모두 선택 항목입니다. 다음은 사용할 수 있는 모든 필드를 담은 전체 구조이며, 지정하지 않은 필드에는 필드 기본값 표에 정리된 기본값이 적용됩니다.

주석의 기본값은 해당 필드를 생략했을 때 적용되는 값이며, 자동은 고정값이 아니라 생략 시 클러스터 설정(ncloud-config)·NCP 서버 기본값·컨트롤러 파생값 중 하나로 결정됨을 의미합니다. 필드별 구체적인 의미는 필드 기본값 표를 참고해 주십시오.

apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1
kind: LoadBalancerTemplate
metadata:
name: full-template
spec:
# --- Load Balancer 인프라 속성 ---
name: my-alb # provider LB 이름 · 기본값: 자동(<Gateway namespace>-<Gateway 이름>)
networkType: PUBLIC # PUBLIC | PRIVATE · 기본값: PUBLIC
size: SMALL # SMALL | MEDIUM | LARGE | XLARGE · 기본값: 자동
description: "example template" # LB 설명 · 기본값: "Managed by Gateway <namespace>/<name>"
idleTimeoutSeconds: 60 # 유휴 연결 유지 시간(초), 1~3600 · 기본값: 60
accessLogEnabled: false # ALB 접근 로그 사용 여부 · 기본값: false
skipAcgUpdate: true # LB 생성 시 ACG 업데이트 생략 여부 · 기본값: false
lbSubnetIds: # LB를 배치할 Subnet ID 목록 · 기본값: 자동(클러스터 기본 LB Subnet)
- 12345
publicIpInstanceNo: 123456 # PUBLIC LB에 연결할 공인 IP 인스턴스 번호 · 기본값: 자동(자동 할당)
retainPublicIpOnTermination: false # LB 삭제 시 공인 IP 보존 여부 · 기본값: false

# --- 모든 Listener에 공통 적용되는 기본값 ---
defaults:
http2Enabled: false # HTTP/2 사용 여부 · 기본값: false
sslRedirectPort: 0 # 0보다 크면 HTTP→HTTPS 리다이렉트 룰 자동 생성 · 기본값: 0(비활성)
aclId: 0 # 연결할 ACL ID, 0이면 미사용 · 기본값: 0
targetGroup:
protocol: HTTP # HTTP | HTTPS · 기본값: HTTP
algorithmType: RR # RR | LC | SIPHS · 기본값: RR
stickySession: false # Sticky Session 사용 여부 · 기본값: false
proxyProtocol: false # ALB Gateway에서는 true 사용 불가 · 기본값: false
healthCheck:
protocol: HTTP # HTTP | HTTPS · 기본값: HTTP
method: GET # GET | HEAD · 기본값: GET
path: / # 헬스 체크 경로 · 기본값: /
port: 0 # 0이면 traffic-port 사용 · 기본값: 0
intervalSeconds: 30 # 헬스 체크 간격(초) · 기본값: 30
healthyThresholdCount: 2 # 정상 판정 연속 성공 횟수 · 기본값: 2
unhealthyThresholdCount: 2 # 비정상 판정 연속 실패 횟수 · 기본값: 2

# --- 특정 포트 Listener에만 적용되는 개별 설정 (defaults 오버라이드) ---
listeners:
- port: 443 # (필수) 설정을 적용할 Gateway Listener 포트, 1~65535
protocol: HTTPS # (필수) HTTP | HTTPS
http2Enabled: true # 기본값: defaults.http2Enabled 값
sslRedirectPort: 0 # 기본값: defaults.sslRedirectPort 값
aclId: 12345 # 기본값: defaults.aclId 값
tls: # protocol: HTTPS일 때 사용
certificateNos: # (HTTPS 시 필수) NCP Certificate Manager 인증서 번호
- 123456
minVersion: TLSV12 # TLSV10 | TLSV11 | TLSV12 | TLSV13 · 기본값: TLSV10
cipherSuiteList: # 허용할 암호화 스위트 목록 · 기본값: 자동
- TLS_RSA_WITH_AES_128_GCM_SHA256
targetGroup: # 이 Listener의 TG 설정 · 기본값: defaults.targetGroup 값
protocol: HTTP
algorithmType: RR
stickySession: false
healthCheck:
protocol: HTTP
method: GET
path: /
rules: # 이 Listener의 라우팅 룰(조건·액션) · 지정 시 HTTPRoute 생성 룰을 대체
- priority: 1 # (필수) 평가 우선순위, 1~10000 (낮을수록 먼저 평가)
conditions: # 매칭 조건 · 여러 타입 조합 시 AND · 타입별 1개(같은 타입 중복 불가)
- type: HostHeader # HostHeader | PathPattern | HttpHeader · 필요한 타입만 지정
hostHeader:
values: ["api.example.com"] # 복수 값이면 OR
- type: PathPattern
pathPattern:
values: ["/old", "/old/*"]
- type: HttpHeader
httpHeader:
headerName: X-Env
values: ["canary"]
action: # (필수)
type: Redirect # ForwardTargetGroup | Redirect
redirect: # type: Redirect일 때 사용
protocol: HTTPS # HTTP | HTTPS
port: "443" # Redirect 시 포트 지정 필요
statusCode: "301" # 301 | 302
# host/path/query 미지정 시 원래 요청 값 유지
# forwardTargetGroup: # type: ForwardTargetGroup일 때 사용
# targets:
# - {targetGroupName: <컨트롤러 자동 생성 TG 이름>, weight: 1}
# enableStickySession: false

spec.defaults와 spec.listeners[]는 공통 필드(http2Enabled, sslRedirectPort, aclId, targetGroup)를 동일하게 사용하며, tls와 rules는 spec.listeners[]에서만 지정할 수 있습니다. 특정 포트에만 다른 값을 적용하려는 경우에만 spec.listeners[]를 작성합니다.

필드 기본값

지정하지 않은 필드에는 다음 표의 기본값이 적용됩니다. 자동은 고정값이 아니라 생략 시 클러스터 설정(ncloud-config)·NCP 서버 기본값·컨트롤러 파생값 중 하나로 결정됨을 의미하며, 필드별 출처는 각 행의 기본값·설명에 표기했습니다.

필드 타입 기본값 설명
name string 자동
  • provider Load Balancer 이름
  • 미지정 시 생성되는 LoadBalancer 리소스 이름(<Gateway namespace>-<Gateway 이름>) 사용
networkType string PUBLIC
  • Load Balancer 네트워크 타입
  • PUBLIC 또는 PRIVATE 입력
size string 자동(NCP 서버 기본값)
  • Load Balancer 부하 처리 성능
  • SMALL, MEDIUM, LARGE, XLARGE 중 하나 입력
description string Managed by Gateway <namespace>/<name> Load Balancer 설명
idleTimeoutSeconds int 60
  • 유휴 연결 유지 시간(초)
  • 1~3600 범위에서 설정
accessLogEnabled bool false ALB 접근 로그 사용 여부
skipAcgUpdate bool false
  • Load Balancer 생성 시 노드 ACG 업데이트 생략 여부
  • 기본값 false에서는 컨트롤러가 노드 ACG에 LB Subnet inbound 룰을 등록해 ALB 트래픽이 노드에 도달하도록 함
lbSubnetIds []int 자동
  • Load Balancer를 배치할 Subnet ID 목록
  • 미지정 시 ncloud-config의 Subnet 사용(PUBLIC은 lbPublicSubnetNo, PRIVATE은 lbSubnetNo)
publicIpInstanceNo int 자동
  • PUBLIC Load Balancer에 연결할 공인 IP 인스턴스 번호
  • 미지정 시 자동 할당
retainPublicIpOnTermination bool false Load Balancer 삭제 시 공인 IP 보존 여부
defaults.http2Enabled bool false
  • HTTP/2 사용 여부
  • HTTPS Listener에서만 적용되며 HTTP Listener에서는 무시됨
defaults.sslRedirectPort int 0 0보다 크면 HTTP→HTTPS 리다이렉트 룰 자동 생성
defaults.aclId int 0
  • Listener에 연결할 ACL ID
  • 0이면 미사용
defaults.targetGroup.protocol string HTTP
  • backend Service로 전달할 프로토콜
  • HTTP 또는 HTTPS 입력
defaults.targetGroup.algorithmType string RR
  • 로드 밸런싱 알고리즘
  • RR, LC, SIPHS 중 하나 입력
defaults.targetGroup.stickySession bool false Sticky Session 사용 여부
defaults.targetGroup.proxyProtocol bool false
  • Proxy Protocol 사용 여부
  • ALB Gateway에서는 true 사용 불가
defaults.targetGroup.healthCheck.protocol string HTTP
  • 헬스 체크 프로토콜
  • HTTP 또는 HTTPS 입력
defaults.targetGroup.healthCheck.method string GET
  • HTTP/HTTPS 헬스 체크 메서드
  • GET 또는 HEAD 입력
defaults.targetGroup.healthCheck.path string / HTTP/HTTPS 헬스 체크 경로
defaults.targetGroup.healthCheck.port int 0
  • 헬스 체크 포트
  • 0이면 traffic-port 사용
defaults.targetGroup.healthCheck.intervalSeconds int 30 헬스 체크 간격(초)
defaults.targetGroup.healthCheck.healthyThresholdCount int 2 정상 판정 연속 성공 횟수
defaults.targetGroup.healthCheck.unhealthyThresholdCount int 2 비정상 판정 연속 실패 횟수
listeners[].port int (필수)
  • 설정을 적용할 Gateway Listener 포트
  • 1~65535 범위에서 설정
listeners[].protocol string (필수)
  • Listener 프로토콜
  • HTTP 또는 HTTPS 입력
listeners[].tls.certificateNos []int (HTTPS 시 필수) NCP Certificate Manager 인증서 번호
listeners[].tls.minVersion string TLSV10
  • TLS 최소 버전
  • TLSV10, TLSV11, TLSV12, TLSV13 중 하나 입력
  • 미지정 시 TLSV10 적용
listeners[].tls.cipherSuiteList []string 자동
  • 허용할 암호화 스위트 목록
  • 미지정 시 리스너가 지원하는 전체 cipher suite 적용
listeners[].http2Enabled bool defaults 값
  • 해당 Listener의 HTTP/2 사용 여부
  • HTTPS Listener에서만 적용되며 HTTP Listener에서는 무시됨
listeners[].sslRedirectPort int defaults 값 해당 Listener의 HTTP→HTTPS 리다이렉트 포트
listeners[].aclId int defaults 값 해당 Listener에 연결할 ACL ID
listeners[].targetGroup object defaults.targetGroup 값
  • 해당 Listener의 Target Group 설정
  • 필드 구조는 defaults.targetGroup과 동일
listeners[].rules []object -
  • 해당 Listener의 라우팅 룰(조건·액션) 목록
  • HTTPRoute로 표현할 수 없는 조건·액션(예: Redirect)을 직접 지정할 때 사용
  • 지정하면 해당 Listener에서 HTTPRoute로부터 생성되는 룰을 대체함
  • Listener 라우팅 룰 직접 지정 참고
listeners[].rules[].priority int (필수)
  • 룰 평가 우선순위
  • 1~10000 범위에서 설정하며 낮을수록 먼저 평가
listeners[].rules[].conditions []object -
  • 매칭 조건 목록
  • 여러 타입을 함께 지정하면 AND로 평가되며, 각 타입(HostHeader/PathPattern/HttpHeader)은 룰당 1개만(같은 타입 중복 불가) 지정 가능
  • 한 조건의 values가 여러 개면 OR
  • 빈 목록이면 모든 요청과 매칭
listeners[].rules[].action object (필수)
  • 조건 매칭 시 수행할 액션
  • ForwardTargetGroup(Target Group 전달) 또는 Redirect(HTTP 리다이렉트) 지정
참고
  • listeners[]의 필드를 지정하지 않으면 defaults에 설정한 값이, defaults에도 없으면 위 표의 기본값이 적용됩니다.
  • listeners[]는 port가 Gateway에 정의된 Listener와 일치할 때만 적용됩니다.

LoadBalancerTemplate 주요 설정 예제

LoadBalancerTemplate에 설정 목적에 따라 필요한 필드를 작성합니다.

Load Balancer 기본 속성 설정

Load Balancer의 네트워크 타입, 크기, 유휴 연결 유지 시간, 접근 로그 사용 여부를 설정할 수 있습니다.

apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1
kind: LoadBalancerTemplate
metadata:
name: alb-basic
spec:
networkType: PUBLIC
size: SMALL
idleTimeoutSeconds: 60
accessLogEnabled: false
  • networkType: Load Balancer 네트워크 타입입니다. PUBLIC 또는 PRIVATE를 입력합니다.
  • size: Load Balancer 부하 처리 성능입니다. SMALL, MEDIUM, LARGE, XLARGE 중 하나를 입력합니다.
  • idleTimeoutSeconds: 유휴 연결 유지 시간입니다. 1~3600초 범위에서 설정합니다.
  • accessLogEnabled: ALB 접근 로그 사용 여부입니다. true 또는 false를 입력합니다.

Load Balancer Subnet 설정

기본 Load Balancer Subnet이 아닌 다른 Subnet에 ALB를 생성해야 하는 경우 lbSubnetIds를 설정합니다.

apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1
kind: LoadBalancerTemplate
metadata:
name: alb-subnet
spec:
networkType: PRIVATE
lbSubnetIds:
- 12345
  • lbSubnetIds: Load Balancer가 생성될 Subnet ID입니다.
  • networkType과 일치하는 Load Balancer Subnet을 입력해야 합니다.
  • lbSubnetIds를 설정하지 않으면 클러스터에 설정된 기본 Load Balancer Subnet을 사용합니다.

공인 IP 설정

공인 ALB에 특정 공인 IP를 연결하거나, ALB 삭제 시 공인 IP를 보존하려면 다음 필드를 사용합니다.

apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1
kind: LoadBalancerTemplate
metadata:
name: alb-public-ip
spec:
networkType: PUBLIC
publicIpInstanceNo: 123456
retainPublicIpOnTermination: true
  • publicIpInstanceNo: ALB에 연결할 공인 IP 인스턴스 번호입니다. networkType: PUBLIC에서 사용합니다.
  • retainPublicIpOnTermination: ALB 삭제 시 공인 IP를 보존할지 여부입니다.

Target Group 기본값 설정

Gateway에 연결된 Service로 트래픽을 전달할 때 사용할 Target Group 기본값을 설정할 수 있습니다.

apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1
kind: LoadBalancerTemplate
metadata:
name: alb-target-group
spec:
defaults:
targetGroup:
protocol: HTTP
algorithmType: RR
stickySession: false
healthCheck:
protocol: HTTP
method: GET
path: /
port: 0
intervalSeconds: 30
healthyThresholdCount: 2
unhealthyThresholdCount: 2
  • protocol: backend Service로 전달할 프로토콜입니다. HTTP 또는 HTTPS를 입력합니다.
  • algorithmType: 로드 밸런싱 알고리즘입니다. RR, LC, SIPHS 중 하나를 입력합니다.
  • stickySession: Sticky Session 사용 여부입니다. Gateway API의 session persistence 필드 대신 이 값을 사용합니다.
  • healthCheck.protocol: 헬스 체크 프로토콜입니다. HTTP 또는 HTTPS를 입력합니다.
  • healthCheck.method: HTTP/HTTPS 헬스 체크 메서드입니다. GET 또는 HEAD를 입력합니다.
  • healthCheck.path: HTTP/HTTPS 헬스 체크 경로입니다.
  • healthCheck.port: 헬스 체크 포트입니다. 0이면 traffic-port를 사용합니다.

Listener별 HTTPS 인증서 설정

HTTPS Listener를 사용할 때는 NCP Certificate Manager의 인증서 번호를 Listener별로 설정합니다.

apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1
kind: LoadBalancerTemplate
metadata:
name: alb-https
spec:
listeners:
- port: 443
protocol: HTTPS
tls:
certificateNos:
- 123456
minVersion: TLSV12
  • listeners[].port: 설정을 적용할 Gateway Listener 포트입니다.
  • listeners[].protocol: Listener 프로토콜입니다. HTTPS Listener에는 HTTPS를 입력합니다.
  • listeners[].tls.certificateNos: NCP Certificate Manager 인증서 번호입니다. Kubernetes Secret 기반 인증서 참조는 사용하지 않습니다.
  • listeners[].tls.minVersion: TLS 최소 버전입니다. TLSV10, TLSV11, TLSV12, TLSV13 중 하나를 입력합니다.

Listener별 ACL과 HTTP/2 설정

특정 Listener에 ACL을 연결하거나 HTTP/2를 활성화할 수 있습니다.

apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1
kind: LoadBalancerTemplate
metadata:
name: alb-listener-option
spec:
listeners:
- port: 443
protocol: HTTPS
aclId: 12345
http2Enabled: true
  • listeners[].aclId: Listener에 연결할 ACL ID입니다. 0이면 사용하지 않습니다.
  • listeners[].http2Enabled: 해당 Listener의 HTTP/2 사용 여부입니다. HTTP/2는 TLS 위에서 협상되므로 HTTPS Listener에서만 적용되며, HTTP Listener에 설정하면 무시됩니다.
참고

spec.defaults와 spec.listeners[]의 역할은 다음과 같이 구분됩니다.

  • spec.defaults: Gateway가 정의한 Listener 중 spec.listeners[]에 포트별 설정이 없는 Listener에 적용되는 기본값입니다. 즉, 개별 설정을 별도로 지정하지 않은 Listener는 이 기본값을 사용합니다.
  • spec.listeners[]: 특정 포트의 Listener에만 적용할 개별 설정입니다. port로 Gateway Listener와 매칭되며, 해당 Listener에 대해서는 spec.defaults 대신 이 설정이 우선 적용됩니다.

Listener 라우팅 룰 직접 지정 (conditions/actions)

기본적으로 ALB Listener의 라우팅 룰(조건·액션)은 HTTPRoute에서 자동 생성됩니다. HTTPRoute로 표현할 수 없는 조건·액션(대표적으로 Redirect)이 필요한 경우, LoadBalancerTemplate의 listeners[].rules[]에 룰을 직접 작성할 수 있습니다.

apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1
kind: LoadBalancerTemplate
metadata:
name: alb-redirect
spec:
listeners:
- port: 80
protocol: HTTP
rules:
- priority: 1 # 낮을수록 먼저 평가 (1~10000)
conditions: # 각 조건 타입은 룰당 1개만 지정 가능
- type: PathPattern
pathPattern:
values: ["/old", "/old/*"]
action:
type: Redirect # ForwardTargetGroup | Redirect
redirect:
protocol: HTTPS # HTTP | HTTPS
port: "443" # Redirect 시 포트 지정 필요
statusCode: "301" # 301 | 302
# host/path/query 미지정 시 원래 요청 값 유지

조건(conditions) 타입

타입 필드 설명
HostHeader hostHeader.values Host 헤더 매칭 값 목록
PathPattern pathPattern.values URL 경로 패턴 값 목록
HttpHeader httpHeader.headerName, httpHeader.values 임의 HTTP 헤더 이름과 값 목록

액션(action) 타입

타입 설명
ForwardTargetGroup
  • Target Group으로 전달
  • forwardTargetGroup.targets[].targetGroupName·weight로 가중치 분산
  • enableStickySession으로 세션 고정
Redirect
  • HTTP 리다이렉트
  • 세부 필드는 다음 표 참고

Redirect 액션의 세부 필드는 다음과 같습니다.

필드 타입 설명
redirect.protocol string
  • 리다이렉트 프로토콜(HTTP 또는 HTTPS)
  • 기본값: #{protocol}(원래 프로토콜 유지)
redirect.port string
  • 리다이렉트 포트
  • Redirect 액션 사용 시 필수(미지정 시 생성 거부)
redirect.statusCode string
  • 리다이렉트 상태 코드(301 또는 302)
  • 기본값: 301
redirect.host string
  • 리다이렉트 호스트
  • 기본값: #{host}(원래 호스트 유지)
redirect.path string
  • 리다이렉트 경로
  • 기본값: /#{path}(원래 경로 유지)
redirect.query string
  • 리다이렉트 쿼리스트링
  • 기본값: #{query}(원래 쿼리 유지)
주의
  • listeners[].rules[]를 지정하면 해당 Listener에서 HTTPRoute로부터 생성되는 룰 전체를 대체합니다(부분 병합이 아님). 따라서 HTTPRoute 라우팅과 직접 작성한 룰을 같은 Listener에서 혼용할 수 없습니다.
  • 한 룰에서 HostHeader·PathPattern·HttpHeader를 각각 1개씩 함께 지정할 수 있으며 AND로 평가됩니다. 단, 같은 타입을 2개 이상 넣을 수는 없습니다.
  • ForwardTargetGroup 액션의 targetGroupName은 컨트롤러가 자동 생성하는 Target Group 이름을 참조해야 하므로, 이 방식은 주로 Target Group이 필요 없는 Redirect 액션에 사용합니다.

사설 ALB 생성

사설 ALB가 필요한 경우 LoadBalancerTemplate에 networkType: PRIVATE을 설정한 후 Gateway에서 참조합니다.

apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1
kind: LoadBalancerTemplate
metadata:
name: private-alb
spec:
networkType: PRIVATE
lbSubnetIds:
- 12345
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: private-web
spec:
gatewayClassName: ncloud-alb
infrastructure:
parametersRef:
group: loadbalancer.vnks.ncloud.com
kind: LoadBalancerTemplate
name: private-alb
listeners:
- name: http
port: 80
protocol: HTTP

Load Balancer 관리 일시 중지

lb.ncloud.naver.com/pause: "true"는 Kubernetes 1.36 이상 KVM 클러스터에서 사용할 수 있는 일시 중지 옵션입니다. 이 값이 설정되면 컨트롤러의 spec/provider reconcile이 일시 중지됩니다.

적용 대상 동작
Gateway
  • pause 중에는 Gateway/HTTPRoute 변경이 Load Balancer 설정에 미반영
  • pause 상태에서 Gateway를 삭제해도 이미 생성된 NCloud LB/TG는 삭제하지 않고 유지
주의

pause는 이미 생성된 NCloud LB/TG를 보존하기 위한 옵션입니다. pause 상태에서는 누락된 Load Balancer 리소스를 새로 생성하지 않습니다. 변경 반영을 재개하려면 입력 리소스에서 pause 어노테이션을 제거해 주십시오.

HTTPS Listener 사용

Gateway API에서 HTTPS Listener를 사용할 때는 NCP Certificate Manager의 인증서 번호를 LoadBalancerTemplate에 입력합니다.

apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1
kind: LoadBalancerTemplate
metadata:
name: https-alb
spec:
listeners:
- port: 443
protocol: HTTPS
tls:
certificateNos:
- 123456
minVersion: TLSV12
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: web-https
spec:
gatewayClassName: ncloud-alb
infrastructure:
parametersRef:
group: loadbalancer.vnks.ncloud.com
kind: LoadBalancerTemplate
name: https-alb
listeners:
- name: https
port: 443
protocol: HTTPS
참고

Gateway API의 Secret 기반 TLS 인증서 참조는 사용하지 않습니다. NCP Certificate Manager 인증서 번호를 사용해 주십시오.

다른 namespace의 Service 연결

HTTPRoute가 다른 namespace의 Service를 backend로 참조하려면 Service가 있는 namespace에 ReferenceGrant를 생성해야 합니다.

apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
name: allow-route
namespace: backend-ns
spec:
from:
- group: gateway.networking.k8s.io
kind: HTTPRoute
namespace: route-ns
to:
- group: ""
kind: Service

ReferenceGrant가 없으면 다른 namespace의 Service는 backend로 사용할 수 없습니다.

Gateway API 미지원 필드

Gateway API 표준에는 다양한 필드와 Route 종류가 포함되지만, NKS Gateway API ALB 연동에서는 다음 범위만 지원합니다.

GatewayClass 및 Gateway

필드 지원 여부 설명 대안
GatewayClass.spec.parametersRef 지원 LoadBalancerTemplate 참조 지원 클러스터 공통 기본값이 필요할 때 운영자가 LoadBalancerTemplate을 참조하도록 구성
Gateway.spec.infrastructure.parametersRef 지원 Gateway와 같은 namespace의 LoadBalancerTemplate 참조 지원 Gateway별 ALB 설정 시 이 필드 사용
Gateway.spec.addresses 미지원 Gateway에서 직접 IP 주소를 요청하거나 예약하지 않음 고정 공인 IP는 LoadBalancerTemplate.spec.publicIpInstanceNo 사용
Gateway.spec.listeners[].hostname 지원
  • Listener에 지정한 hostname도 도메인 라우팅에 사용
  • HTTPRoute.spec.hostnames와 함께 적용
 -
Gateway.spec.listeners[].protocol: HTTP 지원 HTTP Listener 생성 -
Gateway.spec.listeners[].protocol: HTTPS 부분 지원 HTTPS Listener는 생성하지만 Secret 기반 인증서는 사용하지 않음 인증서 번호는 LoadBalancerTemplate.spec.listeners[].tls.certificateNos에 지정
Gateway.spec.listeners[].protocol: TLS 미지원 TLS passthrough Listener를 생성하지 않음 HTTPS Listener 사용
Gateway.spec.listeners[].protocol: TCP 미지원 TCP Listener를 생성하지 않음 Service type: LoadBalancer 사용
Gateway.spec.listeners[].protocol: UDP 미지원 UDP Listener를 생성하지 않음 Service type: LoadBalancer 사용
Gateway.spec.listeners[].tls.certificateRefs 미지원 Kubernetes Secret을 인증서로 사용하지 않음 NCP Certificate Manager 인증서 번호 사용
Gateway.spec.listeners[].tls.mode: Passthrough 미지원 ALB는 L7 종단 방식으로 동작 HTTPS Listener 사용
Gateway.spec.listeners[].allowedRoutes.namespaces.from 지원 Same, All, Selector 사용 가능 -
Gateway.spec.listeners[].allowedRoutes.kinds 부분 지원 HTTPRoute만 지원 HTTPRoute 사용

HTTPRoute

필드 지원 여부 설명 대안
HTTPRoute.spec.parentRefs 지원 Gateway 및 Listener 연결에 사용 -
HTTPRoute.spec.hostnames 지원 ALB Host header 조건으로 사용 -
HTTPRoute.spec.rules[].matches[].path.type: PathPrefix 지원 Path 조건으로 사용 -
HTTPRoute.spec.rules[].matches[].path.type: Exact 지원 Path 조건으로 사용 -
HTTPRoute.spec.rules[].matches[].path.type: RegularExpression 미지원 정규식 Path 조건 미지원 PathPrefix 또는 Exact 사용
HTTPRoute.spec.rules[].matches[].headers exact match 지원 Header exact match 조건으로 사용 -
HTTPRoute.spec.rules[].matches[].headers regex match 미지원 정규식 Header 조건 미지원 exact match 사용
HTTPRoute.spec.rules[].matches[].headers 다중 header (한 match에 2개 이상) 미지원 하나의 rule은 Header 조건을 1개만 가질 수 있어 여러 header를 AND로 매칭 불가 단일 header 조건 사용 또는 애플리케이션에서 처리
HTTPRoute.spec.rules[].matches[].queryParams 미지원 Query parameter 조건 미지원 애플리케이션에서 처리
HTTPRoute.spec.rules[].matches[].method 미지원 HTTP method 조건 미지원 애플리케이션에서 처리
HTTPRoute.spec.rules[].filters[].type: RequestRedirect 미지원 HTTPRoute의 Redirect filter 미지원 LoadBalancerTemplate의 listeners[].rules[]에 Redirect 액션 직접 지정(Listener 라우팅 룰 직접 지정)
HTTPRoute.spec.rules[].filters[].type: URLRewrite 미지원 URL rewrite filter 미지원 애플리케이션에서 처리
HTTPRoute.spec.rules[].filters[].type: RequestHeaderModifier 미지원 Request header modifier 미지원 애플리케이션에서 처리
HTTPRoute.spec.rules[].filters[].type: ResponseHeaderModifier 미지원 Response header modifier 미지원 애플리케이션에서 처리
HTTPRoute.spec.rules[].filters[].type: RequestMirror 미지원 Request mirror 미지원 별도 미러링 구성 사용
HTTPRoute.spec.rules[].backendRefs[].kind: Service 지원 Service를 backend로 사용 가능 Service type: NodePort 사용
Service 외 backendRef kind 미지원 Service가 아닌 backendRef 미지원 Service backend 사용
다른 namespace의 backendRef 부분 지원 ReferenceGrant가 있는 경우에만 사용 가능 backend namespace에 ReferenceGrant 생성
HTTPRoute.spec.rules[].backendRefs[].weight 지원 Backend 가중치로 사용 -
backend Service type: ClusterIP 미지원 NodePort가 없어 Target Group backend로 사용 불가 Service type: NodePort 사용
backend Service type: LoadBalancer 미지원 Gateway backend로 사용하지 않음 Service type: NodePort 사용
backend Service type: ExternalName 미지원 Gateway backend로 사용하지 않음 Service type: NodePort 사용
Gateway API sessionPersistence 미지원 Gateway API session persistence 필드 미사용 LoadBalancerTemplate의 Target Group stickySession 사용
Rule 또는 backend 단위 timeout 미지원 Gateway API timeout 필드 미사용 Load Balancer idle timeout은 LoadBalancerTemplate.spec.idleTimeoutSeconds 사용

상태 확인

Gateway와 HTTPRoute 상태는 다음 명령으로 확인할 수 있습니다.

kubectl get gateway
kubectl get httproute

상세 상태를 확인하려면 다음 명령을 실행해 주십시오.

kubectl describe gateway <gateway-name>
kubectl describe httproute <httproute-name>

생성된 Load Balancer와 Target Group 리소스는 다음 명령으로 확인할 수 있습니다.

kubectl get loadbalancer
kubectl get targetgroup

Gateway가 정상적으로 설정되면 연결된 ALB 주소가 Gateway 상태에 표시됩니다.

삭제

Gateway API로 생성한 ALB를 삭제하려면 HTTPRoute와 Gateway를 삭제합니다.

kubectl delete httproute <httproute-name>
kubectl delete gateway <gateway-name>

LoadBalancerTemplate을 별도로 생성한 경우 더 이상 사용하지 않을 때 삭제할 수 있습니다.

kubectl delete loadbalancertemplate <template-name>
사업자등록번호: 129-86-31394 통신판매업신고번호:제2009-경기성남-0510호
대표이사: 김유원 주소: 경기도 성남시 분당구 불정로 6 네이버 그린팩토리 17~26층, 13561 고객지원 대표전화: 1544-5876
© NAVER Cloud Corp. All Rights Reserved.