How to Implement Canary Deployments with Istio on Kubernetes

Background Overview

In internet companies the production environment hosts core business services, so a faulty release can cause significant loss. To meet stability requirements, gray (canary) releases are a necessary capability.

Why Native Kubernetes Service Is Insufficient

Kubernetes uses a Service as a load balancer, which distributes requests to Pods, but it does not provide built‑in traffic‑splitting or canary features. A naive approach is to control the number of Pods for each version (e.g., 1 Pod for v2 and 4 Pods for v1), which results in a roughly 20% traffic share for v2 based on random scheduling. This method is inflexible and cannot achieve fine‑grained traffic control.

Istio’s Canary Capabilities

Istio offers two primary canary mechanisms: traffic‑percentage based routing and precise routing based on request headers, cookies, etc. Configuration is performed through three custom resources:

Gateway : defines the external entry point.

VirtualService : describes routing rules.

DestinationRule : groups service versions into subsets.

Example 1 – Percentage‑Based Canary

Route 90% of traffic to version v1 and 10% to version v2.

# gateway-http.yaml
apiVersion: networking.istio.io/v1
kind: Gateway
metadata:
  name: demo-gateway  # custom gateway name
  namespace: default  # usually same namespace as the service or istio-system
spec:
  selector:
    istio: ingressgateway  # default Istio ingress gateway label (do not modify)
  servers:
  - port:
      number: 80
      name: http
      protocol: HTTP
    hosts:
    - demo.example.com  # external domain pointing to the Istio gateway IP

# virtualservice-grey-gateway.yaml
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: demo-service
  namespace: default
spec:
  hosts:
  - demo.example.com  # must match Gateway hosts
  gateways:
  - demo-gateway      # bind to the Gateway defined above
  http:
  - route:
    - destination:
        host: demo-service
        subset: v1
        weight: 90  # 90% traffic to v1
    - destination:
        host: demo-service
        subset: v2
        weight: 10  # 10% traffic to v2

# DestinationRule for the service
apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: demo-service
  namespace: default
spec:
  host: demo-service
  subsets:
  - name: v1
    labels:
      version: v1
  - name: v2
    labels:
      version: v2
  trafficPolicy:
    loadBalancer:
      simple: ROUND_ROBIN

Example 2 – Header‑Based Precise Canary

This example routes requests that contain the header X-Version: v2 to the v2 subset, while all other traffic continues to v1.

# virtualservice-header-gateway.yaml (header‑based canary)
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: demo-service
  namespace: default
spec:
  hosts:
  - demo.example.com
  gateways:
  - demo-gateway
  http:
  # Rule 1: match requests with X-Version: v2
  - match:
    - headers:
        X-Version:
          exact: v2
    route:
    - destination:
        host: demo-service
        subset: v2
  # Rule 2: default route for all other traffic
  - route:
    - destination:
        host: demo-service
        subset: v1

Conclusion

Istio, as a key component of the Kubernetes ecosystem, extends traffic control, security, and other capabilities without requiring code changes. Its language‑agnostic design makes it suitable for heterogeneous micro‑service environments, providing reliable, non‑intrusive canary deployment mechanisms.