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!

Prerequisites

If you want to get started with canary rollouts on your own environment, you will need to have Edge Stack version 2.0.4 or greater or Emissary-ingress 2.0.4 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):

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:

3. Create a manifests folder in your repository

Inside of your repository, you will need a specific directory in which your manifests will live. If you don't already have one, create a directory called manifests. Inside of it add your existing services manifest files that you want to be able to use with Canary Releases, (for example, add a service.yaml file).

An example repository can be found here. 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:

4. Apply the manifests in your cluster

From the root of your locally forked rollouts-demo repository, update the a8r.io/repository annotation from git@github.com:datawire/rollouts-demo.git to git@gthub.com:<org>/<repo>.git, then apply the Kubernetes manifests to your cluster with the command:

5. Configure your repository and container registry

In order to configure the repository and the container registry to use with rollouts, you ned to go to your team settings and click on the Integrations button.

5.1 GitHub

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 Cloud. 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.

5.2 DockerHub

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.

5.3 GitLab

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 it. 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 where 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:

• Canary concepts: Learn more about canary rollouts and Argo
• Canary rollouts and observability: Explore how observability is a prerequisite of effective canary releases.
• Ambassador Cloud Rollouts reference: Dive into the details of Argo configurations and Ambassador Cloud rollouts annotations.