---
layout: docs
page_title: Argo Rollouts Progressive Delivery with Consul on Kubernetes
description: >-
  Configure the Argo Rollouts Controller to enable Canary deployments for subset-based routing. Learn how k8s Rollouts integrate with Consul's service mesh.
---

# Argo Rollouts Progressive Delivery with Consul on Kubernetes

This page describes the process to configure and use the [Argo Rollouts Controller](https://argo-rollouts.readthedocs.io/en/stable/) with Consul on Kubernetes to manage advanced subset-based routing for Canary deployments.

Consul's support for Argo Rollouts is currently limited to subset-based routing.

## Install Argo Rollouts Controller

There are three methods for installing the Argo Rollouts Controller with Consul on Kubernetes:

1. [Install Rollouts Using Helm and init containers](#install-rollouts-using-helm-and-binary). We recommend installing the Argo Rollouts Controllor using this method.
1. [Install Rollouts Using Helm and binary](#install-rollouts-using-helm-and-binary)
1. [Standalone installation](#stand-alone-installation)

After installing the controller, you must [apply the RBAC CRD](https://raw.githubusercontent.com/argoproj-labs/rollouts-plugin-trafficrouter-consul/main/yaml/rbac.yaml) to your Kubernetes cluster.

### Install Rollouts Using Helm and init containers

We recommend using this method to install this plugin.

Add the following code to your `values.yaml` file to configure the plugin:

```yaml
controller:
  initContainers:
    - name: copy-consul-plugin
      image: hashicorp/rollouts-plugin-trafficrouter-consul
      command: ["/bin/sh", "-c"]
      args:
        # Copy the binary from the image to the rollout container
        - cp /bin/rollouts-plugin-trafficrouter-consul /plugin-bin/hashicorp
      volumeMounts:
        - name: consul-plugin
          mountPath: /plugin-bin/hashicorp
  trafficRouterPlugins:
    trafficRouterPlugins: |-
      - name: "hashicorp/consul"
        location: "file:///plugin-bin/hashicorp/rollouts-plugin-trafficrouter-consul"
  volumes:
    - name: consul-plugin
      emptyDir: {}
  volumeMounts:
    - name: consul-plugin
      mountPath: /plugin-bin/hashicorp
```

Then install the `argo-rollouts` and apply your updated values using Helm:

```shell-session
$ helm install argo-rollouts argo/argo-rollouts -f values.yaml -n argo-rollouts
```

### Install Rollouts Using Helm and binary

To build the binary and install Rollouts, complete the following steps:

1. Build this plugin using your preferred tool. For example, `make build`.
1. Mount the built plugin onto the `argo-rollouts` container.
1. Add the following code to your `values.yaml` file to configure the plugin:

```yaml
controller:
  trafficRouterPlugins:
    trafficRouterPlugins: |-
      - name: "argoproj-labs/consul"
        location: "file:///plugin-bin/hashicorp/rollouts-plugin-trafficrouter-consul"
  volumes:
    - name: consul-route-plugin
      hostPath:
        # The path being mounted to, change this depending on your mount path
        path: /rollouts-plugin-trafficrouter-consul
        type: DirectoryOrCreate
  volumeMounts:
    - name: consul-route-plugin
      mountPath: /plugin-bin/hashicorp
```

Then install the `argo-rollouts` and apply your updated values using Helm:

```shell-session
  $ helm install argo-rollouts argo/argo-rollouts -f values.yaml -n argo-rollouts
```

### Stand-alone installation

This section describes the process to create a stand-alone installation. These instructions are for illustrative purposes. We recommend using init containers to create and install this plugin.

To create a stand-alone installation of the Rollouts plugin, complete the following steps:

1. Build this plugin.
1. Put the plugin on the path and mount it to the `argo-rollouts`container.
1. Create a `ConfigMap` to configure `argo-rollouts` with the plugin's location.

The following example schedules a Deployment and mounts it to the `argo-rollouts` container:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: argo-rollouts
  namespace: argo-rollouts
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: argo-rollouts
  template:
    spec:
      # ...
      volumes:
        # ...
         - name: consul-plugin
           hostPath:
             path: /plugin-bin/hashicorp/rollouts-plugin-trafficrouter-consul
             type: DirectoryOrCreate
      containers:
        - name: argo-rollouts
        # ...
          volumeMounts:
             - name: consul-route-plugin
               mountPath: /plugin-bin/hashicorp

```

The following example creates the `ConfigMap` with the location of the plugin:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: argo-rollouts-config
  namespace: argo-rollouts
data:
  trafficRouterPlugins: |-
    - name: "argoproj-labs/consul"
      location: "file:///plugin-bin/hashicorp/rollouts-plugin-trafficrouter-consul"
binaryData: {}
```

### Install the RBAC

After either mounting the binary or using an init container, configure an RBAC using [Argo Rollout Consul plugin `rbac.yaml`](https://raw.githubusercontent.com/argoproj-labs/rollouts-plugin-trafficrouter-consul/main/yaml/rbac.yaml):

```shell-session
$ kubectl apply -f https://raw.githubusercontent.com/argoproj-labs/rollouts-plugin-trafficrouter-consul/main/yaml/rbac.yaml
```

## Use the Argo Rollouts Consul plugin

Schedule the Kubernetes Service utilized by the service being rolled out. Additionally, configure any service defaults and proxy defaults required for the service.

```yaml
apiVersion: v1
kind: Service
metadata:
  name: test-service
spec:
  selector:
    app: test-service
  ports:
    - name: http
      port: 80
      targetPort: 8080
```

Next, create the service resolver and service splitter CRDs for your stable service. Argo automatically modifies these CRDs during canary deployments.

The following example demonstrates the configuration of the service resolver CRD, which creates service subsets and sets the stable subset as the default:

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: test-service
spec:
  subsets:
    stable:
      filter: Service.Meta.version == 1
    canary:
      filter: ""
  defaultSubset: stable
```

The following example demonstrates the configuration of the service splitter CRD, which initially sends 100% of traffic to the stable deployment:

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceSplitter
metadata:
  name: test-service
spec:
  splits:
    - weight: 100
      serviceSubset: stable
    - weight: 0
      serviceSubset: canary
```

Then configure your Argo Rollout resource to incrementally rollout the canary deployment:

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: test-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: test-service
  template:
    metadata:
      labels:
        app: test-service
      annotations:
        consul.hashicorp.com/connect-inject: "true"
        consul.hashicorp.com/service-meta-version: "1"
        consul.hashicorp.com/service-tags: "v1"
    spec:
      containers:
        - name: test-service
          # Using alpine vs latest as there is a build issue with M1s. Also other tests in multiport-app reference
          # alpine so standardizing this.
          image: docker.mirror.hashicorp.services/hashicorp/http-echo:alpine
          args:
            - -text="I am v1"
            - -listen=:8080
          ports:
            - containerPort: 8080
              name: http
      serviceAccountName: test-service
      terminationGracePeriodSeconds: 0 # so deletion is quick
  strategy:
    canary:
      trafficRouting:
        plugins:
          hashicorp/consul:
            stableSubsetName: stable # subset name of the stable service
            canarySubsetName: canary # subset name of the canary service
            serviceName: test-service
      steps:
      - setWeight: 20
      - pause: {}
      - setWeight: 40
      - pause: {duration: 10}
      - setWeight: 60
      - pause: {duration: 10}
      - setWeight: 80
      - pause: {duration: 10}
```

Finally, perform the Rollout operation using the Argo Rollouts Kubectl plugin.

```shell-session
$ kubectl argo rollouts promote test-service
```