Create documentation for Argo Rollouts Plugin. (#20680)

* Create documentation for Argo Rollouts Plugin. * Create documentation for Argo Rollouts Plugin. * Apply suggestions from code review Co-authored-by: David Yu <[email protected]> * Apply suggestions from code review Co-authored-by: Jeff Boruszak <[email protected]> * Update docs based on feedback * Apply suggestions from code review Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/k8s/deployment-configurations/argo-rollouts-configuration.mdx * Update website/content/docs/k8s/deployment-configurations/argo-rollouts-configuration.mdx --------- Co-authored-by: David Yu <[email protected]> Co-authored-by: Jeff Boruszak <[email protected]> Co-authored-by: Michael Wilkerson <[email protected]>
hashicorp · Jun 24, 2024 · 596a4cd · 596a4cd
1 parent 830d1bf
commit 596a4cd
Show file tree

Hide file tree

Showing 2 changed files with 266 additions and 0 deletions.
diff --git a/website/content/docs/k8s/deployment-configurations/argo-rollouts-configuration.mdx b/website/content/docs/k8s/deployment-configurations/argo-rollouts-configuration.mdx
@@ -0,0 +1,262 @@
+---
+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
+```
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
@@ -1381,6 +1381,10 @@
             "title": "Consul Enterprise",
             "path": "k8s/deployment-configurations/consul-enterprise"
           },
+          {
+            "title": "Argo Rollouts Progressive Delivery",
+            "path": "k8s/deployment-configurations/argo-rollouts-configuration"
+          },
           {
             "title": "Multi-Cluster Federation",
             "routes": [