Skip to content

GitOps with ArgoCD

How it Works

ArgoCD continuously watches the master branch of this repo. Any change merged to master is automatically applied to the cluster — no manual kubectl apply needed.

git push origin master
       │
       ▼
  ArgoCD detects drift
       │
       ▼
  Applies diff to cluster
  (create / update / prune)

The App-of-Apps Pattern

This repo uses the App of Apps pattern: a single root ArgoCD Application (argocd-apps) manages a Helm chart whose templates generate all other Application CRDs.

argocd-apps (root)
  └── kubernetes/apps/addons/argocd-apps/
        ├── application.yaml    ← bootstraps the root app itself
        ├── values.yaml         ← sets cluster destination
        └── templates/
              ├── addons/argocd.yaml
              ├── homelab/mealie.yaml
              ├── automation/home-assistant.yaml
              └── ... (one file per app)

Bootstrap — application.yaml is the only file that needs to be manually applied once:

kubectl apply -f kubernetes/apps/addons/argocd-apps/application.yaml

After that, every other app in templates/ is created and managed automatically.

Application Template

Every app in templates/<namespace>/<app>.yaml follows the same pattern — a multi-source ArgoCD Application that pulls the upstream Helm chart and overlays values from this repo:

# --------------------
# cert-manager
#   - Docs: https://cert-manager.io/docs/
#   - Chart: https://charts.jetstack.io (cert-manager)
# --------------------
---
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: cert-manager
  namespace: {{ .Release.Namespace }}
  finalizers:
    - resources-finalizer.argocd.argoproj.io   # (1)
spec:
  project: default
  sources:
    - repoURL: https://charts.jetstack.io
      targetRevision: 1.20.2                   # (2)
      chart: cert-manager
      helm:
        valueFiles:
          - $values/kubernetes/apps/addons/cert-manager/values.yaml
    - repoURL: git@github.com:afonsoc12/homelab.git
      targetRevision: HEAD
      ref: values                              # (3)
  destination:
    name: {{ .Values.spec.destination.name }}
    namespace: addons
  1. Cascade-deletes all owned resources when the Application is deleted.
  2. targetRevision is pinned to a specific chart version. Renovate opens PRs to update that pinned version.
  3. The second source is a ref (no path, no chart) — it only provides the values files for the first source.

Sync Policy

The root argocd-apps application has selfHeal: true and prune: true:

syncPolicy:
  automated:
    prune: true      # removes resources deleted from Git
    selfHeal: true   # reverts manual in-cluster changes
  syncOptions:
    - CreateNamespace=true

Self-heal

Any manual change made directly via kubectl will be reverted the next time ArgoCD syncs. All changes must go through Git.

Useful Commands

# List all apps and their sync status
argocd app list

# Force sync a specific app
argocd app sync <app-name>

# Sync with pruning (removes orphaned resources)
argocd app sync <app-name> --prune

# Check app details and events
argocd app get <app-name>

# View diff between Git and live state
argocd app diff <app-name>

# Rollback to previous version
argocd app rollback <app-name>

Renovate Integration

Renovate runs on this repo and automatically opens PRs to:

  • Bump Helm chart targetRevision in app templates
  • Update container image tags in values files

Renovate is configured to ignore .decrypted~*.yaml files so it never touches SOPS intermediaries.

Deployment tool security

Argo CD verifies the OIDC provider certificate with its system CA trust store. Keep the provider certificate chain valid rather than disabling verification.

CI checks that every field selected by each SOPS file encryption policy is encrypted. GitHub Actions grant write permissions only to jobs that publish an image, update an image tag, deploy Pages or publish a release.

The SOPS private-key volume is read-only. The secrets, secrets+age-import and secrets+age-import-kubernetes downloader schemes are enabled, supporting the current GPG configuration and a future age migration. Configure the age private-key mount or Kubernetes Secret access when migrating. Symlinks are rejected. Absolute values paths remain enabled because Argo CD resolves values files to absolute paths. Parent-directory paths remain enabled because local charts load encrypted values through secrets://../../apps/...; disabling them prevents manifest generation. Test changes to these flags through the helm-secrets wrapper, not only with decrypted Helm input.

MetalLB address pools are stored in kubernetes/apps/addons/metallb-resources/values.sops.yaml and decrypted by helm-secrets during rendering.