GitOps on Haven — Deployment Draft

Draft only. Nothing below is applied to the cluster yet. Diagrams are [Excalidraw JSON] (import at https://excalidraw.com) — static previews included as PNG. Create the repo before running any commands.

1. Decisions

Decision	Value	Why
Tool	Argo CD	Best UI (app dependency graph, live-vs-git diff, rollback). Flux's UI (Weave GitOps) is stalled post-Weaveworks; community alternative is Capacitor.
Git remote	Gitea git.ivanch.me/ivanch/haven	Repo you'll create. Gitea is a first-class Argo CD source.
Layout	App-of-apps	A single root Argo Application watches a folder of app manifests; each app manifests as a child Application. One place to add/remove apps.
Secrets	No change. Keep raw env in manifests initially, migrate to ESO/Vaultwarden later.	Argo CD can't write Secret contents itself — value must live in git or come from a controller. Never commit real secrets.
Access	Ingress argocd.haven, internal-only (nginx class, no TLS/cert-manager) + admin password via kubectl	Matches your internal-app convention (notepad, openwebui, etc.).
Repo structure	New gitops repo (clean, standalone). Your current spec folder stays untouched — migrate later if desired.	Avoids mixing with the haven folder used by Gitea Actions CI.

2. Repo layout (gitops/)

gitops/
├── bootstrap/
│   └── root-app.yaml          # the app-of-apps (only file you apply manually, once)
├── apps/
│   └── root/
│       ├── kustomization.yaml # lists every child Application
│       ├── argocd.yaml        # Argo CD managing itself (dogfood)
│       ├── notepad.yaml
│       └── ...
└── apps/<name>/               # per-app dir
    ├── kustomization.yaml
    ├── deployment.yaml
    ├── service.yaml
    ├── ingress.yaml
    └── pvc.yaml

apps/root/kustomization.yaml is the switchboard — adding a service = adding one Application entry + one folder.

3. Manual bootstrap (run once, by hand)

# Install Argo CD — declarative kustomize install (no Helm CLI, no curl pipes).
# Renders 59 resources from the official argo-cd manifests repo, pinned via ?ref=
kubectl.exe --kubeconfig=C:\Users\ivanch\.kube\config apply -k bootstrap/argocd-install
# retrieve the initial admin password
kubectl.exe --kubeconfig=C:\Users\ivanch\.kube\config -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d
# one-time: point the root app at Gitea (requires the repo to exist first)
kubectl.exe --kubeconfig=C:\Users\ivanch\.kube\config apply -f bootstrap/root-app.yaml

Version pinning: ?ref=stable in bootstrap/argocd-install/kustomization.yaml tracks the stable branch; pin a tag (?ref=v3.1.0) once settled. Component customization goes through patches: in that same kustomization (example commented in the file), not by editing rendered output.

After that, every change is: git push → Argo syncs. kubectl only for debugging.

4. Key manifests

bootstrap/root-app.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
  finalizers: [resources-finalizer.argocd.argoproj.io]
spec:
  project: default
  source:
    repoURL: https://git.ivanch.me/ivanch/haven.git
    targetRevision: main
    path: apps/root
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

apps/root/argocd.yaml — Argo CD managing itself (standard dogfood pattern). Each child app follows the same shape with path: apps/<name> and destination.namespace matching where it runs today (default for most of your internal apps).

5. Ingress (internal-only, per Haven convention)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server
  namespace: argocd
spec:
  ingressClassName: nginx
  rules:
    - host: argocd.haven
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: argocd-server
                port: { number: 80 }

6. Diagrams (Excalidraw JSON)

Two diagrams are included as .excalidraw files — open https://excalidraw.com and drop the file onto the canvas to view/edit:

• excalidraw/haven-gitops-flow.excalidraw — the flow: git push → Gitea → Argo CD → k3s, with Gitea Actions CI reduced to image build/push only.
• excalidraw/haven-gitops-tree.excalidraw — the app-of-apps tree: root app → child Applications (notepad, openwebui, paperless, vaultwarden, argocd itself, and infra deferred to a later phase).

7. Migration plan

Phase 0 (this draft) → Phase 1: install Argo CD + root app, convert 1 pilot app (suggest notepad — simple, stateless-ish, single PVC) → Phase 2: onboard the rest of default ns → Phase 3: infra components (ingress-nginx, cert-manager, ESO) — do these last; they're the ones that can break the cluster if a sync goes wrong → Phase 4: delete the old haven spec folder once Argo is the source of truth.