Skip to content

Nginx Ingress Canary Annotations

Nginx Ingress Canary Annotations are configuration settings applied to Kubernetes Ingress resources to enable Canary Deployment strategies.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]

Nginx Ingress allows for granular traffic management at Layer 7 (HTTP/HTTPS).^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md] By adding specific annotations to an Ingress resource, administrators can route a portion of incoming traffic to a new service version (the "canary") while the majority of traffic continues to flow to the stable version.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]

Canary Annotation Key

To enable canary functionality, the Ingress resource for the new version must include the following annotation^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]:

  • nginx.ingress.kubernetes.io/canary: Set to "true" to mark the Ingress as a Canary Ingress.

Traffic Splitting Annotations

Once the canary is enabled, traffic can be routed based on headers, cookies, or weight.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]

Header-Based Routing

  • nginx.ingress.kubernetes.io/canary-by-header-value: Routes traffic to the canary if the request header matches the configured value.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]
  • nginx.ingress.kubernetes.io/canary-by-header-pattern: Functions similarly to canary-by-header-value but supports regular expressions. This annotation is ignored if canary-by-header-value is also set.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]
  • nginx.ingress.kubernetes.io/canary-by-cookie: Routes traffic to the canary if the request cookie matches the configured value. If the value is set to always, all traffic is redirected.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]

Weight-Based Routing

  • nginx.ingress.kubernetes.io/canary-weight: Specifies the percentage of traffic (0-100) to route to the canary.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]

Annotation Precedence

When multiple rules are configured, they are evaluated in a specific order of priority^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]:

  1. canary-by-header
  2. canary-by-cookie
  3. canary-weight

Example Configuration

The following example creates a Canary Ingress that sends 10% of traffic to the bar-service (version 2), while the remaining traffic goes to the main Ingress backend^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]:

apiVersion: networking.k8s.io/v1
kind: [Ingress](<./ingress.md>)
metadata:
  name: canary-ingress
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "10"
spec:
  ingressClassName: nginx
  defaultBackend:
    service:
      name: bar-service
      port:
        number: 8080

Sources

  • 400-devops-06-kubernetes-k8s-ithelp-day15-readme.md