Canary deployments in Kubernetes - Commands & Configuration

Introduction

When you want to release a new version of your app safely, you can send only a small part of your users to the new version first. This helps catch problems early without affecting everyone. This method is called canary deployment.

When you want to test a new app version with a small group of users before full release

When you want to reduce risk by gradually shifting traffic to a new version

When you want to monitor new version performance and errors before full rollout

When you want to rollback quickly if the new version has issues

When you want to run two versions of your app side-by-side during an update

Config File - canary-deployment.yaml

canary-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 5
  selector:
    matchLabels:
      app: my-app
      version: stable
  template:
    metadata:
      labels:
        app: my-app
        version: stable
    spec:
      containers:
      - name: my-app-container
        image: my-app:1.0
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-canary
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
      version: canary
  template:
    metadata:
      labels:
        app: my-app
        version: canary
    spec:
      containers:
      - name: my-app-container
        image: my-app:1.1
---
apiVersion: v1
kind: Service
metadata:
  name: my-app-service
spec:
  selector:
    app: my-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080

This file creates two deployments: one stable with 5 replicas running version 1.0, and one canary with 1 replica running version 1.1. The service selects pods with label app: my-app, so it sends traffic to both stable and canary pods. This setup lets you send about 1/6 of traffic to the new version for testing.

Commands

This command creates the stable and canary deployments and the service that routes traffic to both versions.

Terminal

kubectl apply -f canary-deployment.yaml

Expected Output

deployment.apps/my-app created

deployment.apps/my-app-canary created

service/my-app-service created

This command lists all pods with label app=my-app to verify both stable and canary pods are running.

Terminal

kubectl get pods -l app=my-app -o wide

Expected Output

NAME                          READY   STATUS    RESTARTS   AGE   IP           NODE

my-app-abcdef1234-xyz12       1/1     Running   0          1m    10.244.1.5   node1

my-app-abcdef1234-xyz34       1/1     Running   0          1m    10.244.1.6   node2

my-app-canary-12345abcde-xy1  1/1     Running   0          30s   10.244.1.7   node3

→

-l - Filter pods by label

→

-o wide - Show extra pod details like IP and node

This command shows the service details to confirm it selects pods with label app=my-app and routes traffic to both stable and canary pods.

Terminal

kubectl describe service my-app-service

Expected Output

Name:                     my-app-service

Namespace:                default

Labels:                   <none>

Selector:                 app=my-app

Type:                     ClusterIP

IP:                       10.96.0.1

Port:                     <unset>  80/TCP

TargetPort:               8080/TCP

Endpoints:                10.244.1.5:8080,10.244.1.6:8080,10.244.1.7:8080

Session Affinity:         None

Events:                   <none>

This command checks the rollout status of the canary deployment to ensure the new version is running smoothly.

Terminal

kubectl rollout status deployment/my-app-canary

Expected Output

deployment "my-app-canary" successfully rolled out

Key Concept

If you remember nothing else from this pattern, remember: run the new version alongside the old one with fewer pods and route only a small share of traffic to it for safe testing.

Common Mistakes

Creating only one deployment and replacing the old version immediately

This causes all users to get the new version at once, increasing risk of failure without gradual testing.

Create a separate canary deployment with fewer replicas and run it alongside the stable deployment.

Service selector only matches stable pods, ignoring canary pods

Traffic will not reach the canary pods, so the new version is not tested with real users.

Use a service selector that matches both stable and canary pods by a common label.

Not checking rollout status of the canary deployment

You might miss errors or crashes in the new version before sending traffic.

Use 'kubectl rollout status' to verify the canary deployment is healthy before increasing traffic.

Summary

Create two deployments: stable with most replicas and canary with fewer replicas running the new version.

Use a service that selects both stable and canary pods to split traffic between versions.

Check pods and rollout status to ensure the canary version is running well before full rollout.