Configure a canary deployment

Canary deployments release applications incrementally to a subset of users, which allows for the gradual deployment of new application versions without any downtime.

NGINX Ingress Controller supports traffic-splitting policies based on header, cookie, and weight. Whereas header- and cookie-based policies serve to provide a new service version to a subset of users, weight-based policies serve to divert a percentage of traffic to a new service version.

NGINX Ingress Controller uses the following annotations to enable canary deployments:

  • nginx.ingress.kubernetes.io/canary-by-header

  • nginx.ingress.kubernetes.io/canary-by-header-value

  • nginx.ingress.kubernetes.io/canary-by-header-pattern

  • nginx.ingress.kubernetes.io/canary-by-cookie

  • nginx.ingress.kubernetes.io/canary-weight

Canary rules are evaluated in the following order:

  1. canary-by-header

  2. canary-by-cookie

  3. canary-weight

Canary deployments require that you create two ingresses: one for regular traffic and one for alternative traffic. Be aware that you can apply only one canary ingress.

You enable a particular traffic-splitting policy by setting the associated canary annotation to true in the Kubernetes Ingress resource, as in the following example:

nginx.ingress.kubernetes.io/canary-by-header: "true"

Refer to Ingress Canary Annotations in the NGINX Ingress Controller documentation for more information.

Example canary setup

  1. Deploy two services, echo-v1 and echo-v2, using either the MKE web UI or kubectl.

    To deploy echo-v1:
    apiVersion: v1
    kind: Service
    metadata:
      name: echo-v1
    spec:
      type: ClusterIP
      ports:
        - port: 80
          protocol: TCP
          name: http
      selector:
        app: echo
        version: v1
    
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: echo-v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: echo
          version: v1
      template:
        metadata:
          labels:
            app: echo
            version: v1
        spec:
          containers:
            - name: echo
              image: "docker.io/hashicorp/http-echo"
              args:
                - -listen=:80
                - --text="echo-v1"
              ports:
                - name: http
                  protocol: TCP
                  containerPort: 80
    
    To deploy echo-v2:
    apiVersion: v1
    kind: Service
    metadata:
      name: echo-v2
    spec:
      type: ClusterIP
      ports:
        - port: 80
          protocol: TCP
          name: http
      selector:
        app: echo
        version: v2
    
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: echo-v2
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: echo
          version: v2
      template:
        metadata:
          labels:
            app: echo
            version: v2
        spec:
          containers:
            - name: echo
              image: "docker.io/hashicorp/http-echo"
              args:
                - -listen=:80
                - --text="echo-v2"
              ports:
                - name: http
                  protocol: TCP
                  containerPort: 80
    
  2. Create an Ingress to route the traffic for the regular service:

    Example Ingress
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      annotations:
        ingress.kubernetes.io/rewrite-target: /
      name: ingress-echo
    spec:
      ingressClassName: nginx-default
      rules:
        - host: canary.example.com
          http:
            paths:
              - path: /echo
                pathType: Exact
                backend:
                  service:
                    name: echo-v1
                    port:
                      number: 80
    
  3. Verify that traffic is successfully routed:

    curl -H "Host: canary.example.com" http://<IP_ADDRESS>:<NODE_PORT>/echo
    

    Expected output:

    echo-v1
    

Canary deployment use cases

To provide a subset of users with a new service version using a request header:

  1. Create a canary ingress that routes traffic to the echo-v2 service using the request header x-region: us-east:

    Header-based policy
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      annotations:
        ingress.kubernetes.io/rewrite-target: /
        nginx.ingress.kubernetes.io/canary: "true"
        nginx.ingress.kubernetes.io/canary-by-header: "x-region"
        nginx.ingress.kubernetes.io/canary-by-header-value: "us-east"
      name: ingress-echo-canary
    spec:
      ingressClassName: nginx-default
      rules:
        - host: canary.example.com
          http:
            paths:
              - path: /echo
                pathType: Exact
                backend:
                  service:
                    name: nginx-v2
                    port:
                      number: 80
    
  2. Verify that traffic is properly routed:

    curl -H "Host: canary.example.com" -H "x-region: us-east" \
    http://<IP_ADDRESS>:<NODE_PORT>/echo
    curl -H "Host: canary.example.com" -H "x-region: us-west" \
    http://<IP_ADDRESS>:<NODE_PORT>/echo
    curl -H "Host: canary.example.com" \
    http://<IP_ADDRESS>:<NODE_PORT>/echo
    

    Expected output:

    echo-v2
    echo-v1
    echo-v1
    

To provide a subset of users with a new service version using a cookie:

  1. Create a canary ingress that routes traffic to the echo-v2 service using a cookie:

  2. Verify that traffic is properly routed:

    curl -s -H "Host: canary.example.com" --cookie "my_cookie=always" \
    http://<IP_ADDRESS>:<NODE_PORT>/echo
    curl -s -H "Host: canary.example.com" --cookie "other_cookie=always" \
    http://<IP_ADDRESS>:<NODE_PORT>/echo
    curl -s -H "Host: canary.example.com" \
    http://<IP_ADDRESS>:<NODE_PORT>/echo
    

    Expected output:

    echo-v2
    echo-v1
    echo-v1
    

To route a segment of traffic to a new service version:

  1. Create a canary ingress that routes 20% of traffic to the echo-v2 service using the nginx.ingress.kubernetes.io/canary-weight annotation:

    Weight-based policy
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      annotations:
        ingress.kubernetes.io/rewrite-target: /
        nginx.ingress.kubernetes.io/canary: "true"
        nginx.ingress.kubernetes.io/canary-weight: "20"
      name: ingress-echo-canary
    spec:
      ingressClassName: nginx-default
      rules:
        - host: canary.example.com
          http:
            paths:
              - path: /echo
                pathType: Exact
                backend:
                  service:
                    name: echo-v2
                    port:
                      number: 80
    
  2. Verify that traffic is properly routed:

    for i in {1..10}; do curl -H "Host: canary.example.com" \
    http://<IP_ADDRESS>:<NODE_PORT>/echo
    

    Example output:

    "echo-v1"
    "echo-v2"
    "echo-v2"
    "echo-v1"
    "echo-v1"
    "echo-v1"
    "echo-v1"
    "echo-v1"
    "echo-v1"
    "echo-v1"