Canary Release With Traefik: A Step-by-Step Guide

Dec 2, 2025 by Alex Johnson 50 views

In the realm of software deployment, managing risk and ensuring smooth transitions are paramount. A canary release strategy offers a powerful way to mitigate these risks by gradually rolling out new versions of an application to a subset of users before a full-scale deployment. This approach allows for real-world testing and validation, minimizing potential disruptions and providing a safety net for unexpected issues. This article provides a comprehensive guide to implementing canary releases using Traefik weighted routing, a robust and versatile edge router that simplifies the process of managing traffic distribution.

Prerequisites

Before diving into the implementation, ensure that you have a working ingress configuration. This is a fundamental requirement for directing external traffic to your services within the cluster. If you haven't already configured ingress, refer to the relevant documentation or guides for your chosen Kubernetes environment. Setting up ingress correctly is crucial for Traefik to effectively manage and route traffic based on the defined weights and rules.

Tasks

The implementation of a canary release strategy with Traefik involves several key tasks, each contributing to the overall functionality and robustness of the deployment process. These tasks include defining the routing rules, creating the canary service, configuring the gateway chart, and establishing workflows for promotion and rollback. By meticulously addressing each task, you can ensure a seamless and controlled deployment process.

1. Create `templates/canary-ingressroute.yaml` with Weighted Services

The heart of the canary release strategy lies in the ability to selectively route traffic to different versions of the application. This is achieved through weighted services, where traffic is distributed based on predefined proportions. The canary-ingressroute.yaml file serves as the blueprint for defining these routing rules. It specifies the services that will receive traffic, along with their respective weights. For instance, you might start with a configuration that directs 5% of traffic to the canary deployment and the remaining 95% to the stable version. This file leverages Traefik's IngressRoute resource, which provides a declarative way to define routing configurations. The weights can be adjusted dynamically to gradually shift traffic to the canary deployment as confidence in the new version grows.

In this file, you'll define the rules that govern how traffic is split between the stable and canary versions of your application. Traefik's weighted services feature allows you to specify the percentage of traffic that should be routed to each version. For example, you might start by directing 5% of traffic to the canary deployment and 95% to the stable version. This allows you to test the new version with a small subset of users before rolling it out more broadly.

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: shopifake-ingressroute
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`shopifake.example.com`)
      kind: Rule
      services:
        - name: shopifake-stable-service
          port: 80
          weight: 95
        - name: shopifake-canary-service
          port: 80
          weight: 5
  tls:
    secretName: shopifake-tls

This example demonstrates a basic IngressRoute configuration that splits traffic between two services: shopifake-stable-service and shopifake-canary-service. The weight parameter determines the percentage of traffic that each service receives. In this case, 95% of traffic is routed to the stable service, while 5% is routed to the canary service.

2. Create `templates/canary-service.yaml` for Canary Deployment

To effectively manage the canary deployment, a dedicated service is required. The canary-service.yaml file defines this service, which acts as a gateway to the canary version of the application. This service will typically point to a different set of pods or deployments than the stable service, allowing for independent scaling and management. The canary service is crucial for isolating the canary deployment and ensuring that traffic is routed correctly. It enables you to monitor the performance and stability of the new version without impacting the overall stability of the application.

The canary service is a crucial component of the canary release strategy. It acts as a separate endpoint for the canary deployment, allowing you to direct traffic specifically to the new version of your application. This isolation is essential for monitoring the canary deployment's performance and stability without impacting the stable version.

apiVersion: v1
kind: Service
metadata:
  name: shopifake-canary-service
spec:
  selector:
    app: shopifake
    version: canary
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080

This example defines a service named shopifake-canary-service that targets pods with the labels app: shopifake and version: canary. This ensures that traffic routed to the canary service is directed to the canary deployment. The targetPort specifies the port on which the canary application is listening.

3. Add Canary Values to Gateway Chart (`canary.enabled`, `canary.weight`)

To streamline the deployment process and make it more configurable, it's beneficial to introduce canary-specific values into the gateway chart. This involves adding parameters such as canary.enabled and canary.weight to the chart's values file. The canary.enabled flag allows you to easily toggle the canary deployment on or off, while the canary.weight parameter controls the percentage of traffic directed to the canary version. By incorporating these values, you can dynamically adjust the canary deployment strategy without modifying the underlying templates. This approach promotes flexibility and simplifies the management of canary releases.

Integrating canary values into the gateway chart provides a convenient way to manage the canary deployment's configuration. By adding parameters like canary.enabled and canary.weight, you can easily control whether the canary deployment is active and the percentage of traffic it receives.

canary:
  enabled: true
  weight: 5

This snippet demonstrates how to add canary values to the gateway chart's values.yaml file. The canary.enabled flag enables or disables the canary deployment, while the canary.weight parameter specifies the initial traffic percentage for the canary version.

4. Create `merge-prod-promote.yml` Workflow for Progressive Promotion (5% → 20% → 50% → 100%)

The progressive promotion of a canary release is a critical aspect of the strategy. It involves gradually increasing the traffic directed to the canary deployment as confidence in the new version grows. This can be automated using a workflow, such as the merge-prod-promote.yml file. This workflow defines the steps involved in promoting the canary release, typically starting with a small percentage of traffic (e.g., 5%) and incrementally increasing it in stages (e.g., 20%, 50%, 100%). Each stage should be accompanied by smoke tests and health checks to ensure the stability and performance of the canary deployment. If any issues are detected, the workflow should be designed to automatically roll back the changes.

