Bootstrap ArgoCD

This guide shows you how to install ArgoCD, connect it to your Git repository, and deploy the Portefaix app-of-apps pattern to manage all platform stacks.

Prerequisites

• A running Kubernetes cluster with kubectl access
• Helm ≥ 3.12 installed
• ArgoCD CLI (argocd) installed
• Your fork of portefaix-kubernetes on GitHub/GitLab

1. Add the Argo Helm repository

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

2. Install ArgoCD

Portefaix provides per-cloud values-*.yaml files that configure ArgoCD with appropriate resource limits, OIDC integration, and Helm plugin settings.

kubectl create namespace argocd

# Replace CLOUD with: gcp | aws | azure | scaleway
helm install argocd argo/argo-cd \
  --namespace argocd \
  --version 7.x.x \
  --values portefaix-kubernetes/gitops/argocd/values-CLOUD.yaml \
  --wait

Verify all pods are running:

kubectl get pods -n argocd

3. Access the ArgoCD UI

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

# Get the initial admin password
argocd admin initial-password -n argocd

Visit https://localhost:8080 and log in with admin and the password above.

4. Log in with the CLI

argocd login localhost:8080 \
  --username admin \
  --password "$(argocd admin initial-password -n argocd | head -1)" \
  --insecure

5. Connect your Git repository

argocd repo add https://github.com/YOUR_ORG/portefaix-kubernetes \
  --username git \
  --password "YOUR_GITHUB_PAT"

For SSH authentication:

argocd repo add git@github.com:YOUR_ORG/portefaix-kubernetes \
  --ssh-private-key-path ~/.ssh/id_ed25519

6. Deploy the app-of-apps

The app-of-apps pattern uses a single ArgoCD Application that manages all other Applications. Apply the bootstrap manifest for your cloud and environment:

kubectl apply -f portefaix-kubernetes/gitops/argocd/bootstrap/app-of-apps-CLOUD-ENV.yaml

Monitor the initial sync:

argocd app list
argocd app get portefaix-bootstrap
argocd app sync portefaix-bootstrap --prune

Stack deployment order

ArgoCD deploys stacks in waves defined by the argocd.argoproj.io/sync-wave annotation. The order ensures dependencies are ready before dependents:

Troubleshooting

App stuck in OutOfSync:

argocd app diff portefaix-bootstrap
argocd app sync portefaix-bootstrap --prune --force

Webhook not receiving GitHub events: ensure your ArgoCD server is reachable from GitHub. Configure the webhook secret in argocd-secret:

kubectl patch secret argocd-secret -n argocd \
  --type merge \
  -p '{"stringData":{"webhook.github.secret":"YOUR_WEBHOOK_SECRET"}}'