--- title: "Gateway API 사용" slug: "k8s-k8suse-gateway-api" updated: 2026-08-20T09:03:27Z published: 2026-08-20T09:03:27Z canonical: "guide-gov.ncloud-docs.com/k8s-k8suse-gateway-api" --- > ## 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. # Gateway API 사용

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을 활성화하면 사용할 수 있습니다. :::(Warning) (주의) * 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가 준비되었는지 확인할 수 있습니다. ```bash kubectl get gatewayclass ncloud-alb ``` :::(Info) (참고) 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 미지원 필드](#GatewayAPI미지원필드)를 참고해 주십시오. - 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` 타입이어야 합니다. ```yaml apiVersion: v1 kind: Service metadata: name: web spec: type: NodePort selector: app: web ports: - port: 80 targetPort: 80 nodePort: 30080 ``` ### Gateway와 HTTPRoute 생성 ```yaml 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 등을 설정할 수 있습니다. :::(Info) (참고) `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`로 참조합니다. ```yaml 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 서버 기본값·컨트롤러 파생값 중 하나로 결정됨을 의미합니다. 필드별 구체적인 의미는 [필드 기본값](#필드기본값) 표를 참고해 주십시오. ```yaml apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1 kind: LoadBalancerTemplate metadata: name: full-template spec: # --- Load Balancer 인프라 속성 --- name: my-alb # provider LB 이름 · 기본값: 자동(-) networkType: PUBLIC # PUBLIC | PRIVATE · 기본값: PUBLIC size: SMALL # SMALL | MEDIUM | LARGE | XLARGE · 기본값: 자동 description: "example template" # LB 설명 · 기본값: "Managed by Gateway /" 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 리소스 이름(`-`) 사용
| | `networkType` | string | `PUBLIC` |
  • Load Balancer 네트워크 타입
  • `PUBLIC` 또는 `PRIVATE` 입력
| | `size` | string | 자동(NCP 서버 기본값) |
  • Load Balancer 부하 처리 성능
  • `SMALL`, `MEDIUM`, `LARGE`, `XLARGE` 중 하나 입력
| | `description` | string | `Managed by Gateway /` | 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 라우팅 룰 직접 지정](#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 리다이렉트) 지정
| :::(Info) (참고) * `listeners[]`의 필드를 지정하지 않으면 `defaults`에 설정한 값이, `defaults`에도 없으면 위 표의 기본값이 적용됩니다. * `listeners[]`는 `port`가 Gateway에 정의된 Listener와 일치할 때만 적용됩니다. ::: ### LoadBalancerTemplate 주요 설정 예제 `LoadBalancerTemplate`에 설정 목적에 따라 필요한 필드를 작성합니다. #### Load Balancer 기본 속성 설정 Load Balancer의 네트워크 타입, 크기, 유휴 연결 유지 시간, 접근 로그 사용 여부를 설정할 수 있습니다. ```yaml 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`를 설정합니다. ```yaml 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를 보존하려면 다음 필드를 사용합니다. ```yaml 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 기본값을 설정할 수 있습니다. ```yaml 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별로 설정합니다. ```yaml 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를 활성화할 수 있습니다. ```yaml 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에 설정하면 무시됩니다. :::(Info) (참고) `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[]`에 룰을 직접 작성할 수 있습니다. ```yaml 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}`(원래 쿼리 유지)
| :::(Warning) (주의) * `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에서 참조합니다. ```yaml 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는 삭제하지 않고 유지
| :::(Warning) (주의) pause는 이미 생성된 NCloud LB/TG를 보존하기 위한 옵션입니다. pause 상태에서는 누락된 Load Balancer 리소스를 새로 생성하지 않습니다. 변경 반영을 재개하려면 입력 리소스에서 pause 어노테이션을 제거해 주십시오. ::: ## HTTPS Listener 사용 Gateway API에서 HTTPS Listener를 사용할 때는 NCP Certificate Manager의 인증서 번호를 `LoadBalancerTemplate`에 입력합니다. ```yaml 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 ``` :::(Info) (참고) Gateway API의 Secret 기반 TLS 인증서 참조는 사용하지 않습니다. NCP Certificate Manager 인증서 번호를 사용해 주십시오. ::: ## 다른 namespace의 Service 연결 HTTPRoute가 다른 namespace의 Service를 backend로 참조하려면 Service가 있는 namespace에 `ReferenceGrant`를 생성해야 합니다. ```yaml 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 라우팅 룰 직접 지정](#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 상태는 다음 명령으로 확인할 수 있습니다. ```bash kubectl get gateway kubectl get httproute ``` 상세 상태를 확인하려면 다음 명령을 실행해 주십시오. ```bash kubectl describe gateway kubectl describe httproute ``` 생성된 Load Balancer와 Target Group 리소스는 다음 명령으로 확인할 수 있습니다. ```bash kubectl get loadbalancer kubectl get targetgroup ``` Gateway가 정상적으로 설정되면 연결된 ALB 주소가 Gateway 상태에 표시됩니다. ## 삭제 Gateway API로 생성한 ALB를 삭제하려면 HTTPRoute와 Gateway를 삭제합니다. ```bash kubectl delete httproute kubectl delete gateway ``` `LoadBalancerTemplate`을 별도로 생성한 경우 더 이상 사용하지 않을 때 삭제할 수 있습니다. ```bash kubectl delete loadbalancertemplate ```