GitOps w/ ArgoCD a Tutorial

This is a step by step on how to get ArgoCD up and running locally on a k3s cluster, and also demonstrate a bit of what ArgoCD is capable of. This will get you up and running on a local k3s cluster, so you don't need your own existing Kubernetes cluster!

Some info before you jump in!

If you have a Kubernetes cluster already that you'd like to run ArgoCD in and have kubectl configured for it already, you can skip installing k3d and skip any k3d related steps.

If you are using a GKE cluster, there is one extra step that you must take. You will need grant your account the ability to create new cluster roles with the following command:

$ kubectl create clusterrolebinding YOURNAME-cluster-admin-binding --clusterrole=cluster-admin --user=[e-mail]

Now let's Git into it! (I know, I know. Hilarious pun.)

Prereqs:

Docker
K3d
ArgoCD CLI
Kubectl
Repo used for tutorial (Feel free to fork it, for your convenience.)
Docker image and versions used

Spin up k3d/k3s

$ k3d create

Configure kubectl to your k3s cluster

$ export KUBECONFIG="$(k3d get-kubeconfig --name='k3s-default')"

Deploy argocd into cluster

$ kubectl create namespace argocd
$ kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Access ArgoCD UI through port-forwarding

$ kubectl port-forward svc/argocd-server -n argocd 8080:443

Head over to http://localhost:8080/ where you should find the ArgoCD UI. You should see a login page. Your username is admin and your password is actually the name of your running server. You can get that with the following command:

$ kubectl get pods -n argocd -l app.kubernetes.io/name=argocd-server -o name | cut -d'/' -f 2

Then you'll see the following screen! Congrats, you got ArgoCD running in your cluster!

Login to ArgoCD through CLI:

You'll need to login to the running ArgoCD server through the CLI so that you can deploy applications through the CLI with ArgoCD. You could also simply do it through the UI, but we will proceed here with the CLI.

$ argocd login localhost:8080

Your password here is the same as the one from the previous step.

Configure app repo with ArgoCD

Since we are using the example repo I've provided, you'd simply replace the repo in the command with your own. Also, replace the path to the deployment directory to the path specified in your own repo.

In true GitOps fashion, you would NOT hold both the source code and the deployment manifests in the same repo. I've only done so for the sake of a more simple demonstration.

We are deploying into the default namespace, which you typically wouldn't, but for the sake of the demo it should be fine.

$ export MY_APP_NAME=express-app
$ export MY_REPO_NAME=https://github.com/Dizdarevic/gitops-brown-bag.git
$ export MY_DEPLOYMENT_PATH=example-app/deployment-repo
$ argocd app create $MY_APP_NAME --repo $MY_REPO_NAME --path $MY_DEPLOYMENT_PATH --dest-server https://kubernetes.default.svc --dest-namespace default

After which, you should see the application show up on the ArgoCD dashboard:

You'll see that the current state of the deployment is out-of-sync with the deployment configuration in your git repository.
Click on the Sync button, in the UI and then click Synchronize.
Now you can watch your app/server deploy!

Expose the v1 docker image (stated in the prereqs) with ArgoCD

I'm specifically exposing 3000, because this is the port defined in the deployment configuration as well as the port that is exposed in the docker image being used. You can do so with the following command:

$ kubectl port-forward svc/express-app -n default 3000:3000

Now you can visit http://localhost:3000/ and see your first server deployed to a cluster with ArgoCD! Congrats!

Deploy v2 and watch it redeploy

Before we begin, stop port forwarding on port 3000. It will break anyways once we redeploy a different version.

Now we will modify the version of the docker image being used in the deployment repo.

Change the image tag in the deployment repo from dizdarevic/express-app:v1 to dizdarevic/express-app:v2

Go back to the ArgoCD UI. Click Refresh on the application and you should see that it is out-of-sync again. Do the same synchronization steps as before. Allow the new version of the service to spin up, and for the old one to spin down.

Follow the same steps as before to expose the service on port 3000. Once you visit http://localhost:3000/ again, you should see a different message that shows you are using the new docker image!

Spin down everything after you're doing poking around!

$ k3d delete