docs: Quick start (#45)

* docs: added pictures of quick start Signed-off-by: Kostis Kapelonis <[email protected]> * docs: added quick start guide Signed-off-by: Kostis Kapelonis <[email protected]> * docs: link quick start Signed-off-by: Kostis Kapelonis <[email protected]> --------- Signed-off-by: Kostis Kapelonis <[email protected]>
argoproj-labs · Feb 28, 2024 · 992244e · 992244e
1 parent 6eec228
commit 992244e
Show file tree

Hide file tree

Showing 7 changed files with 311 additions and 2 deletions.
diff --git a/docs/images/quick-start/canary-end.png b/docs/images/quick-start/canary-end.png
diff --git a/docs/images/quick-start/canary-in-progress.png b/docs/images/quick-start/canary-in-progress.png
diff --git a/docs/images/quick-start/canary-start.png b/docs/images/quick-start/canary-start.png
diff --git a/docs/index.md b/docs/index.md
@@ -41,7 +41,7 @@ This is the installation process.
 The first 3 steps are specific to your provider/implementation of the Gateway API inside the Kubernetes cluster. The rest of the steps are the same regardless of the specific implementation you chose.
 
 See end-to-end examples for several other implementations
-at the [provider status page](provider-status.md).
+at the [provider status page](provider-status.md) or try our [quick start guide](quick-start.md).
 
 
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -62,4 +62,4 @@ time="XXX" level=info msg="Downloading plugin argoproj-labs/gatewayAPI from: htt
 time="YYY" level=info msg="Download complete, it took 7.792426599s" 
 ```
 
-You are now ready to use the Gateway API in your [Rollout definitions](https://argoproj.github.io/argo-rollouts/features/specification/). 
+You are now ready to use the Gateway API in your [Rollout definitions](https://argoproj.github.io/argo-rollouts/features/specification/). See also our [Quick Start Guide](quick-start.md).
diff --git a/docs/quick-start.md b/docs/quick-start.md
@@ -0,0 +1,308 @@
+# Quick start for using Kubernetes API Gateway with Argo Rollouts
+
+Let's look at a quick example of how you can use Argo Rollouts
+to control your Http Routes. In this guide we will see how to use [the Rollouts demo](https://github.com/argoproj/rollouts-demo) with [Envoy Gateway](https://gateway.envoyproxy.io/) as the traffic provider.
+
+You can find more examples at the [provider status page](provider-status.md).
+
+## Prerequisites 
+
+Get access to a Kubernetes cluster. You can use a cluster on the cloud or on your workstation like [k3s](https://k3s.io/), [k3d](https://k3d.io/) or [Docker for Desktop](https://www.docker.com/products/docker-desktop/).
+
+Then make sure you also install:
+
+ 1. Argo Rollouts along [with the Gateway plugin](installation.md)
+ 1. The [helm](https://helm.sh/) and [kubectl](https://kubernetes.io/docs/tasks/tools/) executables
+ 1. The [Argo Rollouts CLI](https://argo-rollouts.readthedocs.io/en/stable/features/kubectl-plugin/)
+
+In a real production scenario, [different people](https://gateway-api.sigs.k8s.io/#personas) will build
+different parts of the solution. In this guide you will wear multiple hats, so the process might seem more complicated than it actually is.
+
+## Step 1 - Install the Gateway Provider
+
+!!! note
+    This process needs to happen only once per cluster. The task is normally handled by infrastructure operators.
+
+Install Envoy Gateway with Helm:
+
+```
+helm install eg oci://docker.io/envoyproxy/gateway-helm --version v0.5.0 -n envoy-gateway-system --create-namespace
+```
+
+Wait for it to become ready
+
+```
+kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available
+```
+
+## Step 2 - Create a gateway
+
+!!! note
+    This process needs to happen only once per cluster. The task is normally handled by infrastructure operators.
+
+Create a Gateway 
+
+```yaml
+---
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: GatewayClass
+metadata:
+  name: eg
+  namespace: default
+spec:
+  controllerName: gateway.envoyproxy.io/gatewayclass-controller
+---
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: Gateway
+metadata:
+  name: eg
+  namespace: default
+spec:
+  gatewayClassName: eg
+  listeners:
+    - name: http
+      protocol: HTTP
+      port: 80
+```      
+Apply the file with kubectl and then verify it works correctly with
+
+```
+kubectl get gatewayclass
+kubectl get gateway
+```
+
+Note down the `ADDRESS` IP to use later in the application. For a local cluster this should be `127.0.0.1`
+
+## Step 3 - Allow Argo Rollouts to edit Http Routes
+
+!!! note
+    This process needs to happen only once per cluster. The task is normally handled by infrastructure operators.
+
+Create a role and binding.
+
+```yaml
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: gateway-controller-role
+  namespace: argo-rollouts
+rules:
+  - apiGroups:
+      - "*"
+    resources:
+      - "*"
+    verbs:
+      - "*"
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: gateway-admin
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: gateway-controller-role
+subjects:
+  - namespace: argo-rollouts
+    kind: ServiceAccount
+    name: argo-rollouts
+```  
+
+Apply the file with kubectl. Note that this role is **NOT** to be used in production clusters as it is super permissive.
+
+
+## Step 4 - Create an HTTP route 
+
+!!! note
+    This process needs to happen only once per application. The task is normally handled by cluster operators or application developers.
+
+Create a route that has as backend two services (stable and canary)
+
+```yaml
+---
+kind: HTTPRoute
+apiVersion: gateway.networking.k8s.io/v1beta1
+metadata:
+  name: argo-rollouts-http-route
+  namespace: default
+spec:
+  parentRefs:
+    - name: eg
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /  
+    backendRefs:
+    - name: argo-rollouts-stable-service
+      kind: Service
+      port: 80
+    - name: argo-rollouts-canary-service
+      kind: Service
+      port: 80
+```
+
+Apply the file with kubectl.
+Verify it with `kubectl get httproutes`
+
+## Step 5 - Create a Rollout 
+
+!!! note
+    This process needs to happen only once per application. The task is normally handled by cluster operators or application developers.
+
+Create two Kubernetes services
+
+```yaml
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: argo-rollouts-stable-service
+  namespace: default
+spec:
+  ports:
+    - port: 80
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    app: rollouts-demo
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: argo-rollouts-canary-service
+  namespace: default
+spec:
+  ports:
+    - port: 80
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    app: rollouts-demo
+```
+
+Apply the file with kubectl.
+
+Finally create the Rollout:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Rollout
+metadata:
+  name: rollouts-demo
+  namespace: default
+spec:
+  replicas: 10
+  strategy:
+    canary:
+      canaryService: argo-rollouts-canary-service # our created canary service
+      stableService: argo-rollouts-stable-service # our created stable service
+      trafficRouting:
+        plugins:
+          argoproj-labs/gatewayAPI:
+            httpRoute: argo-rollouts-http-route # our created httproute
+            namespace: default
+      steps:
+      - setWeight: 50
+      - pause: {}
+      - setWeight: 100
+      - pause: {}
+  revisionHistoryLimit: 2
+  selector:
+    matchLabels:
+      app: rollouts-demo
+  template:
+    metadata:
+      labels:
+        app: rollouts-demo
+    spec:
+      containers:
+        - name: rollouts-demo
+          image: argoproj/rollouts-demo:blue
+          ports:
+            - name: http
+              containerPort: 8080
+              protocol: TCP
+          resources:
+            requests:
+              memory: 32Mi
+              cpu: 5m
+```
+
+Wait for the application to be ready and then visit in your browser `localhost`, or `127.0.0.1` or whatever is the IP of your Gateway.
+
+You should see that all requests return with blue color:
+
+![First deployment](images/quick-start/canary-start.png)
+
+
+## Daily Task - Perform a Canary 
+
+!!! note
+    This process happens multiple times per day/week. The task is normally handled by application developers.
+
+We are ready to deploy a new version. Open your rollout yaml change the image to `argoproj/rollouts-demo:yellow` and apply the file again with kubectl.
+
+Wait until the canary pod are ready. Run the following to see when the canary has paused.
+
+```
+kubectl argo rollouts get rollout rollouts-demo
+```
+
+At this point each color should get 50% of requests. You can see this visually in your browser:
+
+![Canary in progress](images/quick-start/canary-in-progress.png)
+
+You should also inspect the Http Route and verify that Argo Rollouts has changed the weights of the backend services
+
+Run 
+
+```
+kubectl get httproute -o yaml
+```
+
+In the response you should see the following information about the weights for each backing service.
+
+```yaml
+[...snip...]
+  spec:
+    parentRefs:
+    - group: gateway.networking.k8s.io
+      kind: Gateway
+      name: eg
+    rules:
+    - backendRefs:
+      - group: ""
+        kind: Service
+        name: argo-rollouts-stable-service
+        port: 80
+        weight: 50
+      - group: ""
+        kind: Service
+        name: argo-rollouts-canary-service
+        port: 80
+        weight: 50
+      matches:
+      - path:
+          type: PathPrefix
+          value: /
+[...snip...]
+```
+
+Promote the Rollout twice by running the following two times:
+
+```
+kubectl argo rollouts promote rollouts-demo
+```
+
+Wait a bit until the old color pods are completely destroyed.
+The application should gradually change now to yellow.
+
+![Canary finished](images/quick-start/canary-end.png)
+
+The deployment has finished. If you change the Rollout image again, the process will start over.
+
+Feel free to learn more about all Rollout options in the [Specification documentation](https://argo-rollouts.readthedocs.io/en/stable/features/specification/).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -18,6 +18,7 @@ nav:
 - Overview: index.md
 - Installation: installation.md
 - Providers: provider-status.md
+- Quick start: quick-start.md
 - Features: 
   - Advanced Deployments: features/advanced-deployments.md
   - Multiple Routes: features/multiple-routes.md