Container Service for Kubernetes:Advanced APIG Ingress usage

Header-based canary release

Example 1: Route requests with header `apig: always` to the canary service

Example 2: Route to multiple canary versions by header value (`apig: v1` → v1, `apig: v2` → v2)

Query parameter-based canary release

Header-based and query parameter-based rules can be combined. When both are configured, a request is routed to the canary service only if both conditions match.

Example 1: Route requests with URL query parameter `canary=gray` to the canary service

Example 2: Route to canary only when both `canary=gray` in URL and `x-user-id: test` in header are present

Cookie-based canary release

Use nginx.ingress.kubernetes.io/canary-by-cookie to split traffic based on a cookie. Set the cookie value to always to route requests to the canary service; all other requests go to the production service.

Cookie-based canary release does not support custom values. The cookie value must be always.

Example: Route requests with cookie `demo=always` to the canary service

Weight-based canary release

Example: Split traffic across three versions — canary v1 at 30%, canary v2 at 20%, production at 50%

Use the pod label convention for APIG Ingress

Set higress.ingress.kubernetes.io/service-subset to specify which Pod group receives requests. By default, APIG Ingress maps the subset value to Pod labels prefixed with opensergo.io/canary:

• Value "" or base: routes to Pods with label opensergo.io/canary: "" or Pods that have no opensergo.io/canary-prefixed label.

• Any other string (e.g., gray): routes to Pods with label opensergo.io/canary-gray: gray.

Example: Route `x-user-id: test` requests to the gray Deployment of go-httpbin

First, apply the Service and Deployments:

# Kubernetes Service
apiVersion: v1
kind: Service
metadata:
  name: go-httpbin
  namespace: default
spec:
  ports:
    - port: 8080
      protocol: TCP
  selector:
    app: go-httpbin
---
# Base Deployment — no opensergo.io/canary label
apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-httpbin-base
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: go-httpbin
  template:
    metadata:
      labels:
        app: go-httpbin
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/apig/go-httpbin
          args:
            - "--version=base"
          imagePullPolicy: Always
          name: go-httpbin
---
# Gray Deployment — has label opensergo.io/canary-gray: gray
apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-httpbin-gray
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: go-httpbin
  template:
    metadata:
      labels:
        app: go-httpbin
        opensergo.io/canary-gray: gray
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/apig/go-httpbin
          args:
            - "--version=gray"
          imagePullPolicy: Always
          name: go-httpbin

Then configure the Ingress resources:

Use custom labels

To target Pods by any arbitrary label — not the opensergo.io/canary convention — set both higress.ingress.kubernetes.io/service-subset and higress.ingress.kubernetes.io/subset-labels.

When subset-labels is configured, the subset is no longer mapped to opensergo.io/canary-prefixed labels.

Example: Route `x-user-id: test` requests to Pods with label `version: gray`

First, apply the Deployments (the version: gray label is added to the gray Deployment's Pod template):

# go-httpbin Kubernetes Service
apiVersion: v1
kind: Service
metadata:
  name: go-httpbin
  namespace: default
spec:
  ports:
    - port: 8080
      protocol: TCP
  selector:
    app: go-httpbin
---
# Base Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-httpbin-base
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: go-httpbin
  template:
    metadata:
      labels:
        app: go-httpbin
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/apig/go-httpbin
          args:
            - "--version=base"
          imagePullPolicy: Always
          name: go-httpbin
---
# Gray Deployment — uses the custom label version: gray
apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-httpbin-gray
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: go-httpbin
  template:
    metadata:
      labels:
        app: go-httpbin
        version: gray
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/apig/go-httpbin
          args:
            - "--version=gray"
          imagePullPolicy: Always
          name: go-httpbin

Then configure the Ingress resources:

Path rewrite

All examples below use nginx.ingress.kubernetes.io/rewrite-target to modify the request path.

Example 1: Rewrite `example.com/test` to `example.com/dev` before forwarding

Example 2: Strip the `/v1` prefix — rewrite `example.com/v1/xxx` to `example.com/xxx`

Example 3: Replace the `/v1` prefix with `/v2` — rewrite `example.com/v1/xxx` to `example.com/v2/xxx`

Host rewrite

Example: Rewrite the host from `example.com` to `test.com` before forwarding

HTTP-to-HTTPS redirect

APIG Ingress treats ssl-redirect and force-ssl-redirect identically — both force an HTTP-to-HTTPS redirect.

Example: Redirect `http://example.com/test` to `https://example.com/test`

Permanent redirect

Example: Permanently redirect `http://example.com/test` to `http://example.com/app`

Temporary redirect

Use nginx.ingress.kubernetes.io/temporal-redirect to specify the destination URL for a temporary redirect. The URL must include the scheme (http:// or https://).

Example: Temporarily redirect `http://example.com/test` to `http://example.com/app`

Request header control

All three annotations share the same multi-header syntax: a single header uses a key-value pair; multiple headers use the YAML | block scalar with one key-value pair per line.

Example 1: Add headers `foo: bar` and `test: true` to all requests to `example.com/test`

Example 2: Use header control together with canary releases to tag traffic by deployment stage

When apig: v1 is present in the request header, APIG Ingress routes to the canary and adds stage: gray. All other requests go to the base version and receive stage: production.

Response header control

Example: Remove the `req-cost-time` header from responses to `example.com/test`

Route-level IP access control

Example 1: Allow access to `example.com/test` only from `1.1.X.X`

Example 2: Block access to `example.com/test` from `2.2.2.2`

Domain-level IP access control

Example 1: Allow access to all routes under `example.com` from `1.1.X.X` and `2.2.2.2`

Example 2: Combine domain-level and route-level allowlists — restrict `/order` to `3.3.X.X` while allowing `1.1.X.X` and `2.2.2.2` on all other routes

Custom response

Example 1: Limit `example.com/test` to 100 RPS with the default throttling response

Example 2: Limit `example.com/test` to 100 RPS; return HTTP 503 with body `server is overload` when throttled

Redirection

Use higress.ingress.kubernetes.io/rate-limit-fallback-redirect-url to redirect clients to a fallback URL when throttling is triggered.

Example: Limit `example.com/test` to 100 RPS; redirect to `example.com/fallback` when throttled

Custom response

Example 1: Limit concurrent requests to `example.com/test` to 1,000 with the default response

Example 2: Limit concurrent requests to 1,000; return HTTP 503 with body `server is overloaded` when the limit is reached

Redirection

Use higress.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url to redirect clients to a fallback URL when concurrency control is triggered.

Example: Limit concurrent requests to 1,000; redirect to `example.com/fallback` when the limit is reached

Common load balancing algorithms

Use nginx.ingress.kubernetes.io/load-balance to set the algorithm.

Example: Use least connections for the demo-service backend

Load balancing algorithms based on consistent hashing

Consistent hashing ensures that requests with the same key are always routed to the same backend node — useful for session-aware applications or cache locality. Set the hash key using nginx.ingress.kubernetes.io/upstream-hash-by.

Supported hash key types:

Example 1: Route all requests from the same client IP to the same backend node

Example 2: Route requests with the same `X-Stage` header value to the same backend node

Example 3: Route requests with the same `X-Stage` query parameter value to the same backend node