Run a Canary Release Behind an Existing Service

Original Prepium guide · Written for Kubernetes v1.35 and checked against the official documentation on 6 October 2026. Use a disposable practice cluster.

Split traffic by replica count: a manual canary behind one Service

Kubernetes has no built-in "send 10% to the new version" switch. What it does have is a Service that forwards to every ready Pod matching its selector. If two Deployments produce Pods that both match that selector, the share each version receives follows the share of Pods it owns. That is the whole canary trick, and the exam expects you to build it with labels and prove it with EndpointSlices.

Service quotes  (selector: app=quotes)
   |-- quotes-stable  3 Pods  app=quotes, release=stable
   '-- quotes-canary  1 Pod   app=quotes, release=canary   => about 1 in 4 requests

1. Give every Pod a shared label and a track label

Each Pod template carries two labels. app=quotes is the one the Service selects. release tells the tracks apart, and each Deployment includes it in its own spec.selector, so the two controllers never claim each other's Pods. The image is the small hostname server from the Kubernetes Service debugging guide; it answers on port 9376 with the Pod's name, which makes the split visible. Save this as canary-tracks.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: quotes-stable
  namespace: prepium-tutorial
spec:
  replicas: 3
  selector:
    matchLabels:
      app: quotes
      release: stable
  template:
    metadata:
      labels:
        app: quotes
        release: stable
    spec:
      containers:
      - name: server
        image: registry.k8s.io/serve_hostname
        ports:
        - containerPort: 9376
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: quotes-canary
  namespace: prepium-tutorial
spec:
  replicas: 1
  selector:
    matchLabels:
      app: quotes
      release: canary
  template:
    metadata:
      labels:
        app: quotes
        release: canary
    spec:
      containers:
      - name: server
        image: registry.k8s.io/serve_hostname
        ports:
        - containerPort: 9376
---
apiVersion: v1
kind: Service
metadata:
  name: quotes
  namespace: prepium-tutorial
spec:
  selector:
    app: quotes
  ports:
  - port: 80
    targetPort: 9376

kubectl create namespace prepium-tutorial
kubectl apply -f canary-tracks.yaml
kubectl -n prepium-tutorial get pods -l app=quotes -L release

The -L release flag adds a RELEASE column, so you can count stable and canary Pods at a glance.

2. Prove both tracks sit behind the Service

The control plane builds EndpointSlices for any Service with a selector and labels them with kubernetes.io/service-name. Each endpoint has a targetRef naming the Pod and a conditions.ready flag:

kubectl -n prepium-tutorial get endpointslices -l kubernetes.io/service-name=quotes \
  -o jsonpath='{range .items[*].endpoints[*]}{.targetRef.name}{"\t"}{.conditions.ready}{"\n"}{end}'

You want four lines, three starting with quotes-stable- and one with quotes-canary-, all true. Now sample real traffic from inside the cluster:

kubectl -n prepium-tutorial run probe --image=busybox:1.36 --restart=Never --rm -it -- \
  sh -c 'for i in $(seq 1 20); do wget -qO- http://quotes; echo; done'

Roughly a quarter of the replies should name the canary Pod. In kube-proxy's iptables mode each new connection picks a backend at random, so the ratio is a tendency over many requests, not an exact rotation.

3. Move the dial by scaling

The canary share is canary Pods divided by all ready Pods. Promote the canary to half the traffic without touching any label:

kubectl -n prepium-tutorial scale deployment quotes-stable --replicas=2
kubectl -n prepium-tutorial scale deployment quotes-canary --replicas=2

Re-run the EndpointSlice query: two of each. Only ready endpoints count, so a canary Pod failing its readiness probe receives nothing, which is often exactly the safety net you want.

4. Contrast: blue-green switches the selector instead

Blue-green keeps both versions fully scaled and makes the Service choose one by adding the track label to its selector. The cut-over is a single selector change, all or nothing, and rollback is the same change in reverse:

kubectl -n prepium-tutorial patch service quotes --type=merge \
  -p '{"spec":{"selector":{"app":"quotes","release":"canary"}}}'

The EndpointSlice now lists only canary Pods. Canary trades that instant switch for gradual exposure.

Common mistakes

• Both Deployments select only app=quotes. Their selectors overlap, which the Deployment docs warn makes controllers conflict; keep the track label in each selector.
• The Service selector includes the stable track label. The canary Pods run happily but never appear in the EndpointSlice, so they get zero traffic.
• A typo in the shared label (app: quote) on one template. Same symptom: Running Pods missing from the endpoint list.
• Editing a Deployment's spec.selector after creation. It is immutable in apps/v1, so the API rejects the change; delete and recreate instead.
• kubectl set selector replaces the whole Service selector, so passing only the track label silently drops app.

Cleanup: kubectl delete namespace prepium-tutorial. References: Deploy a release using a canary deployment, EndpointSlices, Virtual IPs and service proxies. Next, try rolling updates and rollback or Service selector troubleshooting.