Using Gateway API

Prev Next

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.

  • 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 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 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 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 (<Gateway namespace>-<Gateway name>)
  networkType: PUBLIC                 # PUBLIC | PRIVATE · Default: PUBLIC
  size: SMALL                         # SMALL | MEDIUM | LARGE | XLARGE · Default: Automatic
  description: "example template"      # LB description · Default: "Managed by Gateway <namespace>/<name>"
  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.
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[].targetGroupNameand 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).
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 <gateway-name>
kubectl describe httproute <httproute-name>

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 <httproute-name>
kubectl delete gateway <gateway-name>

If you create LoadBalancerTemplate separately, you can delete it when it is no longer needed.

kubectl delete loadbalancertemplate <template-name>