Docs

Volcengine Kubernetes Engine

APIG Ingress

Using APIG Ingresses to implement gray releases and blue-green deployments

APIG Ingresses enable you to use annotations to implement gray releases and blue-green deployments. This topic introduces how to use APIG Ingresses to implement gray releases and blue-green deployments.

Background information

What is gray release

Gray release, also known as Canary release, is a software release strategy that allows developers to gradually deploy new versions of software to the production environment, rather than releasing them all at once. This approach first releases software within several limited scopes and finally expands to all users if the software goes well in each scope, so as to reduce the risks in software releases.

The main characteristics of gray releases include:

Gradual release: Instead of releasing the new version to all users at once, the rollout is expanded step by step according to a plan. For example, first making it available to 1% of users, observing for a period of time, then expanding to 10%, and finally releasing to all users.

Risk control: By limiting the user scope of a new software version, it is possible to quickly roll back in case of issues and avoid a large-scale impact.

Real-time monitoring: During a gray release, you need to closely monitor software health, including performance metrics and user feedback, in order to ensure the stability of the new versions.

Flexible rollback: If the new version encounters serious problems, you can quickly roll back to the previous version to minimize the impact on users.

Gray release is very important for ensuring good software quality and user experience, especially in large-scale and complex systems. It enables teams to manage the software release process with greater flexibility and security, reducing potential risks.

Release process with APIG Ingresses

By using annotations, APIG Ingresses enable you to release services in different scenarios, including canary releases, blue-green deployments, and A/B testing. The release process is as follows:

Create two applications and two services in the cluster.

Create two Ingresses for the services: One is a standard APIG Ingress, and the other is an Ingress with the nginx.ingress.kubernetes.io/canary: "true" annotation, which is referred to as the Canary APIG Ingress. Then, bind these Ingresses to the same APIG Instance.

Use annotations to configure the traffic splitting policy for the Canary APIG Ingress according to the specific scenario.

Annotations of APIG Ingresses

The following annotations are available for gray releases with APIG Ingresses:

nginx.ingress.kubernetes.io/canary-by-header: Header-based traffic splitting policy, applicable to gray releases. Requests with the specific header will be forwarded to the backend services through Canary APIG Ingresses.

nginx.ingress.kubernetes.io/canary-by-header-value: Used together with canary-by-header to specify the value of the header. Requests with the specific header value will be forwarded to the backend services through Canary APIG Ingresses.

nginx.ingress.kubernetes.io/canary-weight: A traffic splitting policy based on service weight, applicable to blue-green deployments. This annotation specifies the traffic percentage forwarded by Canary APIG Ingresses, with a range from 0 to 100. 100 percent means all traffic will be forwarded to the backend services through Canary APIG Ingresses.

tip

The priorities of the above annotations are: canary-by-header > canary-weight.

Prerequisites

Application images have been uploaded to the Container Registry (CR). For details, see Pushing and pulling images.

The apig-controller add-on has been installed. For details, see Add-on installation.

A KubeConfig for private networks has been generated in the cluster. For details, see Connecting to clusters.

An APIGInstance has been created and bound to a newly created or existing APIG instance. For details, see Creating APIGInstance.

Deploying services in clusters

Use the following YAML configuration to create legacy applications and services.

Use the following YAML configuration to create new versions of applications and services.

Use the following YAML configuration to create an APIG Ingress and point it to the old version service.

Execute the following command to verify whether the legacy service is accessible. <EXTERNAL_IP> is the IP address exposed externally by APIG Ingress.

The following response indicates the old version application has been reached successfully.

Configuring gray releases

APIG Ingresses can implement gray releases with policies based on headers, cookies, or server weights.

warning

At most two versions of the same backend service are supported, because only one Canary APIG Ingress can be defined for the same service.

The old version services need to be retained, even if all traffic is forwarded by Canary APIG Ingress. Otherwise, errors will occur.

Use the following YAML configuration to bind Canary APIG Ingress to the new version of the services. The annotations shown below are used to enable and configure Canary, so as to filter and forward traffic based on headers. In this example, requests with the header name Region and value set to beijing will be forwarded to the new version services.

Execute the following commands to test. The expected results are as follows.

When Region does not exist, traffic is forwarded to the legacy service.

curl -H "Host: example.com" http://<EXTERNAL_IP>
This is the old version of nginx

When Region exists, and its value is not beijing, traffic is forwarded to the new version of the services.

curl -H "Host: example.com" -H "Region: shanghai" http://<EXTERNAL_IP>
This is the old version of nginx

When Region exists and its value is beijing, traffic is forwarded to the new version of the services.

curl -H "Host: example.com" -H "Region: beijing" http://<EXTERNAL_IP>
This is the new version of nginx

Gray releases based on service weights

Use the following YAML configuration to bind Canary APIG Ingress to the new version of the services. The annotations shown below are used to enable and configure Canary to filter and forward traffic based on service weights. In this example, 25% of requests are forwarded to the new version of the services.

Execute the following command to test with 20 requests.

The following responses indicate that 25% of the traffic has been forwarded to the new version of the services as expected.

tip

It is normal to have slight deviations in results due to the small sample size (20 requests). You can perform more tests or increase the sample size.

Configuring blue-green deployments

Traffic can be split based on service weights. When the weight of the new service is set to 100, blue-green deployment can be achieved.

Execute the following command to test with 20 requests.

The expected result is as follows. All traffic has been forwarded to the new version services, while the old version is retained. You can shift traffic and roll back if necessary.

Last updated: 2026.07.24 14:51:37