Update README.md

2026-07-18 01:04:35 +00:00
parent 62385a475b
commit b2c6e28068
1 changed files with 387 additions and 0 deletions
@@ -352,3 +352,390 @@ DOCKER_BIN="$(command -v docker)" \
 CURL_BIN="$(command -v curl)" \
 sudo -E LAB_HOST_IP=192.168.68.61 ./deploy-lab.sh install-autostart
 ```
+
+
+# Bootstrap GitOps completo v4.0
+
+La versión v4.0 agrega dos piezas al laboratorio:
+
+1. **App-of-Apps**
+   - Aplica `root-apps-registry`.
+   - Fuente: `https://gitea.cruzcloud.net/devops/apps-registry.git`.
+   - Revisión: `main`.
+   - Ruta: `apps`.
+   - Espera las ocho Applications existentes en el repositorio.
+   - Informa cuáles siguen `Progressing`, `OutOfSync` o `Degraded`.
+
+2. **Gitea Actions runner persistente**
+   - Contenedor: `gitea-runner`.
+   - Registro persistente: `/DATA/AppData/k3d-lab/gitea-runner/data/.runner`.
+   - Monta `/var/run/docker.sock`.
+   - Política `unless-stopped`.
+   - Etiqueta compatible con `runs-on: ubuntu-latest`.
+   - El servicio systemd también valida y recupera el runner.
+
+## Primera adopción del runner existente
+
+Primero confirma que no haya un workflow activo y ejecuta:
+
+```bash
+MIGRATE_EXISTING_RUNNER=true ./deploy-lab.sh runner
+```
+
+El script:
+
+- detecta la imagen actual;
+- copia `/data` desde el contenedor existente;
+- guarda `.runner` fuera del contenedor;
+- recrea `gitea-runner` con el volumen persistente;
+- no requiere un token nuevo si `.runner` pudo recuperarse.
+
+## Runner desde cero
+
+Obtén un token desde Gitea:
+
+```text
+apps-registry -> Settings -> Actions -> Runners
+```
+
+Guárdalo sin mostrarlo:
+
+```bash
+sudo install -d -m 0700 -o devops /DATA/AppData/k3d-lab/secrets
+sudo sh -c 'umask 077; cat > /DATA/AppData/k3d-lab/secrets/gitea-runner-registration-token'
+```
+
+Pega únicamente el token y finaliza con `Ctrl+D`. Después:
+
+```bash
+sudo chown devops /DATA/AppData/k3d-lab/secrets/gitea-runner-registration-token
+sudo chmod 0600 /DATA/AppData/k3d-lab/secrets/gitea-runner-registration-token
+./deploy-lab.sh runner
+```
+
+El token solo se utiliza para generar `/data/.runner`. El contenedor permanente no conserva el token de registro como variable de entorno.
+
+## Repositorio privado de Argo CD
+
+Cuando `apps-registry` sea privado, crea:
+
+```bash
+sudo sh -c 'umask 077; printf "%s\n" "devops" > /DATA/AppData/k3d-lab/secrets/argocd-repo-username'
+sudo sh -c 'umask 077; cat > /DATA/AppData/k3d-lab/secrets/argocd-repo-password'
+```
+
+Pega un token de Gitea con lectura del repositorio y finaliza con `Ctrl+D`.
+
+```bash
+sudo chown devops /DATA/AppData/k3d-lab/secrets/argocd-repo-username
+sudo chown devops /DATA/AppData/k3d-lab/secrets/argocd-repo-password
+sudo chmod 0600 /DATA/AppData/k3d-lab/secrets/argocd-repo-*
+```
+
+## Aplicar solo GitOps al clúster actual
+
+```bash
+./deploy-lab.sh gitops
+```
+
+## Reconstrucción completa
+
+```bash
+LAB_HOST_IP=192.168.68.61 ./deploy-lab.sh bootstrap
+```
+
+El orden es:
+
+```text
+k3d -> Argo CD -> repositorio Gitea -> root-apps-registry
+     -> Applications hijas -> RBAC postdeploy -> Gitea runner
+```
+
+## Reinstalar systemd
+
+```bash
+sudo LAB_HOST_IP=192.168.68.61 ./deploy-lab.sh install-autostart
+```
+
+## Verificación
+
+```bash
+kubectl get applications.argoproj.io -n argocd
+docker ps --filter name=gitea-runner
+docker logs --tail 100 gitea-runner
+```
+
+
+# Caché Git persistente v4.1
+
+La versión v4.1 no recrea `root-apps-registry` como fuente principal.
+Antes de aplicar GitOps:
+
+1. clona `apps-registry` cuando no existe;
+2. ejecuta `git fetch --prune` cuando ya existe;
+3. alinea la copia local con `origin/main`;
+4. valida `application.yaml` y la carpeta `apps/`;
+5. aplica `application.yaml` directamente desde el clon;
+6. registra el commit utilizado;
+7. conserva el clon en `/DATA` para una recuperación cuando Gitea esté
+   temporalmente fuera de servicio.
+
+Ruta:
+
+```text
+/DATA/AppData/k3d-lab/git/apps-registry
+```
+
+Commit utilizado:
+
+```text
+/DATA/AppData/k3d-lab/git/apps-registry.commit
+```
+
+## Actualizar únicamente el clon
+
+```bash
+./deploy-lab.sh repo-sync
+```
+
+## Actualizar el clon y reconciliar Argo CD
+
+```bash
+./deploy-lab.sh gitops
+```
+
+## Reconstrucción desde cero
+
+```bash
+LAB_HOST_IP=192.168.68.61 ./deploy-lab.sh bootstrap
+```
+
+El `bootstrap` intenta obtener primero la última versión de `main`. Cuando
+Gitea no responde y ya existe un clon válido, utiliza el commit cacheado y
+permite que Argo CD vuelva a reconciliarse cuando Gitea regrese.
+
+El watchdog no hace `git fetch` cada cinco minutos por defecto. Solo usa el
+clon para restaurar `root-apps-registry` si desaparece. Argo CD sigue siendo
+el encargado de observar Git y desplegar cambios durante la operación normal.
+
+Para actualizar el clon también durante `ensure`:
+
+```bash
+APP_REGISTRY_REFRESH_ON_ENSURE=true \
+sudo LAB_HOST_IP=192.168.68.61 ./deploy-lab.sh install-autostart
+```
+
+No se recomienda en el valor predeterminado porque haría una consulta a
+Gitea en cada ejecución del watchdog.
+
+
+# Corrección v4.2: descubrimiento dinámico y monitoring
+
+## Applications esperadas
+
+La lista ya no está codificada manualmente. El script descubre el
+`metadata.name` real de cada `Application` dentro de:
+
+```text
+/DATA/AppData/k3d-lab/git/apps-registry/apps/
+```
+
+Esto evita falsos errores cuando el nombre real es, por ejemplo,
+`monitoring-governance` y no `monitoring-governance-app`.
+
+También se puede seguir forzando una lista explícita:
+
+```bash
+EXPECTED_GITOPS_APPS="ecommerce-app,monitoring-app" ./deploy-lab.sh gitops
+```
+
+## Diagnóstico de kube-prometheus-stack
+
+```bash
+./deploy-lab.sh monitoring-diagnose
+```
+
+El comando muestra:
+
+- versión del chart;
+- estado Sync/Health;
+- operación de Argo CD;
+- mensaje del hook;
+- Jobs y Pods admission-create/admission-patch;
+- eventos recientes;
+- condiciones de la Application.
+
+Para chart `58.2.1` o `58.2.2`, usa como mínimo `58.3.3` y agrega:
+
+```yaml
+helm:
+  parameters:
+    - name: prometheusOperator.admissionWebhooks.patch.ttlSecondsAfterFinished
+      value: "60"
+```
+
+
+# Multi-repo y governance v4.3
+
+La versión v4.3 incorpora el segundo repositorio GitOps:
+
+```text
+https://gitea.cruzcloud.net/devops/platform-infra.git
+```
+
+El repositorio contiene los overlays Kustomize utilizados por las
+Applications `*-governance`.
+
+## Cachés persistentes
+
+```text
+/DATA/AppData/k3d-lab/git/apps-registry
+/DATA/AppData/k3d-lab/git/platform-infra
+```
+
+## Validación Kustomize
+
+El script descubre en `apps-registry/apps/*.yaml` todas las Applications
+cuyo `repoURL` apunta a `platform-infra`, valida que sus rutas existan y
+ejecuta:
+
+```bash
+kubectl kustomize <ruta>
+```
+
+Los snapshots renderizados quedan en:
+
+```text
+/DATA/AppData/k3d-lab/rendered/platform-infra/
+```
+
+Durante un bootstrap se aplican antes de crear las Applications de workload.
+Esto garantiza que Namespace, ResourceQuota, LimitRange y NetworkPolicy
+estén presentes antes de instalar Helm charts.
+
+## Contrato obligatorio de monitoring
+
+`monitoring-governance` debe contener un `LimitRange`, porque su
+`ResourceQuota` exige requests y limits de CPU y memoria.
+
+Se incluyen archivos de referencia en:
+
+```text
+repo-patches/platform-infra/monitoring-governance/
+├── limitrange.yaml
+└── kustomization.yaml
+```
+
+Copia `limitrange.yaml` al repositorio `platform-infra` y agrega el recurso
+a su `kustomization.yaml`.
+
+## Sincronizar ambos repositorios
+
+```bash
+./deploy-lab.sh repo-sync
+```
+
+## Reconciliar GitOps completo
+
+```bash
+LAB_HOST_IP=192.168.68.61 ./deploy-lab.sh gitops
+```
+
+## Reinstalar watchdog
+
+```bash
+sudo LAB_HOST_IP=192.168.68.61 ./deploy-lab.sh install-autostart
+```
+
+
+# Recuperación de operación obsoleta de Grafana
+
+Grafana puede funcionar mientras Argo CD mantiene una operación antigua,
+por ejemplo target `58.3.3` con operación activa `58.2.1`.
+
+```bash
+./deploy-lab.sh monitoring-diagnose
+./deploy-lab.sh monitoring-recover
+```
+
+La recuperación valida el LimitRange, termina la operación anterior,
+elimina únicamente los Jobs admission temporales, ejecuta hard refresh,
+sincroniza la revisión actual y espera `Synced/Healthy`.
+
+Cuando `argocd` no está instalado en ZimaOS se usa temporalmente la imagen
+oficial de Argo CD con `--core` y `/DATA/.kube/config`.
+
+El manifiesto funcional está en:
+
+```text
+repo-patches/apps-registry/apps/monitoring-app.yaml
+```
+
+
+# Corrección v4.4.1: compatibilidad CLI Argo CD 3.2
+
+`argocd app terminate-op` y `argocd app sync` no aceptan
+`--app-namespace` en la versión usada por el laboratorio.
+
+La función `argocd_core_cli` ahora ejecuta:
+
+```bash
+argocd app terminate-op monitoring-app --core
+argocd app sync monitoring-app --core --async --prune --assumeYes
+```
+
+Las Applications del laboratorio residen en `argocd`, el namespace de
+control de Argo CD.
+
+
+# Corrección v4.4.2
+
+Se corrigen dos comportamientos:
+
+1. Cuando `monitoring-app` ya tiene:
+   - revisión de operación igual al target;
+   - fase `Succeeded`;
+   - estado `Synced/Healthy`;
+
+   el script termina correctamente y no inicia otra sincronización.
+
+2. En modo `argocd --core`, el kubeconfig temporal fija el namespace
+   actual en `argocd`. Esto evita:
+
+```text
+configmap "argocd-cm" not found
+```
+
+El flujo intenta primero hard refresh y auto-sync. Solo llama
+`argocd app sync --core` si Argo CD no inicia la reconciliación.
+
+
+# Corrección v4.4.3: Gitea runner y restart storm
+
+El watchdog se ejecuta como `devops`; no puede pedir una contraseña de
+`sudo`. La v4.4.3:
+
+- crea las rutas persistentes del Gitea runner durante `install-autostart`;
+- elimina `sudo` del flujo `ensure -> ensure_gitea_runner`;
+- cambia el servicio `oneshot` a `Restart=no`;
+- deja los reintentos exclusivamente al timer de cinco minutos;
+- limita fallos con `StartLimitIntervalSec=15min` y `StartLimitBurst=3`;
+- agrega `Persistent=true` al timer.
+
+Esto evita ciclos como:
+
+```text
+restart counter is at 645
+sudo: a terminal is required
+Failed to allocate directory watch: Too many open files
+```
+
+Instalación:
+
+```bash
+sudo systemctl stop k3d-lab-ensure.timer
+sudo systemctl stop k3d-lab-ensure.service || true
+sudo systemctl reset-failed k3d-lab-ensure.service
+
+sudo LAB_HOST_IP=192.168.68.61 ./deploy-lab.sh install-autostart
+```