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.

Preparation 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

Supported Scope

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.

LoadBalancerTemplate can be referenced from the following locations.

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

LoadBalancerTemplate's spec fields are all 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 keep-alive time (seconds), 1–3600 · Default: 60
accessLogEnabled: false # Whether to use ALB access log · Default: false
skipAcgUpdate: true # Whether to skip ACG update when creating 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, 0 if not used · 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 # If 0, traffic-port is used · 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–65535
protocol: HTTPS # (Required) HTTP | HTTPS
http2Enabled: true # Default: Value of defaults.http2Enabled
sslRedirectPort: 0 # Default: Value of defaults.sslRedirectPort
aclId: 12345 # Default: Value of defaults.aclId
tls: # protocol: Used when 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: Value of defaults.targetGroup
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–10000 (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: # type: Used when 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: # type: Used when 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 only.

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.

Key LoadBalancerTemplate configuration examples

Write the fields you need in LoadBalancerTemplate according to your configuration purpose.

Configure basic Load Balancer properties

You can configure the Load Balancer's network type, size, idle connection keep-alive 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 handling capacity of the Load Balancer. Enter one of SMALL, MEDIUM, LARGE, XLARGE.
• idleTimeoutSeconds: This is the idle connection keep-alive time. Set within the range of 1–3600 seconds.
• accessLogEnabled: This is 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: This is 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, SIPHS.
• stickySession: This is 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, 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: This is 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.

Directly specifying listener routing rules (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 (conditions) type

Action (action) type

The detailed fields of the Redirect action are as follows.

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.

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

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

HTTPRoute

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>