docs: rework documentation and getting started guide (argoproj#535)

34fathombelow · Jun 24, 2020 · 3a795f5 · 3a795f5
1 parent 7a5cd4f
commit 3a795f5
Show file tree

Hide file tree

Showing 30 changed files with 828 additions and 173 deletions.
diff --git a/Makefile b/Makefile
@@ -126,7 +126,16 @@ precheckin: test lint
 
 .PHONY: release-docs
 release-docs: plugin-docs
-	mkdocs gh-deploy -r ${GIT_REMOTE_REPO}
+	docker run --rm -it \
+		-v ~/.ssh:/root/.ssh \
+		-v ${CURRENT_DIR}:/docs \
+		-v ~/.gitconfig:/root/.gitconfig \
+		squidfunk/mkdocs-material gh-deploy -r ${GIT_REMOTE_REPO}
+
+# convenience target to run `mkdocs serve` using a docker container
+.PHONY: serve-docs
+serve-docs:
+	docker run --rm -it -p 8000:8000 -v ${CURRENT_DIR}:/docs squidfunk/mkdocs-material serve -a 0.0.0.0:8000
 
 .PHONY: release-precheck
 release-precheck: manifests

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -118,16 +118,17 @@ associated repos have to pinned to the correct version specified by the kubernet
 `./hack/update-k8s-dependencies.sh` updates all the dependencies to the those correct versions.
 
 ## Documentation Changes
-If you need to run the mkdocs server, you will need to do the following:
 
-* Follow the instruction guide to install [mkDocs](https://www.mkdocs.org/#installation)
-* Install the `material` theme with the [following guide](https://squidfunk.github.io/mkdocs-material/#quick-start)
-* Run `make plugin-docs` to generate kubectl plugin documentation
+Modify contents in `docs/` directory. 
 
-Afterwards, you can run `mkdocs serve` and access your documentation at [http://127.0.0.1:8000/](http://127.0.0.1:8000/)
+Preview changes in your browser by visiting http://localhost:8000 after running:
 
-If you don't want to setup mkDocs locally, the following docker command should suffice:
+```shell
+make serve-docs
+```
+
+To publish changes, run:
 
 ```shell
-docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+make release-docs
 ```
diff --git a/docs/concepts.md b/docs/concepts.md
@@ -0,0 +1,42 @@
+# Concepts
+
+## Rollout
+
+A Rollout is Kubernetes workload resource which is equivalent to a Kubernetes Deployment object.
+It is intended to replace a Deployment object in scenarios when more advanced deployment or 
+progressive delivery functionality is needed. A Rollout provides the following features which
+a Kubernetes Deployment cannot:
+
+* blue-green deployments
+* canary deployments
+* integration with ingress controllers and service meshes for advanced traffic routing
+* integration with metric providers for blue-green & canary analysis
+* automated promotion or rollback based on successful or failed metrics
+
+## Progressive Delivery
+
+Progressive delivery is the process of releasing updates of a product in a controlled and gradual
+manner, thereby reducing the risk of the release, typically coupling automation and metric analysis
+to drive the automated promotion or rollback of the update. 
+
+Progressive delivery is often described as an evolution of continuous delivery, extending the
+speed benefits made in CI/CD to the deployment proccess. This is accomplished by limiting the
+exposure of the new version to a subset of users, observing and analysing for correct behavior, 
+then  progressively increassing the exposure to a broader and wider audience while continuosly
+verifing correctness.
+
+## Deployment Strategies
+
+While the industry has used a consistent terminology to describe various deployment strategies, the implementations of these strategies tend to differ across tooling. To make it clear how the Argo Rollouts will behave, here are the descriptions of the various deployment strategies implementations offered by the Argo Rollouts.
+
+### Rolling Update
+A `RollingUpdate` slowly replaces the old version with the new version. As the new version comes up, the old version is scaled down in order to maintain the overall count of the application. This is the default strategy of the Deployment object.
+
+### Recreate
+A Recreate deployment deletes the old version of the application before bring up the new version. As a result, this ensures that two versions of the application never run at the same time, but there is downtime during the deployment.
+
+### Blue-Green
+A Blue-Green deployment (sometimes referred to as a Red-Black) has both the new and old version of the application deployed at the same time.  During this time, only the old version of the application will receive production traffic. This allows the developers to run tests against the new version before switching the live traffic to the new version.
+
+### Canary
+A Canary deployment exposes a subset of users to the new version of the application while serving the rest of the traffic to the old version. Once the new version is verified to be correct, the new version can gradually replace the old version. Ingress controllers and service meshes such as NGINX and Istio, enable more sophisticated traffic shaping patterns for canarying than what is natively available (e.g. achieving very fine-grained traffic splitting, or splitting based on HTTP headers).
diff --git a/docs/deployment-concepts.md b/docs/deployment-concepts.md
diff --git a/docs/features/kubectl-plugin.md b/docs/features/kubectl-plugin.md
@@ -5,36 +5,7 @@ Argo Rollouts offers a Kubectl plugin to enrich the experience with Rollouts, Ex
 
 ## Installation
 
-### Manual
-1. Install [Argo Rollouts Kubectl plugin](https://github.com/argoproj/argo-rollouts/releases) with curl.
-    ```shell
-    curl -LO https://github.com/argoproj/argo-rollouts/releases/latest/download/kubectl-argo-rollouts-darwin-amd64
-    ```
-
-    !!! tip "" 
-        For Linux dist, replace `darwin` with `linux`
-
-1. Make the kubectl-argo-rollouts binary executable.
-
-    ```shell
-    chmod +x ./kubectl-argo-rollouts-darwin-amd64
-    ```
-
-1. Move the binary into your PATH.
-
-    ```shell
-    sudo mv ./kubectl-argo-rollouts-darwin-amd64 /usr/local/bin/kubectl-argo-rollouts
-    ```
-
-Test to ensure the version you installed is up-to-date:
-
-```shell
-kubectl argo rollouts version
-```
-
-### Krew
-
-Currently not supported, but there are plans to make the Argo Rollouts kubectl a part of [Krew](https://github.com/kubernetes-sigs/krew). Please follow this [issue](https://github.com/argoproj/argo-rollouts/issues/294) for the most up-to-date information.
+See the [installation guide](../installation.md) for instructions on installing the plugin.
 
 ## Usage
 The best way to get information on the available Argo Rollouts kubectl plugin commands is by run `kubectl argo rollouts`. The plugin lists all the available commands that the tool can execute along with a description of each commend. All the plugin's commands interact with the Kubernetes API server and use KubeConfig credentials for authentication. Since the plugin leverages the KubeConfig of the user running the command, the plugin has the permissions of those configs. 

diff --git a/docs/features/index.md → docs/features/specification.md b/docs/features/index.md → docs/features/specification.md
@@ -1,9 +1,4 @@
-# Overview
-
-The Rollout object has two available strategies: Canary and BlueGreen. Below are the links to the documenation for each strategy:
-
-1. [Blue Green](bluegreen.md)
-1. [Canary](canary.md)
+# Rollout Specification
 
 The following describes all the available fields of a rollout:
 
@@ -13,9 +8,11 @@ kind: Rollout
 metadata:
   name: example-rollout-canary
 spec:
-  # Number of desired pods. This is a pointer to distinguish between explicit zero and not specified. Defaults to 1.
+  # Number of desired pods. This is a pointer to distinguish between explicit zero and not specified.
+  # Defaults to 1.
   replicas: 5
-  # Label selector for pods. Existing ReplicaSets whose pods are selected by this will be the ones affected by this rollout. It must match the pod template's labels.`
+  # Label selector for pods. Existing ReplicaSets whose pods are selected by this will be the ones
+  # affected by this rollout. It must match the pod template's labels.
   selector:
     matchLabels:
       app: guestbook
@@ -25,29 +22,49 @@ spec:
       containers:
       - name: guestbook
         image: gcr.io/heptio-images/ks-guestbook-demo:0.1
-  # Minimum number of seconds for which a newly created pod should be ready without any of its container crashing, for it to be considered available. Defaults to 0 (pod will be considered available as soon as it is ready)
+  # Minimum number of seconds for which a newly created pod should be ready without any of its
+  # container crashing, for it to be considered available.
+  # Defaults to 0 (pod will be considered available as soon as it is ready)
   minReadySeconds: 30
-  # The number of old ReplicaSets to retain. If unspecified, will retain 10 old ReplicaSets
+  # The number of old ReplicaSets to retain.
+  # Defaults to 10
   revisionHistoryLimit: 3
-  # Indiciates if the rollout is paused
-  paused: false
-  # The maximum time in seconds for a rollout to make progress before it is considered to be failed. Argo Rollouts will continue to process failed rollouts and a condition with a ProgressDeadlineExceeded reason will be surfaced in the rollout status. Note that progress will not be estimated during the time a rollout is paused. Defaults to 600s.
+  # Pause allows a user to manually pause a rollout at any time. A rollout will not advance through
+  # its steps while it is manually paused, but HPA auto-scaling will still occur.
+  paused: true
+  # The maximum time in seconds in which a rollout must make progress during an update, before it is
+  # considered to be failed. Argo Rollouts will continue to process failed rollouts and a condition
+  # with a ProgressDeadlineExceeded reason will be surfaced in the rollout status. Note that
+  # progress will not be estimated during the time a rollout is paused.
+  # Defaults to 600s
   progressDeadlineSeconds: 600
-  # Field to specify the strategy to run
+  # UTC timestamp in which a Rollout should sequentially restart all of its pods. Used by the
+  # `kubectl argo rollouts restart ROLLOUT` command. The controller will ensure all pods have a
+  # creationTimestamp greater than or equal to this value.
+  restartAt: "2020-03-30T21:19:35Z"
+  # Deployment strategy to use during updates
   strategy:
     blueGreen:
       # Name of the service that the rollout modifies as the active service.
       activeService: active-service
-      # Pre-promotion analysis run
+      # Pre-promotion analysis run which performs analysis before the service cutover. +optional
       prePromotionAnalysis:
         templates:
         - templateName: success-rate
         # template arguments
         args:
         - name: service-name
           value: guestbook-svc.default.svc.cluster.local
-      # Name of the service that the rollout modifies as the preview service.
-      previewService: preview-service 
+      # Pre-promotion analysis run which performs analysis after the service cutover. +optional
+      postPromotionAnalysis:
+        templates:
+        - templateName: success-rate
+        # template arguments
+        args:
+        - name: service-name
+          value: guestbook-svc.default.svc.cluster.local
+      # Name of the service that the rollout modifies as the preview service. +optional
+      previewService: preview-service
       # The number of replicas to run under the preview service before the switchover. Once the rollout is resumed the new replicaset will be full scaled up before the switch occurs +optional
       previewReplicaCount: 1
       # Indicates if the rollout should automatically promote the new ReplicaSet to the active service or enter a paused state. If not specified, the default value is true. +optional
@@ -58,6 +75,11 @@ spec:
       scaleDownDelaySeconds: 30
       # Limits the number of old RS that can run at once before getting scaled down. Defaults to nil
       scaleDownDelayRevisionLimit: 2
+      # Anti Affinity configuration between desired and previous replicaset. Only one must be specified
+      antiAffinity:
+        requiredDuringSchedulingIgnoredDuringExecution: {}
+        preferredDuringSchedulingIgnoredDuringExecution:
+          weight: 1 # Between 1 - 100
     canary:
       # CanaryService holds the name of a service which selects pods with canary version and don't select any pods with stable version. +optional
       canaryService: canary-service
@@ -84,7 +106,39 @@ spec:
           duration: 1h # One hour
       - setWeight: 40
         # Sets .spec.paused to true and waits until the field is changed back
-      - pause: {} 
+      - pause: {}
+      # Anti Affinity configuration between desired and previous replicaset. Only one must be specified
+      antiAffinity:
+        requiredDuringSchedulingIgnoredDuringExecution: {}
+        preferredDuringSchedulingIgnoredDuringExecution:
+          weight: 1 # Between 1 - 100
+      # Traffic routing specifies ingress controller or service mesh configuration to achieve
+      # advanced traffic splitting. If omitted, will achieve traffic split via a weighted
+      # replica counts between the canary and stable ReplicaSet.
+      trafficRouting:
+        # Istio traffic routing configuration
+        istio:
+          virtualService: 
+            name: rollout-vsvc  # required
+            routes:
+            - primary # At least one route is required
+        # NGINX Ingress Controller routing configuration
+        nginx:
+          stableIngress: primary-ingress  # required
+          annotationPrefix: customingress.nginx.ingress.kubernetes.io # optional
+          additionalIngressAnnotations:   # optional
+            canary-by-header: X-Canary
+            canary-by-header-value: iwantsit
+        # ALB Ingress Controller routing configuration
+        alb:
+           ingress: ingress  # required
+           servicePort: 443  # required
+           annotationPrefix: custom.alb.ingress.kubernetes.io # optional
+        # Service Mesh Interface routing configuration
+        smi:
+         rootService: root-svc # optional
+         trafficSplitName: rollout-example-traffic-split # optional
+
 status:
   pauseConditions:
   - reason: StepPause

diff --git a/docs/features/traffic-management/nginx.md b/docs/features/traffic-management/nginx.md
@@ -20,15 +20,15 @@ spec:
   ...
   strategy:
     canary:
-      canaryService: canary-service # required
+      canaryService: canary-service  # required
       stableService: stable-service  # required
       trafficRouting:
         nginx:
-           stableIngress: primary-ingress  # required
-           annotationPrefix: customingress.nginx.ingress.kubernetes.io # optional
-           additionalIngressAnnotations: #optional
-             canary-by-header: X-Canary
-             canary-by-header-value: iwantsit
+          stableIngress: primary-ingress  # required
+          annotationPrefix: customingress.nginx.ingress.kubernetes.io # optional
+          additionalIngressAnnotations:   # optional
+            canary-by-header: X-Canary
+            canary-by-header-value: iwantsit
 ```
 
 The stable Ingress field is a reference to an Ingress in the same namespace of the Rollout. The Rollout requires the primary Ingress routes traffic to the stable Service. The Rollout checks that condition by confirming the Ingress has a backend that matches the Rollout's stableService.