Docs

Volcengine Kubernetes Engine

Customize ALB Ingress forwarding rules

Configuring query string-based traffic forwarding

If an ALB Ingress points to a standard ALB instance, it supports query string-based traffic forwarding. This method uses query strings to determine the back-end Service to which traffic will be forwarded.

warning

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

Background information

A query string is the segment of a URL that comes after the ? character, and is commonly used to send request parameters in the key-value pair format to a server. Its format is key=value, and it supports multiple parameters separated by the & character. For example, in the URL https://example.com/search?keyword=k8s&page=1, keyword=k8s and page=1 are the query string parameters.

Query strings are commonly used in GET requests to transmit non-sensitive data, such as search keywords and pagination information. Since parameters are exposed in the URL, they are not suitable for transmitting private content, for example, passwords. Special characters (such as spaces, Chinese characters) must be URL-encoded (for example: a space is encoded as %20) to avoid possible parsing errors.

Prerequisites

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

An ALBInstance 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 v0.37.1 or later. For details, see Upgrading add-ons.

Usage 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

Creating 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. Then click Create Ingress.

Select Application Load Balancer (ALB) for Ingress type.

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

Parameter	Description
Forwarding conditions	Configure forwarding conditions based on domain names and paths. In this configuration, add a Query string forwarding condition to specify traffic forwarding based on HTTP query strings. 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 strings in a query string-based forwarding condition, a request that matches any one of the query strings is considered a match of the forwarding condition.
Forwarding actions	Configure the forwarding action. For this example, select Forward to, which forwards requests to the target service and port.

Click Confirm.

Using kubectl

An ALB Ingress allows you to configure query string-based forwarding 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 QueryString configured in the annotation will be merged with the host configuration in spec.rules. For example, in this case, requests with example.com as the host and query string key1:value1 will all be forwarded to the service-demo service.

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 Method, which indicates a method-based forwarding policy.	No
queryStringConfig.values	Array of value	The query string in the forwarding policy. The query string contains parameters in the key-value pair format. You need to configure specific keys and values.	No

value

Parameter	Type	Description	default value
key	String	Key of the query parameter.	No
value	String	Value of the query parameter.	No

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 query string matches the configured one.

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 /demo. 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.

Since no query string is provided in the result, the back-end service cannot be accessed correctly.

Run the following command again to access the service using an allowed HTTP request method.

Since a matching query string is provided in the request, the back-end service can be accessed correctly.

Last updated: 2026.10.23 10:41:06