create argocd apps declaratively

README.md

@@ -25,6 +25,7 @@ Aquest clúster K3s gestiona els següents serveis:
 ```
 .
 ├── README.md                    # Aquest fitxer
+├── argocd-bootstrap.yaml        # App-of-apps: llavor per a ArgoCD (aplicar 1 cop)
 ├── <aplicació>/                 # Cada aplicació té el seu directori
 │   ├── deployment.yaml          # Definició del Deployment
 │   ├── service.yaml            # Definició del Service
@@ -32,8 +33,12 @@ Aquest clúster K3s gestiona els següents serveis:
 │   ├── namespace.yaml           # Namespace dedicat (opcional)
 │   ├── configmap.yaml          # ConfigMaps (opcional)
 │   └── pvc.yaml                 # PersistentVolumeClaims (opcional)
+├── argocd/                      # ArgoCD
+│   ├── ingress.yaml             # Ingress d'ArgoCD
+│   ├── apps/                    # Applications + AppProject declaratius
+│   └── gen-apps.sh              # Genera argocd/apps/* i argocd-bootstrap.yaml
 └── nas/                         # Servei extern per al NAS
-    ├── nas.yaml                 # Service i Endpoints externs
+    ├── transport.yaml           # ServersTransport de Traefik
     └── ingress.yaml             # Ingress del NAS
 ```
 
@@ -62,6 +67,9 @@ kubectl apply -f <aplicació>/<fitxer>.yaml
 
 ### Desplegar Tot el Clúster
 
+La forma recomanada és deixar que ArgoCD sincronitzi el repo (veure secció [ArgoCD (GitOps)](#-argocd-gitops)).
+Per a un desplegament manual sense ArgoCD:
+
 ```bash
 # Desplegar totes les aplicacions
 for dir in */; do
@@ -122,6 +130,66 @@ spec:
                 number: 80
 ```
 
+## 🐙 ArgoCD (GitOps)
+
+Totes les aplicacions del repo es despleguen de forma declarativa amb ArgoCD. Hi ha un `Application` per cada directori d'aplicació, agrupades sota un `AppProject` anomenat `k3s-cluster`.
+
+### Estructura
+
+- [`argocd/apps/project.yaml`](argocd/apps/project.yaml) — `AppProject` `k3s-cluster` (sync-wave -1).
+- [`argocd/apps/<app>.yaml`](argocd/apps/) — un `Application` per aplicació (sync-wave 0), cadascun apunta al seu directori del repo.
+- [`argocd-bootstrap.yaml`](argocd-bootstrap.yaml) — `Application` "app-of-apps" que sincronitza tot el directori `argocd/apps/`. És l'únic recurs que cal aplicar a mà.
+- [`argocd/gen-apps.sh`](argocd/gen-apps.sh) — regenera tots els fitxers anteriors a partir d'una llista d'aplicacions.
+
+### Flux
+
+1. El `AppProject` i tots els `Application` estan versionats a `argocd/apps/`.
+2. L'app `k3s-cluster-root` (a `argocd-bootstrap.yaml`) llegeix `argocd/apps/` i crea/actualitza el projecte i totes les applications.
+3. Cada `Application` sincronitza el seu directori (ex: `pihole/`) cap al seu namespace, amb `prune` i `selfHeal` activats.
+
+### Bootstrap (una sola vegada)
+
+Prerequisits:
+
+1. ArgoCD instal·lat al clúster (namespace `argocd`).
+2. `cert-manager` instal·lat (veure [`cert-manager/install.sh`](cert-manager/install.sh)) — el `ClusterIssuer` depèn dels seus CRDs.
+3. El repo registrat a ArgoCD (`Settings → Repositories`). Si el repo és públic a GitHub, l'HTTPS funciona sense credencials.
+
+Llançar la llavor:
+
+```bash
+kubectl apply -f argocd-bootstrap.yaml
+```
+
+A partir d'aquí ArgoCD crea el projecte `k3s-cluster`, totes les `Application` i les sincronitza automàticament. Qualsevol canvi al repo es propaga sol (self-heal).
+
+### Recrear el clúster des de zero
+
+```bash
+# 1. Instal·lar K3s
+# 2. Instal·lar ArgoCD
+# 3. Instal·lar cert-manager
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
+kubectl wait --for=condition=available --timeout=120s deployment/cert-manager -n cert-manager
+# 4. Registrar el repo a ArgoCD (o deixar-lo públic)
+# 5. Llançar la llavor
+kubectl apply -f argocd-bootstrap.yaml
+```
+
+### Afegir o treure una aplicació
+
+1. Crea/esborra el directori de l'aplicació.
+2. Afegeix/treu la línia corresponent a l'array `APPS` de [`argocd/gen-apps.sh`](argocd/gen-apps.sh) amb el format `name|namespace|path|recurse|validate`.
+3. Executa `./argocd/gen-apps.sh` per regenerar els manifests.
+4. Fes commit i push; ArgoCD ho sincronitza sol.
+
+### Notes
+
+- Els `Application`/`AppProject` pertanyen al namespace `argocd` (recursos propis d'ArgoCD).
+- L'app `argocd` té `recurse: false` sobre el directori `argocd/` per gestionar només `ingress.yaml` i no els seus propis manifests sota `argocd/apps/`.
+- L'app `phoenix` usa `Validate=false` per tolerar el CRD `ServiceMonitor` si el Prometheus Operator encara no és instal·lat.
+- Els secrets que no estan al repo (ex: `gitea-registry` per a `gym-tracker`) s'han de crear manualment al seu namespace; Argo no els gestiona ni els esborra.
+
 ## 💾 Persistència de Dades
 
 Les aplicacions que necessiten emmagatzematge persistent utilitzen: