From 596a4cd4c5749adf7ffd3ff75a9b6f80aff999b9 Mon Sep 17 00:00:00 2001 From: Ashwin Venkatesh Date: Mon, 24 Jun 2024 19:32:52 -0400 Subject: [PATCH] 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 * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Update docs based on feedback * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * 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 Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: Michael Wilkerson <62034708+wilkermichael@users.noreply.github.com> --- .../argo-rollouts-configuration.mdx | 262 ++++++++++++++++++ website/data/docs-nav-data.json | 4 + 2 files changed, 266 insertions(+) create mode 100644 website/content/docs/k8s/deployment-configurations/argo-rollouts-configuration.mdx diff --git a/website/content/docs/k8s/deployment-configurations/argo-rollouts-configuration.mdx b/website/content/docs/k8s/deployment-configurations/argo-rollouts-configuration.mdx new file mode 100644 index 0000000000..5bd2a1e44d --- /dev/null +++ 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 index 6f44bfd983..38126b547e 100644 --- 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": [