Skip to content

Canary Ingress Pattern

The Canary Ingress Pattern is a deployment strategy implementation in Kubernetes that utilizes the Ingress resource and specific annotations to route a subset of external traffic to a new service version.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md] This approach allows for safe, gradual rollouts by validating the new version with a small percentage of users before a full cutover.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]

Implementation Mechanism

This pattern relies on the Nginx Ingress Controller and its support for specific annotations within the Ingress resource definition.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md] To enable the pattern, two Ingress resources are typically created: a primary Ingress for the stable version and a "canary" Ingress for the new version.

The canary Ingress must be enabled by setting the nginx.ingress.kubernetes.io/canary annotation to "true".^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md] Once enabled, traffic can be routed to the canary service based on three primary strategies, processed in the following order of priority^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]:

  1. Header-based routing (canary-by-header-value): Routes traffic if a request header matches a specific value.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]
  2. Cookie-based routing (canary-by-cookie): Routes traffic if a request cookie matches a specific value (e.g., "always" to route all traffic).^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]
  3. Weight-based routing (canary-weight): Routes a specific percentage of traffic (0–100) to the canary service.^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]

Strategy Workflow

Implementing a Canary Deployment using Ingress generally involves the following iterative process^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]:

  1. Baseline: Deploy the stable version (e.g., v1) and configure the main Ingress to route all traffic to it.
  2. Coexistence: Deploy the new version (e.g., v2) alongside the old version without exposing it via the main Ingress rules.
  3. Activation: Create the Canary Ingress resource with the chosen traffic splitting logic (e.g., setting canary-weight to 10).
  4. Migration: Gradually increase the weight or configuration to direct more traffic to v2 after validating stability.
  5. Cutover: Update the main Ingress to point directly to the new service (v2) and remove the Canary Ingress and old resources (v1).

Sources

^[400-devops-06-kubernetes-k8s-ithelp-day15-readme.md]