--- title: "Gateway API を使用する" slug: "gateway-api-use" updated: 2026-10-20T09:00:56Z published: 2026-10-20T09:00:56Z canonical: "guide.ncloud-docs.com/gateway-api-use" --- > ## 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 を使用する 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 未サポートフィールド](/docs/ja/gateway-api-use#GatewayAPI%EB%AF%B8%EC%A7%80%EC%9B%90%ED%95%84%EB%93%9C)をご参照ください。 - 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に作成されて、他のプロパティには[フィールドデフォルト値](/docs/ja/gateway-api-use#%ED%95%84%EB%93%9C%EA%B8%B0%EB%B3%B8%EA%B0%92)表のデフォルト値が適用されます。 `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` フィールドはすべて選択項目です。次は、使用できる全フィールドをまとめた全体構造であり、指定していないフィールドには[フィールドデフォルト値](/docs/ja/gateway-api-use#%ED%95%84%EB%93%9C%EA%B8%B0%EB%B3%B8%EA%B0%92)表にまとめたデフォルト値が適用されます。 コメントアウトの `기본값`は当該フィールドを省略した時に適用される値であり、`자동`は固定値ではなく省略時のクラスタ設定(`ncloud-config`)・NCPサーバデフォルト値・コントローラ派生値のうち、1つが決定されることを意味します。フィールド別の具体的な意味は、[フィールドデフォルト値](/docs/ja/gateway-api-use#%ED%95%84%EB%93%9C%EA%B8%B0%EB%B3%B8%EA%B0%92)表をご参照ください。 ``` 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サーバデフォルト値・コントローラ派生値の中から1つが決定されることを意味します。また、フィールド別の出典は各行のデフォルト値・説明に表記しました。 | フィールド | タイプ | デフォルト値 | 説明 | | --- | --- | --- | --- | | `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`のうち1つを入力 | | `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`のうち1つを入力 | | `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`のうち1つを入力 - 未指定の場合、`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ルーティングルールを直接指定](/docs/ja/gateway-api-use#Listener%EB%9D%BC%EC%9A%B0%ED%8C%85%EB%A3%B0%EC%A7%81%EC%A0%91%EC%A7%80%EC%A0%95)を参照 | | `listeners[].rules[].priority` | int | (必須) | - ルール評価の優先順位 - 1~10000範囲で設定し、低いほど先に評価 | | `listeners[].rules[].conditions` | []object | - | - マッチング条件リスト - 複数のタイプを一緒に指定すると ANDで評価され、各タイプ(`HostHeader`/`PathPattern`/`HttpHeader`)はルールごとに1つのみ(同じタイプは重複不可)指定可能 - 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`のうち、1つを入力します。 - `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`のうち、1つを入力します。 - `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`のうち、1つを入力します。 #### 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で混用できません。 - 1つのルールで `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(1つの matchに2つ以上) | 未サポート | 1つの 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ルーティングルールを直接指定](/docs/ja/gateway-api-use#Listener%EB%9D%BC%EC%9A%B0%ED%8C%85%EB%A3%B0%EC%A7%81%EC%A0%91%EC%A7%80%EC%A0%95)) | | `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 kubectl describe httproute ``` 作成された Load Balancerと Target Groupリソースは、以下のコマンドで確認できます。 ``` kubectl get loadbalancer kubectl get targetgroup ``` Gatewayが正常に設定されたら接続された ALBアドレスが Gatewayステータスに表示されます。 ## 削除 Gateway APIで作成した ALBを削除するには、HTTPRouteと Gatewayを削除します。 ``` kubectl delete httproute kubectl delete gateway ``` `LoadBalancerTemplate`を別途作成した場合、これ以上使用しない時に削除できます。 ``` kubectl delete loadbalancertemplate ```