A well-defined workflow is essential for the progressive promotion of the canary release. The merge-prod-promote.yml workflow automates the process of gradually increasing traffic to the canary deployment, ensuring a smooth transition and minimizing potential disruptions.

This workflow should define the steps involved in promoting the canary release, including:

Increasing traffic weight: Incrementally increasing the canary.weight value in the gateway chart.
Running smoke tests: Executing automated tests to verify the basic functionality of the canary deployment.
Monitoring health checks: Observing the health of the canary pods and services to detect any issues.
Automatic rollback: Implementing a mechanism to automatically revert to the previous version if health checks fail or smoke tests indicate problems.

The workflow might look something like this:

name: Promote Canary Release

on:
  push:
    branches:
      - main
    paths:
      - 'charts/gateway/values.yaml'

jobs:
  promote:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install Helm
        uses: azure/setup-helm@v3
        with:
          version: v3.10.0

      - name: Configure Kubernetes credentials
        uses: azure/k8s-set-context@v3
        with:
          method: kubeconfig
          kubeconfig: ${{ secrets.KUBE_CONFIG }}

      - name: Increment canary weight (5% -> 20%)
        run: |
          helm upgrade gateway charts/gateway \
            --set canary.weight=20

      - name: Run smoke tests
        run: |
          # Execute smoke tests here
          echo "Running smoke tests..."

      - name: Monitor health checks
        run: |
          # Monitor health checks here
          echo "Monitoring health checks..."

      # Add similar steps for 20% -> 50% and 50% -> 100% promotion

      - name: Finalize promotion (100%)
        run: |
          helm upgrade gateway charts/gateway \
            --set canary.enabled=false # Disable canary deployment

This is a simplified example, and the actual workflow may need to be tailored to your specific requirements and infrastructure.

5. Update `workflow-prod-post-merge.yml` to Use Canary Strategy

Finally, the existing production deployment workflow, typically represented by the workflow-prod-post-merge.yml file, needs to be updated to incorporate the canary release strategy. This involves modifying the workflow to trigger the canary deployment process whenever changes are merged into the main branch. The workflow should also include steps to monitor the canary deployment, run smoke tests, and automatically roll back if necessary. By integrating the canary release strategy into the production deployment workflow, you can ensure that all new deployments are subject to the controlled rollout process.

Integrating the canary release strategy into the production deployment workflow ensures that all new deployments undergo the progressive rollout process. This helps to minimize risk and ensures that any issues are detected early on.

The workflow-prod-post-merge.yml file should be updated to:

Trigger the canary deployment: When changes are merged into the main branch, the workflow should initiate the canary deployment process.
Monitor the canary deployment: The workflow should include steps to monitor the health and performance of the canary deployment.
Run smoke tests: Automated tests should be executed to verify the basic functionality of the canary version.
Rollback on failure: If health checks fail or smoke tests indicate problems, the workflow should automatically roll back to the previous version.

The updated workflow might include steps to:

Deploy the canary service and IngressRoute.
Set the initial canary weight.
Trigger the merge-prod-promote.yml workflow to progressively promote the canary release.
Monitor the overall health of the application and roll back if necessary.

Acceptance Criteria

The success of the canary release implementation can be measured against several key acceptance criteria. These criteria ensure that the strategy is functioning as intended and that the deployment process is robust and reliable.

1. New Deployments Start at 5% Traffic

This criterion verifies that the canary deployment is correctly initialized with a small percentage of traffic. This initial low traffic volume allows for early detection of issues without significantly impacting the user experience. Starting at 5% traffic provides a controlled environment for the canary deployment to be tested and validated.

2. Smoke Tests Validate Canary Before Promotion

Smoke tests are a crucial part of the canary release process. They provide a quick and automated way to verify the basic functionality of the canary deployment before it is exposed to more traffic. This criterion ensures that smoke tests are executed and that the canary deployment passes these tests before any promotion occurs. Smoke tests act as a gatekeeper, preventing problematic versions from being rolled out to a larger audience.

3. Automatic Rollback if Health Checks Fail

Automatic rollback is a critical safety mechanism in the canary release strategy. If health checks indicate that the canary deployment is unhealthy or unstable, the system should automatically revert to the previous stable version. This criterion ensures that the rollback mechanism is functioning correctly and that the application can gracefully recover from failures. Automatic rollback minimizes the impact of faulty deployments and prevents prolonged outages.

4. Full Promotion to 100% After Validation

The ultimate goal of the canary release is to fully promote the new version to 100% of traffic once it has been thoroughly validated. This criterion ensures that the promotion process is completed successfully and that the new version is serving all users. Full promotion signifies that the canary release has been successful and that the new version is ready for general use.

Conclusion

Implementing a canary release strategy with Traefik weighted routing offers a robust and efficient way to manage software deployments. By gradually rolling out new versions to a subset of users, you can minimize risk, validate changes in a real-world environment, and ensure a smooth transition. The steps outlined in this guide provide a comprehensive framework for implementing a canary release strategy, from configuring the routing rules to automating the promotion and rollback processes. By adhering to these best practices, you can confidently deploy new versions of your application with minimal disruption and maximum confidence.

For more in-depth information on Traefik and its features, consider exploring the official Traefik documentation. This resource provides a wealth of information on configuring and utilizing Traefik for various deployment scenarios.