--- title: "Using Gateway API" slug: "gateway-api-use" updated: 2026-10-08T06:52:14Z published: 2026-10-08T06:52:14Z 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. # Using Gateway API Available in VPC Using Gateway API, you can create an Application Load Balancer (ALB) instance and route HTTP/HTTPS traffic using the Kubernetes `GatewayClass`, `Gateway`, and `HTTPRoute` resources. ALB integration using Gateway API is provided as an add-on for Kubernetes 1.36 or later clusters. You can use it by activating the Gateway API add-on in the Add-on menu of the NKS console. Caution - A Load Balancer created with Gateway API is managed as a Kubernetes resource. - If you modify the Load Balancer directly through the console or API, the Kubernetes resource and the Load Balancer status may become inconsistent. If you need to change the configuration, modify the Kubernetes resource. - Technical support is not provided for issues caused by direct changes through the console or API. - The default GatewayClass name used in Gateway API is `ncloud-alb`. - The backend Service to connect with Gateway API must be of type `NodePort`. ## Prerequisites and activation When you activate the Gateway API add-on, if the cluster does not have the Gateway API CRD, the add-on installs it automatically. If it is already installed, the existing CRD is left as is and the installation is skipped. You do not need to install the CRD yourself. The lb-controller uses the `gateway.networking.k8s.io/v1` API, and also references `ReferenceGrant`, which is used to connect a Service in another namespace as a backend, as `v1`. `ReferenceGrant` is provided as `v1` starting from Gateway API v1.6.0, so the add-on installs the Gateway API v1.6.0 (Standard channel) CRD. Activate the Gateway API add-on in the Add-on menu of the NKS console. When you activate the add-on, the following resource is automatically created along with the gateway-adapter controller. - GatewayClass `ncloud-alb` Once activation is complete, you can check whether the `ncloud-alb` GatewayClass is ready using the following command. ``` kubectl get gatewayclass ncloud-alb ``` Note - The add-on does not overwrite or upgrade an already installed Gateway API CRD. If the installed CRD version is earlier than v1.6.0, `ReferenceGrant` is not provided as `v1`, so the feature that uses a Service in another namespace as a backend will not work. If needed, upgrade the CRD to v1.6.0 or later yourself. ## Supported scope | Item | Supported? | Description | | --- | --- | --- | | GatewayClass | Supported | Default GatewayClass name is `ncloud-alb`. | | Gateway | Supported | HTTP and HTTPS listeners can be used. | | HTTPRoute | Partially supported | Supports Host, Path, Header exact match, and weighted backendRefs. | | ReferenceGrant | Supported | Required when using a Service in another namespace as a backend. | | Backend Service | Only NodePort is supported. | `ClusterIP`, `LoadBalancer`, and `ExternalName` type Services cannot be used as a backend. | | HTTPS | Supported | Uses the certificate number from NCP Certificate Manager. | | LoadBalancerTemplate | Supported | Used to configure ALB properties that are difficult to express with standard Gateway API fields. | The following items are not supported or are supported only in a limited way. For details, see [Gateway API unsupported fields](/docs/en/gateway-api-use#GatewayAPI%EB%AF%B8%EC%A7%80%EC%9B%90%ED%95%84%EB%93%9C). - TCPRoute, UDPRoute, TLSRoute, GRPCRoute - Secret-based TLS certificate reference - TLS passthrough - HTTPRoute filters such as RequestRedirect and URLRewrite - Query parameter match, method match - Regular expression-based Path or Header match - Gateway API session persistence ## Create a Gateway To create an ALB with Gateway API, create a Service, Gateway, and HTTPRoute. ### Create a Service The Service used as a backend in Gateway API must be of type `NodePort`. ``` apiVersion: v1 kind: Service metadata: name: web spec: type: NodePort selector: app: web ports: - port: 80 targetPort: 80 nodePort: 30080 ``` ### Create a Gateway and 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 settings `LoadBalancerTemplate` is a resource for configuring NCP ALB properties that are difficult to express with standard Gateway API fields. You can configure items such as private ALB, subnet, Load Balancer size, HTTPS certificate number, Target Group health check, and Sticky Session. Note `LoadBalancerTemplate` is optional. `GatewayClass` `ncloud-alb` does not have `parametersRef` configured, so if you create a Gateway without referencing `LoadBalancerTemplate`, the ALB is created as a public (`PUBLIC`) type in the cluster's default Load Balancer subnet, and the default values in the [Field defaults](/docs/en/gateway-api-use#%ED%95%84%EB%93%9C%EA%B8%B0%EB%B3%B8%EA%B0%92) table are applied to the remaining properties. `LoadBalancerTemplate` can be referenced from the following locations. | Reference location | Purpose | Remarks | | --- | --- | --- | | `GatewayClass.spec.parametersRef` | Cluster default ALB settings | Configured by the operator when common cluster-wide defaults are needed. | | `Gateway.spec.infrastructure.parametersRef` | Per-Gateway ALB settings | References `LoadBalancerTemplate` in the same namespace as the Gateway. | To apply individual settings to a Gateway, create `LoadBalancerTemplate` in the same namespace as the Gateway, and then reference it as `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 ``` ### Full LoadBalancerTemplate spec All `spec` fields in `LoadBalancerTemplate` are optional. The following is the full structure containing all available fields. For any field you do not specify, the default value listed in the [Field defaults](/docs/en/gateway-api-use#%ED%95%84%EB%93%9C%EA%B8%B0%EB%B3%B8%EA%B0%92) table is applied. In the comments, `기본값` is the value applied when the field is omitted, and `자동` means the value is not fixed but is determined, when omitted, as one of the cluster setting (`ncloud-config`), the NCP server default, or a value derived by the controller. For the specific meaning of each field, see the [Field defaults](/docs/en/gateway-api-use#%ED%95%84%EB%93%9C%EA%B8%B0%EB%B3%B8%EA%B0%92) table. ``` apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1 kind: LoadBalancerTemplate metadata: name: full-template spec: # --- Load Balancer infrastructure properties --- name: my-alb # Provider LB name · Default: Automatic (-) networkType: PUBLIC # PUBLIC | PRIVATE · Default: PUBLIC size: SMALL # SMALL | MEDIUM | LARGE | XLARGE · Default: Automatic description: "example template" # LB description · Default: "Managed by Gateway /" idleTimeoutSeconds: 60 # Idle connection hold time (seconds), 1–3,600 · Default: 60 accessLogEnabled: false # Whether to use ALB access log · Default: false skipAcgUpdate: true # Whether to skip ACG update when creating the LB · Default: false lbSubnetIds: # List of subnet IDs to place the LB in · Default: Automatic (cluster's default LB subnet) - 12345 publicIpInstanceNo: 123456 # Public IP instance number to connect to the PUBLIC LB · Default: Automatic (automatically assigned) retainPublicIpOnTermination: false # Whether to retain the public IP when deleting the LB · Default: false # --- Defaults applied to all listeners --- defaults: http2Enabled: false # Whether to use HTTP/2 · Default: false sslRedirectPort: 0 # If greater than 0, an HTTP→HTTPS redirect rule is automatically created · Default: 0 (disabled) aclId: 0 # ACL ID to connect, not used if 0 · Default: 0 targetGroup: protocol: HTTP # HTTP | HTTPS · Default: HTTP algorithmType: RR # RR | LC | SIPHS · Default: RR stickySession: false # Whether to use Sticky Session · Default: false proxyProtocol: false # true cannot be used in ALB Gateway · Default: false healthCheck: protocol: HTTP # HTTP | HTTPS · Default: HTTP method: GET # GET | HEAD · Default: GET path: / # Health check path · Default: / port: 0 # traffic-port is used if 0 · Default: 0 intervalSeconds: 30 # Health check interval (seconds) · Default: 30 healthyThresholdCount: 2 # Number of consecutive successes to be judged healthy · Default: 2 unhealthyThresholdCount: 2 # Number of consecutive failures to be judged unhealthy · Default: 2 # --- Individual settings applied only to a specific port listener (overrides defaults) --- listeners: - port: 443 # (Required) Gateway Listener port to apply the setting to, 1–65,535 protocol: HTTPS # (Required) HTTP | HTTPS http2Enabled: true # Default: defaults.http2Enabled value sslRedirectPort: 0 # Default: defaults.sslRedirectPort value aclId: 12345 # Default: defaults.aclId value tls: # Used when protocol is HTTPS certificateNos: # (Required for HTTPS) NCP Certificate Manager certificate number - 123456 minVersion: TLSV12 # TLSV10 | TLSV11 | TLSV12 | TLSV13 · Default: TLSV10 cipherSuiteList: # List of allowed cipher suites · Default: Automatic - TLS_RSA_WITH_AES_128_GCM_SHA256 targetGroup: # TG settings for this listener · Default: defaults.targetGroup value protocol: HTTP algorithmType: RR stickySession: false healthCheck: protocol: HTTP method: GET path: / rules: # Routing rules (conditions/actions) for this listener · If specified, replaces the rules generated by HTTPRoute - priority: 1 # (Required) Evaluation priority, 1–10,000 (lower values are evaluated first) conditions: # Matching conditions · AND when combining multiple types · 1 per type (duplicate types not allowed) - type: HostHeader # HostHeader | PathPattern | HttpHeader · Specify only the types you need hostHeader: values: ["api.example.com"] # OR if multiple values - type: PathPattern pathPattern: values: ["/old", "/old/*"] - type: HttpHeader httpHeader: headerName: X-Env values: ["canary"] action: # (Required) type: Redirect # ForwardTargetGroup | Redirect redirect: # Used when type is Redirect protocol: HTTPS # HTTP | HTTPS port: "443" # Port must be specified when redirecting statusCode: "301" # 301 | 302 # If host/path/query is not specified, the original request value is retained # forwardTargetGroup: # Used when type is ForwardTargetGroup # targets: # - {targetGroupName: <컨트롤러 자동 생성 TG 이름>, weight: 1} # enableStickySession: false ``` `spec.defaults` and `spec.listeners[]` use the same common fields (`http2Enabled`, `sslRedirectPort`, `aclId`, `targetGroup`), and `tls` and `rules` can only be specified in `spec.listeners[]`. Write `spec.listeners[]` only when you want to apply a different value to a specific port. #### Field defaults For fields you do not specify, the default values in the following table are applied. `자동` means the value is not fixed but is determined, when omitted, as one of the cluster setting (`ncloud-config`), the NCP server default, or a value derived by the controller. The source for each field is indicated in the default value and description of each row. | Field | Type | Default | Description | | --- | --- | --- | --- | | `name` | string | Automatic | - Provider Load Balancer name. - If not specified, uses the name of the created LoadBalancer resource (`<Gateway namespace>-<Gateway 이름>`). | | `networkType` | string | `PUBLIC` | - Load Balancer network type. - Enter `PUBLIC` or `PRIVATE`. | | `size` | string | Automatic (NCP server default) | - Load processing capacity of the Load Balancer. - Enter one of `SMALL`, `MEDIUM`, `LARGE`, or `XLARGE`. | | `description` | string | `Managed by Gateway <namespace>/<name>` | Load Balancer description. | | `idleTimeoutSeconds` | int | `60` | - Idle connection hold time (seconds). - Set within the range of 1–3,600. | | `accessLogEnabled` | bool | `false` | Whether to use ALB access log. | | `skipAcgUpdate` | bool | `false` | - Whether to skip node ACG update when creating the Load Balancer. - With the default value `false`, the controller registers an LB subnet inbound rule in the node ACG so that ALB traffic can reach the nodes. | | `lbSubnetIds` | []int | Automatic | - List of subnet IDs to place the Load Balancer in. - If not specified, uses the subnet of `ncloud-config` (`lbPublicSubnetNo` for PUBLIC, `lbSubnetNo` for PRIVATE). | | `publicIpInstanceNo` | int | Automatic | - Public IP instance number to connect to the `PUBLIC` Load Balancer. - Automatically assigned if not specified. | | `retainPublicIpOnTermination` | bool | `false` | Whether to retain the public IP when deleting the Load Balancer. | | `defaults.http2Enabled` | bool | `false` | - Whether to use HTTP/2. - Applied only to HTTPS listeners and ignored for HTTP listeners. | | `defaults.sslRedirectPort` | int | `0` | If greater than 0, an HTTP→HTTPS redirect rule is automatically created. | | `defaults.aclId` | int | `0` | - ACL ID to connect to the listener. - Not used if `0`. | | `defaults.targetGroup.protocol` | string | `HTTP` | - Protocol to forward to the backend Service. - Enter `HTTP` or `HTTPS`. | | `defaults.targetGroup.algorithmType` | string | `RR` | - Load balancing algorithm. - Enter one of `RR`, `LC`, or `SIPHS`. | | `defaults.targetGroup.stickySession` | bool | `false` | Whether to use Sticky Session. | | `defaults.targetGroup.proxyProtocol` | bool | `false` | - Whether to use Proxy Protocol. - In ALB Gateway, `true` cannot be used. | | `defaults.targetGroup.healthCheck.protocol` | string | `HTTP` | - Health check protocol. - Enter `HTTP` or `HTTPS`. | | `defaults.targetGroup.healthCheck.method` | string | `GET` | - HTTP/HTTPS health check method. - Enter `GET` or `HEAD`. | | `defaults.targetGroup.healthCheck.path` | string | `/` | HTTP/HTTPS health check path. | | `defaults.targetGroup.healthCheck.port` | int | `0` | - Health check port. - If `0`, traffic-port is used. | | `defaults.targetGroup.healthCheck.intervalSeconds` | int | `30` | Health check interval (seconds). | | `defaults.targetGroup.healthCheck.healthyThresholdCount` | int | `2` | Number of consecutive successes to be judged healthy. | | `defaults.targetGroup.healthCheck.unhealthyThresholdCount` | int | `2` | Number of consecutive failures to be judged unhealthy. | | `listeners[].port` | int | (Required) | - Gateway Listener port to apply the setting to. - Set within the range of 1–65,535. | | `listeners[].protocol` | string | (Required) | - Listener protocol. - Enter `HTTP` or `HTTPS`. | | `listeners[].tls.certificateNos` | []int | (Required for HTTPS) | NCP Certificate Manager certificate number. | | `listeners[].tls.minVersion` | string | `TLSV10` | - Minimum TLS version. - Enter one of `TLSV10`, `TLSV11`, `TLSV12`, or `TLSV13`. - If not specified, `TLSV10` is applied. | | `listeners[].tls.cipherSuiteList` | []string | Automatic | - List of allowed cipher suites. - If not specified, all cipher suites supported by the listener are applied. | | `listeners[].http2Enabled` | bool | `defaults` value | - Whether to use HTTP/2 for the listener. - Applied only to HTTPS listeners and ignored for HTTP listeners. | | `listeners[].sslRedirectPort` | int | `defaults` value | HTTP→HTTPS redirect port for the listener. | | `listeners[].aclId` | int | `defaults` value | ACL ID to connect to the listener. | | `listeners[].targetGroup` | object | `defaults.targetGroup` value | - Target Group settings for the listener. - The field structure is the same as `defaults.targetGroup`. | | `listeners[].rules` | []object | - | - List of routing rules (conditions/actions) for the listener. - Used to directly specify conditions/actions that cannot be expressed with HTTPRoute (e.g., Redirect). - If specified, replaces the rules generated from HTTPRoute for the listener. - See [Directly specifying listener routing rules](/docs/en/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 | (Required) | - Rule evaluation priority. - Set within the range of 1–10,000. Lower values are evaluated first. | | `listeners[].rules[].conditions` | []object | - | - List of matching conditions. - If multiple types are specified together, they are evaluated as AND, and only 1 of each type (`HostHeader`/`PathPattern`/`HttpHeader`) can be specified per rule (duplicate types are not allowed). - If a condition has multiple `values` values, they are evaluated as OR. - If the list is empty, it matches all requests. | | `listeners[].rules[].action` | object | (Required) | - Action to perform when the condition matches. - Specify `ForwardTargetGroup` (forward to Target Group) or `Redirect` (HTTP redirect). | Note - If you do not specify a field in `listeners[]`, the value set in `defaults` is used. If it is not set in `defaults` either, the default value in the table above is applied. - `listeners[]` is applied only when `port` matches a Listener defined in the Gateway. ### Key LoadBalancerTemplate configuration examples Write the fields you need in `LoadBalancerTemplate` according to your configuration purpose. #### Basic Load Balancer property settings You can configure the Load Balancer's network type, size, idle connection hold time, and whether to use access log. ``` apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1 kind: LoadBalancerTemplate metadata: name: alb-basic spec: networkType: PUBLIC size: SMALL idleTimeoutSeconds: 60 accessLogEnabled: false ``` - `networkType`: This is the Load Balancer network type. Enter `PUBLIC` or `PRIVATE`. - `size`: This is the load processing capacity of the Load Balancer. Enter one of `SMALL`, `MEDIUM`, `LARGE`, or `XLARGE`. - `idleTimeoutSeconds`: This is the idle connection hold time. Set within the range of 1–3,600 seconds. - `accessLogEnabled`: Specifies whether to use the ALB access log. Enter `true` or `false`. #### Load Balancer subnet settings If you need to create the ALB in a subnet other than the default Load Balancer subnet, configure `lbSubnetIds`. ``` apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1 kind: LoadBalancerTemplate metadata: name: alb-subnet spec: networkType: PRIVATE lbSubnetIds: - 12345 ``` - `lbSubnetIds`: This is the subnet ID where the Load Balancer will be created. - You must enter a Load Balancer subnet that matches `networkType`. - If you do not configure `lbSubnetIds`, the default Load Balancer subnet set for the cluster is used. #### Public IP settings Use the following fields to connect a specific public IP to a public ALB, or to retain the public IP when the ALB is deleted. ``` apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1 kind: LoadBalancerTemplate metadata: name: alb-public-ip spec: networkType: PUBLIC publicIpInstanceNo: 123456 retainPublicIpOnTermination: true ``` - `publicIpInstanceNo`: This is the public IP instance number to connect to the ALB. Used in `networkType: PUBLIC`. - `retainPublicIpOnTermination`: Specifies whether to retain the public IP when the ALB is deleted. #### Target Group default settings You can configure the Target Group defaults to use when forwarding traffic to a Service connected to the Gateway. ``` 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`: This is the protocol to forward to the backend Service. Enter `HTTP` or `HTTPS`. - `algorithmType`: This is the load balancing algorithm. Enter one of `RR`, `LC`, or `SIPHS`. - `stickySession`: Specifies whether to use Sticky Session. This value is used instead of the session persistence field in Gateway API. - `healthCheck.protocol`: This is the health check protocol. Enter `HTTP` or `HTTPS`. - `healthCheck.method`: This is the HTTP/HTTPS health check method. Enter `GET` or `HEAD`. - `healthCheck.path`: This is the HTTP/HTTPS health check path. - `healthCheck.port`: This is the health check port. If `0`, traffic-port is used. #### Per-listener HTTPS certificate settings When using an HTTPS listener, configure the NCP Certificate Manager certificate number for each 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`: This is the Gateway Listener port to apply the setting to. - `listeners[].protocol`: This is the listener protocol. Enter `HTTPS` for an HTTPS listener. - `listeners[].tls.certificateNos`: This is the NCP Certificate Manager certificate number. Kubernetes Secret-based certificate references are not used. - `listeners[].tls.minVersion`: This is the minimum TLS version. Enter one of `TLSV10`, `TLSV11`, `TLSV12`, or `TLSV13`. #### Per-listener ACL and HTTP/2 settings You can connect an ACL to a specific listener or activate 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`: This is the ACL ID to connect to the listener. Not used if `0`. - `listeners[].http2Enabled`: Specifies whether to use HTTP/2 for the listener. Since HTTP/2 is negotiated over TLS, it is applied only to HTTPS listeners, and is ignored if set on an HTTP listener. Note `spec.defaults` and `spec.listeners[]` have their roles distinguished as follows. - `spec.defaults`: This is the default applied to listeners defined by the Gateway that do not have per-port settings in `spec.listeners[]`. In other words, a listener for which individual settings are not separately specified uses this default. - `spec.listeners[]`: This is the individual setting applied only to the listener of a specific port. It is matched with the Gateway Listener by `port`, and for that listener, this setting takes priority over `spec.defaults`. ### Specify listener routing rules directly (conditions/actions) By default, the routing rules (conditions/actions) of an ALB listener are automatically generated from HTTPRoute. If you need conditions/actions that cannot be expressed with HTTPRoute (typically Redirect), you can write the rule directly in `listeners[].rules[]` of `LoadBalancerTemplate`. ``` apiVersion: loadbalancer.vnks.ncloud.com/v1alpha1 kind: LoadBalancerTemplate metadata: name: alb-redirect spec: listeners: - port: 80 protocol: HTTP rules: - priority: 1 # Lower values are evaluated first (1–10000) conditions: # Only 1 of each condition type can be specified per rule - type: PathPattern pathPattern: values: ["/old", "/old/*"] action: type: Redirect # ForwardTargetGroup | Redirect redirect: protocol: HTTPS # HTTP | HTTPS port: "443" # Port must be specified when redirecting statusCode: "301" # 301 | 302 # If host/path/query is not specified, the original request value is retained ``` **Condition type** | Type | Field | Description | | --- | --- | --- | | `HostHeader` | `hostHeader.values` | List of Host header matching values. | | `PathPattern` | `pathPattern.values` | List of URL path pattern values. | | `HttpHeader` | `httpHeader.headerName`, `httpHeader.values` | List of arbitrary HTTP header names and values. | **Action type** | Type | Description | | --- | --- | | `ForwardTargetGroup` | - Forward to Target Group. - Weight distribution using `forwardTargetGroup.targets[].targetGroupName`and `weight`. - Session stickiness using `enableStickySession`. | | `Redirect` | - HTTP redirect. - See the following table for detailed fields. | The detailed fields of the `Redirect` action are as follows: | Field | Type | Description | | --- | --- | --- | | `redirect.protocol` | string | - Redirect protocol (`HTTP` or `HTTPS`). - Default: `#{protocol}` (keeps the original protocol). | | `redirect.port` | string | - Redirect port. - Required when using `Redirect` action (creation is rejected if not specified). | | `redirect.statusCode` | string | - Redirect status code (`301` or `302`). - Default: `301` | | `redirect.host` | string | - Redirect host. - Default: `#{host}` (keeps the original host). | | `redirect.path` | string | - Redirect path. - Default: `/#{path}` (keeps the original path). | | `redirect.query` | string | - Redirect query string. - Default: `#{query}` (keeps the original query). | Caution - Specifying `listeners[].rules[]` replaces all rules generated from HTTPRoute for that listener (this is not a partial merge). Therefore, HTTPRoute routing and directly written rules cannot be mixed on the same listener. - In a single rule, you can specify 1 each of `HostHeader`, `PathPattern`, and `HttpHeader` together, and they are evaluated as AND. However, you cannot include 2 or more of the same type. - The `targetGroupName` of the `ForwardTargetGroup` action must reference the Target Group name automatically generated by the controller, so this method is mainly used for the `Redirect` action, which does not require a Target Group. ## Create a private ALB If you need a private ALB, configure `networkType: PRIVATE` in `LoadBalancerTemplate`, and then reference it from the 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 ``` ## Pause Load Balancer management `lb.ncloud.naver.com/pause: "true"` is a pause option available for KVM clusters running Kubernetes 1.36 or later. When this value is set, the controller's spec/provider reconciliation is paused. | Applies to | Behavior | | --- | --- | | Gateway | - While paused, changes to Gateway/HTTPRoute are not reflected in the Load Balancer settings. - Even if you delete the Gateway while paused, already created Ncloud LB/TG are retained and not deleted. | Caution The pause option is intended to preserve existing Ncloud LB/TG resources. While paused, missing Load Balancer resources are not newly created. To resume applying changes, remove the pause annotation from the input resource. ## Use an HTTPS listener When using an HTTPS listener in Gateway API, enter the NCP Certificate Manager certificate number in `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 ``` Note Secret-based TLS certificate references in Gateway API are not used. Use the NCP Certificate Manager certificate number. ## Connect a Service in another namespace For an HTTPRoute to reference a Service in another namespace as a backend, you must create `ReferenceGrant` in the namespace where the Service is located. ``` 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 ``` Without `ReferenceGrant`, a Service in another namespace cannot be used as a backend. ## Gateway API unsupported fields The Gateway API standard includes various fields and route types, but NKS Gateway API ALB integration supports only the following scope. ### GatewayClass and Gateway | Field | Supported? | Description | Alternative | | --- | --- | --- | --- | | `GatewayClass.spec.parametersRef` | Supported | Supports referencing `LoadBalancerTemplate`. | Configured by the operator to reference `LoadBalancerTemplate` when common cluster-wide defaults are needed. | | `Gateway.spec.infrastructure.parametersRef` | Supported | Supports referencing `LoadBalancerTemplate` in the same namespace as the Gateway. | Use this field when configuring ALB settings per Gateway. | | `Gateway.spec.addresses` | Not supported | Does not directly request or reserve an IP address from the Gateway. | Use `LoadBalancerTemplate.spec.publicIpInstanceNo` for a fixed public IP. | | `Gateway.spec.listeners[].hostname` | Supported | - The hostname specified on the listener is also used for domain routing. - Applied together with `HTTPRoute.spec.hostnames`. | - | | `Gateway.spec.listeners[].protocol: HTTP` | Supported | Creates an HTTP listener. | - | | `Gateway.spec.listeners[].protocol: HTTPS` | Partially supported | Creates an HTTPS listener but does not use Secret-based certificates. | Specify the certificate number in `LoadBalancerTemplate.spec.listeners[].tls.certificateNos`. | | `Gateway.spec.listeners[].protocol: TLS` | Not supported | Does not create a TLS passthrough listener. | Use an HTTPS listener. | | `Gateway.spec.listeners[].protocol: TCP` | Not supported | Does not create a TCP listener. | Use Service `type: LoadBalancer`. | | `Gateway.spec.listeners[].protocol: UDP` | Not supported | Does not create a UDP listener. | Use Service `type: LoadBalancer`. | | `Gateway.spec.listeners[].tls.certificateRefs` | Not supported | Does not use a Kubernetes Secret as a certificate. | Use the NCP Certificate Manager certificate number. | | `Gateway.spec.listeners[].tls.mode: Passthrough` | Not supported | ALB terminates connections at L7. | Use an HTTPS listener. | | `Gateway.spec.listeners[].allowedRoutes.namespaces.from` | Supported | `Same`, `All`, and `Selector` can be used. | - | | `Gateway.spec.listeners[].allowedRoutes.kinds` | Partially supported | Only HTTPRoute is supported. | Use HTTPRoute. | ### HTTPRoute | Field | Supported? | Description | Alternative | | --- | --- | --- | --- | | `HTTPRoute.spec.parentRefs` | Supported | Used to connect a Gateway and listener. | - | | `HTTPRoute.spec.hostnames` | Supported | Used as an ALB Host header condition. | - | | `HTTPRoute.spec.rules[].matches[].path.type: PathPrefix` | Supported | Used as a Path condition. | - | | `HTTPRoute.spec.rules[].matches[].path.type: Exact` | Supported | Used as a Path condition. | - | | `HTTPRoute.spec.rules[].matches[].path.type: RegularExpression` | Not supported | Regular expression Path conditions are not supported. | Use `PathPrefix` or `Exact`. | | `HTTPRoute.spec.rules[].matches[].headers` exact match | Supported | Used as a Header exact match condition. | - | | `HTTPRoute.spec.rules[].matches[].headers` regex match | Not supported | Regular expression Header conditions are not supported. | Use exact match. | | `HTTPRoute.spec.rules[].matches[].headers` multiple headers (2 or more in a single match) | Not supported | A single rule can have only 1 Header condition, so multiple headers cannot be matched with AND. | Use a single header condition, or handle it at the application level. | | `HTTPRoute.spec.rules[].matches[].queryParams` | Not supported | Query parameter conditions are not supported. | Handled at the application level. | | `HTTPRoute.spec.rules[].matches[].method` | Not supported | HTTP method conditions are not supported. | Handled at the application level. | | `HTTPRoute.spec.rules[].filters[].type: RequestRedirect` | Not supported | The Redirect filter of HTTPRoute is not supported. | Directly specify the `Redirect` action in `listeners[].rules[]` of `LoadBalancerTemplate` ([Directly specifying listener routing rules](/docs/en/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` | Not supported | URL rewrite filter is not supported. | Handled at the application level. | | `HTTPRoute.spec.rules[].filters[].type: RequestHeaderModifier` | Not supported | Request header modifier is not supported. | Handled at the application level. | | `HTTPRoute.spec.rules[].filters[].type: ResponseHeaderModifier` | Not supported | Response header modifier is not supported. | Handled at the application level. | | `HTTPRoute.spec.rules[].filters[].type: RequestMirror` | Not supported | Request mirror is not supported. | Use a separate mirroring configuration. | | `HTTPRoute.spec.rules[].backendRefs[].kind: Service` | Supported | A Service can be used as a backend. | Use Service `type: NodePort`. | | backendRef kinds other than Service | Not supported | backendRef kinds other than Service are not supported. | Use a Service backend. | | backendRef in another namespace | Partially supported | Can be used only when `ReferenceGrant` exists. | Create `ReferenceGrant` in the backend namespace. | | `HTTPRoute.spec.rules[].backendRefs[].weight` | Supported | Used as backend weight. | - | | backend Service `type: ClusterIP` | Not supported | Cannot be used as a Target Group backend because it has no NodePort. | Use Service `type: NodePort`. | | backend Service `type: LoadBalancer` | Not supported | Not used as a Gateway backend. | Use Service `type: NodePort`. | | backend Service `type: ExternalName` | Not supported | Not used as a Gateway backend. | Use Service `type: NodePort`. | | Gateway API `sessionPersistence` | Not supported | The Gateway API session persistence field is not used. | Use Target Group `stickySession` of `LoadBalancerTemplate`. | | Rule- or backend-level timeout | Not supported | The Gateway API timeout field is not used. | For Load Balancer idle timeout, use `LoadBalancerTemplate.spec.idleTimeoutSeconds`. | ## Check status You can check the status of the Gateway and HTTPRoute with the following commands. ``` kubectl get gateway kubectl get httproute ``` To check the detailed status, run the following commands. ``` kubectl describe gateway kubectl describe httproute ``` You can check the created Load Balancer and Target Group resources with the following commands. ``` kubectl get loadbalancer kubectl get targetgroup ``` When the Gateway is configured successfully, the address of the connected ALB is displayed in the Gateway status. ## Delete To delete an ALB created with Gateway API, delete the HTTPRoute and Gateway. ``` kubectl delete httproute kubectl delete gateway ``` If you create `LoadBalancerTemplate` separately, you can delete it when it is no longer needed. ``` kubectl delete loadbalancertemplate ```