Docs

Volcengine Kubernetes Engine

Customize ALB Ingress forwarding rules

Configuring traffic forwarding rewrite

ALB Ingresses support request path rewriting. When a request passes through the ALB instance, it can directly modify the request path and fetch content from the new path on the back-end server, enabling dynamic management of back-end services.

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 by using kubectl.

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

Limits

Supported configuration methods vary based on different ALB instance types.

Standard edition: You can configure this type of instance by using the console or YAML.

Basic edition: You can configure this type of instance only by using YAML.

When you configure the Rewrite forwarding action, you also need to configure the Forward to forwarding action. For more limits and considerations, see Creating forwarding rules (Standard edition).

Procedure

Configure by using the console

tip

You can only use the console to configure an ALB ingress that uses a Standard edition ALB instance. To use a Basic edition ALB instance, see the following YAML configuration.

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.

Enable Custom forwarding rules and configure the details of the 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	Set Forwarding actions 1 to Rewrite, and configure the forwarding path. Set Forwarding actions 2 to Forward to, and configure the target service and port for forwarding.

Click Confirm.

Configure by using kubectl

ALB Ingresses allow you to configure forward traffic rewriting rules by using annotations. The configuration slightly varies based on whether the ALB Ingress uses a Standard edition ALB instance or a Basic edition ALB instance.

Standard edition ALB

Basic edition ALB

The following content describes the sample configurations and annotation descriptions of the ALB Ingress when it uses a Standard edition ALB instance.

Warning

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-actions.service-demo.

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

Parameter	Type	Description	Default value
type	String	The action type of the custom forwarding rule. When configuring rewriting, set the value to Rewrite.	No
rewriteConfig.path	String	Configure the forwarding path.	No

Validating results

Viewing configuration

tip

The details pages of forwarding rules differ between Standard edition ALB instances and Basic edition ALB instances. This topic provides an example of viewing the details page of a forwarding rule for a Standard edition ALB instance.

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. You can view the newly added rewriting forwarding rule.

For a forwarding rule, click to view rule details. The rule details should be consistent with 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 /aaa. 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.

The expected result is as follows: When the requested domain is example.com and the original path is /, the back-end service is accessible through the ALB Ingress after the path is rewritten to /aaa.

Regular expression matching

Standard edition ALB

Matching rule

When the ALB Ingress uses a Standard edition ALB instance, matching and replacement based on regular expressions are supported. The basic rules are as follows:

URI rewrite rules

Static paths. Specify the exact target path, for example /aaa.

Dynamic paths

Define one or multiple regular expression patterns in the Ingress path field. Multiple variables represented by () are supported. In rewriteConfig.path, reference one or more variables by using ${1}, ${2}, or ${3}. Up to three variables can be referenced.

Dynamically construct desired rewrite rules by combining matched results based on regular expression patterns.

Rewrites occur when client requests match the regular expression pattern containing multiple () variables and the rewriteConfig.path annotation contains one or more of placeholders ${1}, ${2}, and ${3}.

Examples

The following content describes the matching example of the ALB Ingress when it uses a Standard edition ALB instance.

Warning

tip

For the ALB service, regular expressions must start with ~. In addition, Kubernetes requires that the path field of spec for an Ingress resource must start with /. As a result, the regular expression pattern in the path field in spec in the above example is written as /~gateway(/|$)(.*) to meet both requirements. However, the actual pattern applied is ~gateway(/|$)(.*). For details, see Creating forwarding rules.

Basic edition ALB

Matching rule

When the ALB Ingress uses a Basic edition ALB instance, matching and replacement based on regular expressions are supported. The basic rules are as follows:

Host consistency. The host in the annotation must be identical to the host in spec.

Path formatting

To specify a static path (such as /demo) in spec, set the path in the annotation to the exact path (/demo).

To specify a regular expression (such as /~/(.*)) as the path in spec, for the path in the annotation, remove the leading / from the regular expression and set the value to ~/(.*).

URI rewrite rules

Static paths: Specify the exact target path. For example: /aaa.

Dynamic paths

Define one or multiple regular expression patterns in the Ingress path field. Multiple variables represented by () are supported. In rewriteURI, reference one or more variables by using ${1}, ${2}, or ${3}. Up to three variables can be referenced.

Dynamically construct desired rewrite rules by combining matched results based on regular expression patterns.

Rewrites occur when client requests match a regular expression pattern containing multiple () variables and the rewriteURI annotation contains one or more placeholders ${1}, ${2}, and ${3}.

tip

For example, you configure path in the annotation as ~gateway/(.*)/(.*)/aaa, and rewriteURI as /${1}/${2}. If a client sends a request to the path /gateway/ccc/bbb/aaa, the path matches ~gateway/(.*)/(.*)/aaa, ${1} in rewriteURI is replaced with ccc, and ${2} is replaced with bbb. Ultimately, the back-end server receives the request path /ccc/bbb.

Examples

The following content describes the sample configurations of the ALB Ingress when it uses a Basic edition ALB instance.

tip

Last updated: 2026.07.24 14:51:38

Parameters	Type	Description	default value
host	String	The forwarding domain name for the rewrite rule. This must be consistent with the domain name in the spec that needs to be rewritten.	No
path	String	The path for the rewrite rule. This must be consistent with the path to be rewritten in the spec. tip Regular expression matching is supported. For details, see Regular expression matching.	No
rewriteURI	String	The forwarding path after the rewrite.	No