Annotations supported by APIG Ingress

Canary release

Multi-service routing

Setting this annotation changes the destination for all routing rules on the Ingress. If the syntax is invalid, the annotation is ignored and routing is unchanged.

Example:

annotations:
  # 60% of traffic goes to foo, 40% to bar
  higress.ingress.kubernetes.io/destination: |
    60% foo.default.svc.cluster.local:8080
    40% bar.default.svc.cluster.local:9090

Service subsets

Use service subsets to route requests to a specific subset of Pods when a single service manages multiple Deployments.

Routing behavior for `service-subset`:

• If subset-labels is not set:

  • Set to "" or base — routes to Pods labeled opensergo.io/canary: "" or Pods without any opensergo.io/canary label key.

  • Set to any other value (for example, gray) — routes to Pods labeled opensergo.io/canary-gray: gray.

• If subset-labels is set — routes only to Pods whose labels match the key-value pairs defined in subset-labels.

If no Pods match the specified label, requests are automatically forwarded to all Pods in the service.

Example:

annotations:
  # Route to the "gray" subset of Pods
  higress.ingress.kubernetes.io/service-subset: "gray"

Fallback

Regular expression match

Rewrite

Redirection

Using NGINX variables for redirection is not documented in NGINX Ingress and may pose compatibility risks. We recommend that you do not use NGINX variables for redirection.

CORS

Header control

Header control annotations on base routes and canary routes are independent and validated separately. Configure different header policies for base and canary traffic using these annotations.

Syntax:

• Single header (add/update): Use a key-value pair. Example: X-Custom-Header: value

• Multiple headers (add/update): Use a YAML block scalar (|). Each key-value pair on a separate line.

• Single header (remove): Use the header key only.

• Multiple headers (remove): Comma-separated header keys.

Example — add a request header:

annotations:
  higress.ingress.kubernetes.io/request-header-control-add: "X-Request-Id: abc123"

Example — add multiple response headers:

annotations:
  higress.ingress.kubernetes.io/response-header-control-add: |
    X-Custom-Header: value1
    X-Another-Header: value2

Example — remove multiple request headers:

annotations:
  higress.ingress.kubernetes.io/request-header-control-remove: "X-Forwarded-For,X-Real-IP"

Timeout

This timeout applies at the application layer (HTTP), not at the TCP transport layer.

Retry

Traffic mirroring

Example:

annotations:
  # Mirror 20% of traffic to the shadow service
  higress.ingress.kubernetes.io/mirror-target-service: "default/shadow-service:8080"
  higress.ingress.kubernetes.io/mirror-percentage: "20"

Domain alias

Rate limiting (deprecated)

These annotations are deprecated. Use global throttling control instead.

Global throttling control (recommended)

All annotations in this section require gateway version V1.2.25 or later.

rate-limit-fallback-custom-response-code and rate-limit-fallback-redirect-url are mutually exclusive. Set only one.

Example — return a custom JSON response when rate limiting is triggered:

annotations:
  higress.ingress.kubernetes.io/rate-limit: "100"
  higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-code: "429"
  higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type: "json"
  higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body: '{"error":"rate limit exceeded"}'

Global concurrency control

All annotations in this section require gateway version V1.2.25 or later.

concurrency-limit-fallback-custom-response-code and concurrency-limit-fallback-redirect-url are mutually exclusive. Set only one.

Backend protocol

Load balancing

Warmup (graceful start)

Cookie affinity

IP address access control

Connection pool (gateway to backend)

Client-to-gateway TLS

Default cipher suites for ssl-cipher: ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES128-SHA, ECDHE-RSA-AES128-SHA, AES128-GCM-SHA256, AES128-SHA, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES256-SHA, ECDHE-RSA-AES256-SHA, AES256-GCM-SHA384, AES256-SHA.

Gateway-to-backend TLS

Basic authentication

Full NGINX Ingress annotation reference: Annotations.