7 min • read

Configure Canary Rollout in your Cluster

In this guide we'll give you everything you need to perform a canary rollout in your own cluster using GitOps best practices, but without needing to write lots of YAML!



If you want to get started with canary rollouts on your own environment, you will need to have Edge Stack version 1.12 or greater or Emissary-ingress 1.13 or greater installed in your cluster.

Install Edge Stack from here if needed.

If you already have Edge Stack or Emissary-ingress installed, check your version by running this command (adjust your namespace if necessary):

kubectl get deploy --namespace ambassador ambassador -o jsonpath='{.spec.template.spec.containers[0].image}'

Upgrade Edge Stack to the latest version if needed.

1. Connect your cluster to Ambassador Cloud

  1. Log in to Ambassador Cloud with your preferred identity provider.

  2. At the top, click Add Services then click Connection Instructions in the Edge Stack installation section.

  3. Follow the prompts to name the cluster and click Generate a Cloud Token.

  4. Follow the prompts to install the cloud token into your cluster.

  5. When the token installation completes, refresh the Service Catalog page.

2. Install Argo CD & Argo Rollouts

In order to install Argo CD and Argo Rollouts in your cluster run the commands below:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl create namespace argo-rollouts
kubectl apply -n argo-rollouts -f https://github.com/argoproj/argo-rollouts/releases/latest/download/install.yaml

3. Get a manifests folder in your repository

Inside of your repository, you will need a specific directory in which your manifests will live. If you still don't have any, create a directory called manifests, and inside of it add your existing services manifests files that you want to be able to use with Canary Releases, (for example, add a service.yaml file). Otherwise, use the path of your existing folder that contains the manifests, relative to the root of your repository, in the a8r.io/rollouts/scm.path annotation.

The annotations section of your service.yaml file should look something like the following:

app: rollout-demo
name: rollout-demo
a8r.io/description: Demo service to try the rollout feature
a8r.io/owner: Ambassador Labs
a8r.io/documentation: https://www.getambassador.io/docs/cloud/latest/service-catalog/howtos/rollout/
a8r.io/repository: git@github.com:datawire/rollouts-demo.git
a8r.io/support: https://a8r.io/Slack
a8r.io/rollouts.scm.path: manifests
a8r.io/rollouts.scm.branch: main
a8r.io/rollouts.image-repo.type: dockerhub
a8r.io/rollouts.image-repo.name: hashicorp/http-echo
a8r.io/rollouts.deployment: rollout-demo
a8r.io/rollouts.mappings: rollout-demo-mapping

4. Apply the manifests in your cluster

From your root of your locally forked rollouts-demo repository, apply the Kubernetes manifests to your cluster:

kubectl apply -f ./manifests

5. Configure your repository and container registry


Click the Enable button in the GitHub section. You will be taken to github.com and asked in which account you want to install Ambassador DCP. Select the account in which you forked the rollouts-demo repo. On the new page that opens scroll down to the "Repository access" section, and click on Only select repositories. Then click on the dropdown menu directly below this option and select your forked rollouts-demo repo. Click Save and you will be taken back to the Ambassador Cloud integrations page.


Click the Enable button in the DockerHub section and enter your DockerHub username and an access token so that Ambassador Cloud can query for available image tags. You can generate a DockerHub access token via your hub.docker.com account security settings.


Click the Enable button in the GitLab section and enter your GitLab token. You can generate a personal access token via your GitLab Profile Settings.

6. Configure Argo CD

From the Ambassador Cloud Service Catalog page, look for the service you want to Rollout and click on its card. The Heads Up Display (HUD) will show information about your service along with some actions. Click on the Rollout button to show the start rollout slideout In there, click the Configure Argo for your service option and follow the instructions. This will:

  1. Generate a deployment key in your forked repository.
  2. Configure Argo CD with that deployment key to monitor your repository.
  3. Install an Argo CD Application that represents the selected service.
  4. If you are using a GitLab repository, it will also configure a webhook in the repository.

7. Create a Rollout

Once ArgoCD has been configured in your cluster, you can click the Rollout button again to see the start rollout slideout where you can select the parameters needed to rollout your service.

Fill in the form with the following information:

  • Image Tag
  • Rollout Duration
  • Weight increment
  • Number of pods

Click on Start Rollout.

8. Review & merge

After clicking Start Rollout the slideout will close and you will be redirected to the service rollouts page where you will see one card with a badge saying Not Merged. This is your Rollout Card. Click the Pull Request or Merge Request button. A new browser tab will be opened and you will be taken to your repository where you can review and merge the Pull Request on GitHub or Merge Request on GitLab. Merge the Pull or Merge Request and go back to your service's rollouts page wher you will see in a few seconds the state of the Rollout Card changing from Not Merged to Merged.

9. Watch the Rollout progress from Ambassador Cloud

After ArgoCD has picked up the chanes, the Rollout Card's state will change to In Progress and you can see the rollout progress of your new version. Note how the Current Canary Weight progress bar increases in steps in the amount you specified above in the weight increment when creating the rollout.

What's next?

Explore some of the popular content on canary rollouts: