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 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

サポート範囲

次の項目はサポートしない、または制限的にサポートします。詳細は、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は次の位置でご参照ください。

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サーバデフォルト値・コントローラ派生値のうち、1つが決定されることを意味します。フィールド別の具体的な意味は、フィールドデフォルト値表をご参照ください。

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サーバデフォルト値・コントローラ派生値の中から1つが決定されることを意味します。また、フィールド別の出典は各行のデフォルト値・説明に表記しました。

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に設定すると無視されます。

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)のタイプ

アクション(action)のタイプ

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が一時停止されます。

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

他の 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

HTTPRoute

ステータス確認

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>