125 lines
5.2 KiB
Markdown
125 lines
5.2 KiB
Markdown
# 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/
|
|
│ ├── namespaces.yaml # cluster namespaces
|
|
│ ├── argocd-install/ # Argo CD install manifests + ingress
|
|
│ └── root-app.yaml # root Application watching apps/root
|
|
├── apps/
|
|
│ ├── root/
|
|
│ │ ├── kustomization.yaml # points to applicationset.yaml
|
|
│ │ └── applicationset.yaml# auto-discovers apps/*/*.yaml
|
|
│ └── <namespace>/ # e.g., default/, media/, monitoring/
|
|
│ ├── <app-1>.yaml # all-in-one manifest per app
|
|
│ └── <app-2>.yaml
|
|
```
|
|
|
|
To add a new app: simply drop `<app>.yaml` into the appropriate `apps/<namespace>/` folder. The ApplicationSet automatically generates an Argo CD Application for it.
|
|
|
|
## 3. Manual bootstrap (run once, by hand)
|
|
|
|
```bash
|
|
# 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`**
|
|
```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/applicationset.yaml`** — Uses the Git Files generator to discover any `apps/*/*.yaml` file and automatically generate an Argo CD `Application` pointing directly to that app file within the respective namespace.
|
|
|
|
## 5. Ingress (internal-only, per Haven convention)
|
|
|
|
```yaml
|
|
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.
|