Skip to content

For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Canary Deployments

Verified : Automated tests passed for: Kubernetes resources: The Kubernetes resources on this page were checked against their API schemas. End-to-end run: Every step ran in a fresh test environment and the results were checked.
Page as Markdown
Convert Ingress NGINX canary annotations to weighted HTTPRoute backends.
NGINX’s canary annotations let you split traffic between versions. The tool merges these into a single HTTPRoute with weighted backends.
Before: Primary and canary Ingresses

cat <<'EOF' > canary-ingress.yaml
# Primary Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-primary
spec:
  ingressClassName: nginx
  rules:
  - host: app.example.com
    http:
      paths:
      - backend:
          service:
            name: app-v1
            port:
              number: 80
        path: /
        pathType: Prefix
---
# Canary Ingress (20% of traffic)
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-canary
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
spec:
  ingressClassName: nginx
  rules:
  - host: app.example.com
    http:
      paths:
      - backend:
          service:
            name: app-v2
            port:
              number: 80
        path: /
        pathType: Prefix
EOF
Convert

ingress2gateway print --providers=ingress-nginx --emitter=kgateway \
  --input-file canary-ingress.yaml > canary-kgateway.yaml
The tool prints a warning that it does not translate HTTPS for the app.example.com host. By default, Ingress NGINX serves HTTPS for every host with a self-signed certificate. The generated Gateway has only an HTTP listener. To serve HTTPS, add an HTTPS listener to the Gateway. For more information, see HTTPS listener.
After: HTTPRoute with weighted backends

cat canary-kgateway.yaml
The output has a Gateway and one HTTPRoute. Both Ingresses merge into the HTTPRoute, which takes its name from the canary Ingress, app-canary. The weights send 80% of traffic to app-v1 and 20% to app-v2. The order of the two backends in the output can change from one run to the next.
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: nginx
spec:
  gatewayClassName: kgateway
  listeners:
  - hostname: app.example.com
    name: app-example-com-http
    port: 80
    protocol: HTTP
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-canary-app-example-com
spec:
  hostnames:
  - app.example.com
  parentRefs:
  - name: nginx
  rules:
  - backendRefs:
    - name: app-v1
      port: 80
      weight: 80
    - name: app-v2
      port: 80
      weight: 20
    matches:
    - path:
        type: PathPrefix
        value: /
    name: rule-0
Apply

kubectl apply -f canary-kgateway.yaml
External AuthBackend TLS
Was this page helpful?