How do I run a canary deployment?¶

Keyword: How do I run a canary deployment on SmartTouch?

A canary deployment routes a percentage of traffic to a new service version while the current version continues to serve the remainder. SmartTouch uses traffic splitting to manage the canary percentage. You increase the canary weight incrementally as you gain confidence in the new version.

Goal¶

Deploy Remote Access Service v1.2.0 as a canary alongside v1.1.0, starting at 10% traffic, and promote to 100% once validated.

Prerequisites¶

v1.2.0 image built and pushed to Harbor
stctl authenticated with developer or higher role
Familiarity with the standard deployment workflow—see How do I deploy a service?

How canary traffic splitting works¶

Incoming sessions
        ↓
Istio ingress gateway
        ↓
VirtualService weight rule
  ├── 10% → remote-access-service v1.2.0 (canary)
  └── 90% → remote-access-service v1.1.0 (stable)

Istio routes a percentage of new sessions to the canary. Existing open sessions aren't affected — they remain on the version that established them.

Steps¶

Step 1—Add the canary configuration to your SSD¶

# smarttouch.yaml
service:
  name: remote-access-service
  version: "1.2.0"

deployment:
  image: harbor.smarttouch.io/myteam/remote-access-service:1.2.0
  replicas: 1              # Canary starts with a single replica

canary:
  enabled: true
  stable-version: "1.1.0"
  initial-weight: 10       # Percentage of new sessions routed to the canary
  analysis:
    metrics:
      - name: error-rate
        threshold: 1        # Canary is halted if error rate exceeds 1%
      - name: session-open-latency-p99
        threshold: 500      # Canary is halted if p99 session open latency exceeds 500ms
    interval: 5m            # Metrics are evaluated every 5 minutes

Step 2—Push and merge the canary configuration¶

Follow the standard pull request workflow. After merge, Argo CD deploys the canary alongside the stable version.

Verify both versions are running:

stctl pods --env dev --service remote-access-service

Expected:

POD NAME                             VERSION   STATUS    READY
remote-access-service-stable-abc12   1.1.0     Running   1/1
remote-access-service-canary-def34   1.2.0     Running   1/1

Step 3—Monitor canary metrics¶

SmartTouch evaluates the canary automatically against the metrics defined in the SSD. View the current canary status:

stctl canary status --env dev --service remote-access-service

Expected output during a healthy canary run:

Canary status:    progressing
Stable version:   1.1.0  (90% of sessions)
Canary version:   1.2.0  (10% of sessions)

Canary metrics (last 5m):
  error-rate:                 0.2%  ✔  (threshold: 1%)
  session-open-latency-p99:   120ms ✔  (threshold: 500ms)

Next evaluation: 4 minutes

Step 4—Increase the canary weight¶

When the canary metrics are healthy, increase the traffic percentage:

stctl canary set-weight \
  --env dev \
  --service remote-access-service \
  --weight 50

Repeat in increments: 10% → 50% → 100%. The recommended progression is:

Weight	Duration before next increase
10%	15 minutes
50%	30 minutes
100%	Canary promoted to stable

Step 5—Promote the canary to stable¶

When you are confident the canary is healthy at 100%:

stctl canary promote --env dev --service remote-access-service

This command:

Sets all traffic to v1.2.0
Removes the v1.1.0 stable deployment
Updates the SSD to remove the canary block

Step 6—Halt the canary if metrics degrade¶

If the canary error rate or latency exceeds the thresholds, halt it immediately:

stctl canary halt --env dev --service remote-access-service

This routes all traffic back to the stable version (v1.1.0) and stops the canary deployment. Investigate the issue before re-attempting.

Validation¶

The canary deployment is healthy when:

Check	Command	Expected
Both versions running	`stctl pods --env dev --service remote-access-service`	One stable pod, one canary pod
Canary metrics healthy	`stctl canary status --env dev --service remote-access-service`	All metrics within threshold
Traffic split active	Same command	Percentages match configured weight

Troubleshooting¶

canary: enabled: feature not available during SSD validation

Canary deployments require 'Istio' to be installed in your 'namespace'. Contact your Platform Engineer to confirm 'Istio' is enabled for your team's 'namespace'.

Canary automatically halted¶

The metrics thresholds were exceeded. View the canary analysis logs:

stctl canary logs --env dev --service remote-access-service

Then view service logs to find the root cause:

stctl logs --env dev --service remote-access-service --version canary --since 30m