How to Use ArgoCD?

Don’t get afraid because getting started with ArgoCD is simple. Wanna see how simple it is? Click, you won’t regret.

I installed ArgoCD, deployed the guestbook app, and then did something naughty: I changed the cluster by hand to see what ArgoCD does about it. The answer surprised me a little, because at first it did nothing — no suggestion, no warning and more importantly no reconciliation. Let me show you the whole thing.

Install ArgoCD

# namespace
kubectl create namespace argocd

# clone repo
# good to clone at /tmp because it's not part of your project
cd /tmp
git clone https://github.com/argoproj/argo-helm.git
cd argo-helm/charts/argo-cd
helm dependency up # downloads dependencies from Chart.yaml

# install
helm install argocd . --values values.yaml -n argocd

Verify:

helm list -n argocd

NAME    NAMESPACE       REVISION        UPDATED                                         STATUS          CHART           APP VERSION
argocd  argocd          1               2026-10-27 14:01:41.858028041 +0545 +0545       deployed        argo-cd-10.11.6 v3.5.6

Wait until all the pods are running:

kubectl get pods -n argocd

Open The UI

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

Now open https://localhost:8080 in the browser. It will show a certificate warning, that is normal, ArgoCD is using a self-signed one.

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

Install The CLI

Go to the official release page and download the latest stable version for your OS. For example:

# for linux amd64 (x86_64)
VERSION=$(curl -L -s https://raw.githubusercontent.com/argoproj/argo-cd/stable/VERSION)
curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/download/v$VERSION/argocd-linux-amd64
sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
rm argocd-linux-amd64

Verify:

which argocd

/usr/local/bin/argocd

Log in (keep the port-forward running in another terminal):

argocd login localhost:8080 --username admin --insecure

It asks for the same admin password. After that:

argocd app list

Create An Application

You can create an application using kind: Application, the CLI or the UI, whatever you are comfortable with. The best way to start is this example repo. Let’s deploy the guestbook using YAML manifests, first from the UI:

Same thing using a YAML manifest:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook-ui
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps
    path: guestbook
    targetRevision: HEAD
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: false
      selfHeal: false

kubectl apply -f guestbook-ui.yaml
kubectl get app -n argocd

NAME           SYNC STATUS   HEALTH STATUS
guestbook-ui   Synced        Healthy

Watch the pods come up:

kubectl get pods -w

NAME                            READY   STATUS              RESTARTS   AGE
guestbook-ui-6d476cf4df-5z77t   0/1     ContainerCreating   0          37s
guestbook-ui-6d476cf4df-5z77t   1/1     Running             0          92s

Sync Policy Options

Those two false values in syncPolicy are the interesting part:

Let’s Be Naughty

Git says 1 replica. I will change the cluster by hand to 2:

kubectl scale deployment guestbook-ui --replicas=2
kubectl get pods -w

NAME                            READY   STATUS    RESTARTS   AGE
guestbook-ui-6d476cf4df-5z77t   1/1     Running   0          14m
guestbook-ui-6d476cf4df-t5vxd   1/1     Running   0          5m31s

I waited and nothing happened, even after 5m31s. The pod stayed. That is because I had only Auto Sync on. Auto Sync reacts when Git changes, and Git did not change. My change was in the cluster. The app just showed OutOfSync in the UI.

I got annoyed, so I turned on Self Heal (UI checkbox, or CLI):

argocd app set guestbook-ui --self-heal

NAME                            READY   STATUS        RESTARTS   AGE
guestbook-ui-6d476cf4df-5z77t   1/1     Running       0          14m
guestbook-ui-6d476cf4df-t5vxd   1/1     Running       0          5m31s
guestbook-ui-6d476cf4df-t5vxd   1/1     Terminating   0          6m21s
guestbook-ui-6d476cf4df-t5vxd   0/1     Completed     0          6m22s

As soon as Self Heal was on, ArgoCD noticed 2 in the cluster but 1 in Git, and Git is the boss. The extra pod was gone.

    flowchart LR
    scale["Scale to 2 by hand"] --> auto["Auto Sync only"]
    auto --> stay["Stays 2, shows OutOfSync"]
    stay --> heal["Turn on Self Heal"]
    heal --> back["Back to 1, same as Git"]
  

Clean Up

Delete the app using the CLI, because it also removes the resources the app created. If you use kubectl delete app, the guestbook pods stay behind.

argocd app delete guestbook-ui --yes
helm uninstall argocd -n argocd
kubectl delete namespace argocd

Helm leaves the CRDs behind, so remove them too if you want a fully clean cluster:

kubectl delete crd applications.argoproj.io applicationsets.argoproj.io appprojects.argoproj.io