Installing ArgoCD on Rancher Desktop (Local)
#

Prerequisites
#

1
2
3
# Confirm you're on the right cluster
kubectl config current-context   # should print: rancher-desktop
kubectl get nodes                # should show lima-rancher-desktop Ready

1. Install ArgoCD
#

1
2
3
4
kubectl create namespace argocd

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

--server-side --force-conflicts is required. The ArgoCD install manifest is large enough that a plain kubectl apply (client-side) hits the annotation size limit and silently skips some CRDs - including ApplicationSet. Without it the argocd-applicationset-controller will CrashLoopBackOff immediately after install. --force-conflicts handles any field manager conflicts on re-apply.

Wait for pods to be ready
#

1
kubectl wait --for=condition=Ready pods --all -n argocd --timeout=180s

Verify
#

1
kubectl get pods -n argocd

Expected output - all pods Running:

1
2
3
4
5
6
7
argocd-application-controller-0          1/1     Running
argocd-applicationset-controller-...     1/1     Running
argocd-dex-server-...                    1/1     Running
argocd-notifications-controller-...      1/1     Running
argocd-redis-...                         1/1     Running
argocd-repo-server-...                   1/1     Running
argocd-server-...                        1/1     Running

2. Access the UI
#

Port-forward the ArgoCD server (run in a separate terminal and keep it open):

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

Open: https://localhost:8080 (accept the self-signed cert warning)

Get the initial admin password
#

1
2
kubectl get secret argocd-initial-admin-secret -n argocd \
  -o jsonpath='{.data.password}' | base64 -d && echo

3. Install the ArgoCD CLI
#

1
2
brew install argocd
argocd version --client   # verify

Login via CLI
#

1
2
3
4
# With port-forward running on 8080
argocd login localhost:8080 \
  --username admin \
  --insecure

--insecure skips TLS verification for the self-signed cert (fine for local dev).

Verify CLI access
#

1
2
argocd cluster list    # should show the in-cluster entry
argocd app list        # empty for now

4. (Optional) Change the Admin Password
#

1
argocd account update-password

Note for eu-dev-rancher: the admin password is managed declaratively via environments/eu-dev-rancher/argocd/argocd-admin-password.yaml (bcrypt hash committed to git). ArgoCD applies it on wave 3 - argocd account update-password would be overwritten on the next sync. To change it for eu-dev-rancher, regenerate the hash and update the file.

What Was Installed
#

Component	Role
`argocd-server`	API server + Web UI
`argocd-repo-server`	Clones Git repos, renders manifests (Helm, Kustomize)
`argocd-application-controller`	Reconciles desired state (Git) vs actual state (cluster)
`argocd-applicationset-controller`	Generates Applications from templates
`argocd-dex-server`	OIDC/SSO provider
`argocd-redis`	Cache for repo-server and app-controller
`argocd-notifications-controller`	Sends sync/health alerts

Troubleshooting
#

Pod stuck in Pending:

1
2
kubectl describe pod <pod-name> -n argocd
# Look for resource constraints or image pull errors

argocd-applicationset-controller in CrashLoopBackOff:

1
2
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-applicationset-controller --tail=20
# Error: "no matches for kind ApplicationSet in version argoproj.io/v1alpha1"

The ApplicationSet CRD was not installed - this happens when ArgoCD was applied without --server-side, which hits annotation size limits and silently skips CRDs. Fix by re-applying with server-side apply:

1
2
3
4
5
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Verify the CRD is now present
kubectl get crd applicationsets.argoproj.io

The controller will recover automatically on its next restart.

argocd login times out:

1
2
# Make sure port-forward is still running
kubectl port-forward svc/argocd-server -n argocd 8080:443

k9s can’t find applications.argoproj.io / ArgoCD CRDs not visible: k9s (and kubectl) may show no ArgoCD resources even though ArgoCD is installed. This can happen after a Rancher Desktop restart - the k3s API server comes back up before all CRDs are fully re-registered. Fix: restart Rancher Desktop fully (not just the VM), wait for nodes to be Ready, then re-open k9s.

1
2
kubectl get nodes          # wait until Ready
kubectl get crd | grep argoproj   # confirm CRDs are present

In k9s, navigate with :applications.argoproj.io (the short name :app may be ambiguous).

Forgot admin password:

1
2
3
# Re-read from the secret (valid until you delete it or change the password)
kubectl get secret argocd-initial-admin-secret -n argocd \
  -o jsonpath='{.data.password}' | base64 -d && echo