Docs

Volcengine Kubernetes Engine

Customize ALB Ingress forwarding rules

Configuring header-based traffic forwarding

An ALB Ingress for a Standard edition ALB instance supports traffic distribution to different back-end services based on headers in key-value pairs.

warning

It is highly recommended that you first read Considerations for using ALB Ingresses carefully before getting started.

Prerequisites

The cluster has been connected. For details, see Connecting to clusters.

An ALB instance has been created. For details, see Creating ALB Ingresses via kubectl.

Applications and services have been deployed. For deployment examples, see Using ALB Ingresses for service deployment.

The alb-ingress-controller add-on has been installed and upgraded to version v0.32.0 or later. For details, see Upgrading add-ons.

Limits

This configuration is supported only when an ALB Ingress associates with a Standard edition ALB instance. For details, see Overview of ALB instance editions.

Procedure

Configure through the console

In the left navigation bar, click Cluster.

On the cluster list page, click the target cluster for which you need to configure an Ingress.

In the left navigation bar of the cluster management page, click Services and Ingresses > Ingress. On the page that appears, click Create Ingress.

Select Application Load Balancer (ALB) for Ingress type.

In the Forwarding configuration section, select the Enable check box to configure custom forwarding rules.

Parameter	Description
Forwarding conditions	Configure forwarding conditions, including the domain name, path, and HTTP header. Forwarding conditions can be configured individually or in combination. When multiple forwarding conditions are configured, the logical relationship between these forwarding conditions is AND. For example, if you configure both a domain name and a path in a forwarding rule, then only requests that match the specified domain name and path will match this forwarding rule. Multiple values can be configured within the same forwarding condition, and these values have a logical relationship of OR. For example, if you configure multiple values for a domain name condition, requests that match any of the values are a match for the rule.
Forwarding actions	Configure the forwarding action. For this example, select Forward to, which forwards requests to the target service and port.

Click Confirm.

Configure through kubectl

An ALB Ingress allows you to configure request header-based forwarding policies by using annotations. The following is an example YAML with comments for annotations.

The {{service-name}} field in the annotation must match the name of the back-end service configured in spec.rules. For example, in this case, the correct annotation is ingress.vke.volcengine.com/loadbalancer-conditions.service-demo.

The Header configured in the annotation and the host in spec.rules will be combined. For example, in this case, after the forwarding rules are combined, requests with host set to example.com and Header set to header-key-1:header-value-1 will all be forwarded to service-demo.

The following table describes fields in the ingress.vke.volcengine.com/loadbalancer-conditions.{{service-name}} annotation.

Parameter	Type	Description	Default value
type	String	The forwarding policy type. In this example, the type is Header, which indicates header-based forwarding.	None
headerConfig	Array of headerConfig	The header configuration.	None

headerConfig

Parameter	Type	Description	Default value
key	String	The HTTP Header key. Keys within the same forwarding rule cannot be identical. Only letters, digits, hyphens (-), and underscores (_) are supported. It cannot be Cookie or Host. It can contain up to 40 characters. tip Multiple headers within a forwarding rule have a logical OR relationship.	None
values	Array of String	The value of the HTTP header. Printable ASCII characters are allowed. It cannot start or end with a space. It can contain up to 128 characters. tip A header can have multiple values, which have a logical OR relationship.	None

Validating results

Viewing configuration

Click Instance in the left navigation bar. In the instance list, find the target ALB instance and click Listener in the Actions column.

On the listener details page, find the target listener. In the Actions column, click Edit forwarding rules to view the existing forwarding rules of the listener. Confirm that the forwarding rules are the same as the configured ones.

Sending access requests for verification

tip

Before verification, make sure that you have deployed back-end applications and services in the cluster. In this example, an Nginx image is used and the service path is /. For deployment steps, see Using ALB Ingresses for service deployment.

Access the service by using the domain name configured in the ALB Ingress. In this example, 14.***.***.*** is the public IP address of the ALB instance.

When the access request does not contain a header, the back-end service is inaccessible. The following response is expected:

Run the following command to access the service with a client certificate included in the request:

The request contains the header and matches the forwarding condition. As a result, the back-end service is accessible. The following response is expected:

Last updated: 2026.07.24 14:51:38