Skip to content

Commit

Permalink
docs: added quick start guide
Browse files Browse the repository at this point in the history
Signed-off-by: Kostis Kapelonis <[email protected]>
  • Loading branch information
kostis-codefresh committed Feb 28, 2024
1 parent ae5911b commit 1fa998d
Show file tree
Hide file tree
Showing 2 changed files with 311 additions and 0 deletions.
310 changes: 310 additions & 0 deletions docs/quick-start.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,310 @@
# 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/).
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 1fa998d

Please sign in to comment.