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
 ```