ArgoCD

ArgoCD is a declarative, GitOps-based continuous delivery tool for Kubernetes. In Portefaix it serves as the primary application delivery engine, managing the lifecycle of platform stacks and workloads across clusters.

Architecture

ArgoCD runs inside the cluster and continuously reconciles Application and ApplicationSet resources against the desired state stored in Git:

App of Apps — a single root Application bootstraps all other Applications, so a single kubectl apply brings up the entire platform.
ApplicationSets — generate Applications automatically from cluster lists, directories, or Git history — useful for multi-cluster deployments.
Projects — ArgoCD Projects scope which repositories and clusters each Application can target, enforcing least-privilege.

Bootstrap

To bootstrap ArgoCD on a fresh cluster:

# Install ArgoCD into the cluster
kubectl create namespace argocd
kubectl apply -n argocd \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Apply the Portefaix root Application
kubectl apply -f clusters/<cloud>/<env>/argocd/root-app.yaml

From this point, ArgoCD reconciles all remaining stacks automatically from the Git repository. No further manual installation steps are required.

Platform Stacks

Portefaix organises the platform into stacks — logical groups of related components managed together as ArgoCD Applications:

Stack	Components
Observability	Grafana, Prometheus, Loki, Tempo, Mimir, Alloy
Security	Falco, Trivy Operator, cert-manager, Validating Admission Policies
Networking	Cilium, external-dns, ingress-nginx, Gateway API
Platform	Crossplane, Cluster API, Velero, external-secrets
GitOps	ArgoCD itself, Argo Rollouts, Argo Workflows

Sync Policies

Each Application in Portefaix is configured with automated sync:

spec:
  syncPolicy:
    automated:
      prune: true      # remove resources deleted from Git
      selfHeal: true   # revert manual changes to cluster
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true

Caution: prune: true will delete cluster resources that are removed from Git. Verify your Git state is complete before enabling this on production clusters.

Useful Make Targets

The Portefaix Makefile provides targets for common ArgoCD operations:

# Deploy a specific stack
make argocd-deploy-stack STACK=observability ENV=production

# Check sync status
make argocd-status

# Force a sync
make argocd-sync APP=observability

Multi-cluster Setup

For multi-cluster deployments, ArgoCD runs in a central management cluster and registers spoke clusters using the ArgoCD CLI:

argocd cluster add <context-name> \
  --name <friendly-name> \
  --in-cluster=false

ApplicationSets then target all registered clusters automatically using the cluster generator.