Installation

1. Overview

This page documents a fresh ArgoCD installation. Use this procedure for disaster recovery when deploying to a new or rebuilt cluster.

2. Prerequisites

  • kubectl configured with cluster admin access to the target cluster

  • helm v3.x installed

  • Cluster has an ingress controller (nginx) deployed

  • cert-manager installed with a ClusterIssuer named letsencrypt-prod

  • DNS record for argocd.idealogic.co.za pointing to the cluster ingress

3. Installation Steps

3.1. 1. Add the Helm Repository

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update argo

3.2. 2. Create the Namespace

kubectl create namespace argocd

3.3. 3. Apply CRDs

Helm does not manage CRD lifecycle on install, but for a fresh installation ArgoCD CRDs are bundled with the chart. For explicit control:

kubectl apply -k "https://github.com/argoproj/argo-cd/manifests/crds?ref=v3.3.2" \
  --server-side --force-conflicts

3.4. 4. Create the OIDC Secret

Before installing, create the secret containing the Azure AD OIDC client secret:

kubectl create secret generic argocd-secret -n argocd \
  --from-literal=oidc.azure.clientSecret='<client-secret-value>'
The OIDC client secret must be obtained from the Azure AD app registration in the Azure portal. The app registration is in the e0fd5785-e83e-439e-b7e7-5bfb0b2e8a84 tenant with client ID 0dd148b2-05be-4fbc-a259-721c1d4f8a37.

3.5. 5. Create the Values File

Create argocd-values.yaml with the contents documented in the Configuration page.

3.6. 6. Install with Helm

helm install idealogic argo/argo-cd \
  --version 9.4.4 \
  -n argocd \
  -f argocd-values.yaml \
  --wait --timeout 5m

3.7. 7. Verify the Installation

# Check all pods are running
kubectl get pods -n argocd

# Check the ArgoCD version
kubectl get pods -n argocd -o jsonpath='{.items[0].spec.containers[0].image}'

# Verify ingress is created
kubectl get ingress -n argocd

# Verify certificate is issued
kubectl get certificate -n argocd

3.8. 8. Retrieve the Admin Password

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d
Delete the initial admin secret after first login and password change.

4. Post-Installation

4.1. Register Downstream Clusters

After installation, add the downstream clusters that ArgoCD manages:

# Log in to ArgoCD CLI
argocd login argocd.idealogic.co.za

# Add clusters (requires kubeconfig context)
argocd cluster add idl-xnl-jhb1-rc01 --name idl-xnl-jhb1-rc01
argocd cluster add idl-azr-eastus-aks1 --name idl-azr-eastus-aks1

Alternatively, clusters can be registered via the UI or by creating cluster secrets directly.

4.2. Restore Applications

If restoring from a backup, apply the application manifests:

kubectl apply -f applications-backup.yaml
kubectl apply -f appprojects-backup.yaml
Ensure the backup files are available. The upgrade procedure stores backups in the project’s .argocd-backup/ directory.

5. Troubleshooting

5.1. Pods Not Starting

Check events and logs:

kubectl get events -n argocd --sort-by='.lastTimestamp'
kubectl logs -n argocd deployment/idealogic-argocd-server
kubectl logs -n argocd deployment/idealogic-argocd-repo-server
kubectl logs -n argocd statefulset/idealogic-argocd-application-controller

5.2. Certificate Not Issuing

Verify cert-manager is working:

kubectl get certificate -n argocd
kubectl describe certificate -n argocd
kubectl get challenges -n argocd

5.3. OIDC Login Not Working

Verify the OIDC secret exists and has the correct key:

kubectl get secret argocd-secret -n argocd -o jsonpath='{.data}' | \
  python3 -c "import sys,json; print('\n'.join(json.load(sys.stdin).keys()))"

The secret must contain the key oidc.azure.clientSecret.