Install Argo CD

What Argo CD is

A program that makes sure what is running is the same as what is in your code repository. You change a file in Git, and Argo CD detects the change and applies it. If someone instead changes something directly in the system, Argo CD sees that reality has drifted apart from the file, and flags it.

The idea is called GitOps and is simpler than the name suggests. The truth is in Git. Everything else is a copy that must be kept in sync.

Be honest about the level here. This is the most difficult tool in the collection, because Argo CD requires Kubernetes, and Kubernetes is a subject of its own. If you want to understand how real production environments work, this is the right path. If you want to get a web shop up before Christmas, there are shorter routes, and Dokku is one of them.

You need a Kubernetes cluster first

Argo CD runs inside Kubernetes and cannot be installed without it. So you need two things before you start: a cluster, and the command line tool kubectl that talks to it.

The simplest cluster for practicing is Minikube, which starts a small cluster on your own computer. It requires Docker, the same as in Install Docker.

On Windows, Docker Desktop means you also get WSL2, which is Windows' built-in Linux. Docker Desktop normally installs it itself, but if you are asked, answer yes. Without WSL2, no cluster will start.

Download Minikube from minikube.sigs.k8s.io, which has ready-made packages for both Windows and Linux. kubectl does not come with Minikube, but is downloaded separately from kubernetes.io, which also has ready-made packages for both systems. Then start the cluster:

minikube start

Windows and Linux Mint

When the cluster responds, the installation itself is two lines, and they are identical on both systems:

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

The first line creates a separate space in the cluster so that Argo CD is not mixed up with your own applications. The second fetches and starts everything you need. It takes a couple of minutes, and you follow along in kubectl get pods -n argocd until all the lines show Running.

Then open a path in to the interface:

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

Leave the window open, because the path only exists as long as the command runs. Go to https://localhost:8080, the username is admin. The browser warns about the certificate, which is expected on a local installation, and you click past it.

Three things to do first

1. Get the password, because it is not shown anywhere in the interface. On Linux Mint:

   kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

   PowerShell has no base64, so there you decode with Windows' own tools:

   [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String((kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}")))

   Then change the password with the command argocd account update-password if you have installed the argocd CLI, or under User Info in the web interface if you do not want to install the CLI, and delete the secret.
2. Connect a real repo instead of reading the documentation further. The project has a practice repo at github.com/argoproj/argocd-example-apps. Click Fork there and add your own copy as an application in the interface, not the original. You cannot change someone else's repo, and the next step is about doing exactly that. Then click Sync.
3. Change something in your copy of the repo and watch what happens. Argo CD detects the difference within a few minutes and marks the application as OutOfSync. Then it waits for you to click Sync, because automatic sync is off from the start. That picture is the whole point of the tool, and it cannot be understood by reading about it.

The most common trap

Fixing something by changing it directly in the cluster. Argo CD constantly compares the cluster with the files in Git, so the change shows up within a few minutes as OutOfSync on the application. The fix then exists only in the cluster and nowhere in Git, which means the next Sync removes it.

If you have also turned on automatic sync with self-healing, that is Automated sync and Self heal in the application settings, it happens on its own and without anyone pressing anything. Your fix is gone, the error is back, and nothing in the log clearly points to why.

The rule is therefore simple and takes a while to get used to: changes are made in Git, never in the cluster. The kubectl edit command is a troubleshooting tool, not a way to fix something.

One more thing about planning. Minikube on an ordinary laptop handles exercises perfectly well, but the cluster sits on your own machine and disappears when you shut it down. If something needs to run around the clock, you need a cluster from a provider, and that costs money. Count on that before you build something you have to be able to rely on.