0 Fork 0

Files

T

devops 056a7fb76a docs(docs-portal): Fase 2 - contenido narrativo real de arquitectura/decisiones/aprendizajes

Reemplaza los placeholders "TODO (fase 2+)" por narrativa completa,
grounded en el codigo/manifiestos/incidentes reales del lab (no
generico):

- ADR 0001 (por que k3d) y ADR 0002 (por que Argo CD): pasan de
  template vacio a Contexto/Opciones/Decision/Consecuencias reales,
  apoyados en known-issues.md (blackhole MTU) y en la config real de
  ecommerce-app.yaml.
- vision-general.md: el "por que" de cada frontera de confianza del
  diagrama.
- gitops-flujo.md: ejemplo real con hashes de commit (Fase 3b de
  ADR 0006, v1.0.171 -> hotfix -> v1.0.172), selfHeal explicado con el
  syncPolicy real del repo.
- red-y-exposicion.md: diagrama de terminacion TLS real, por que todo
  va "proxied", patron de diagnostico "interno sano, publico roto".
- glosario.md: 9 terminos nuevos, cada uno con ejemplo real y
  verificado del repo (Namespace, ResourceQuota, LimitRange,
  NetworkPolicy, Deployment, Service, Ingress, StatefulSet, Init
  container).
- notas-sueltas.md: MinIO/S3, limites reales del subscriber
  revalidate-storefront.ts, que se automatizaria desde cero.

Validado con `docker build --target build` (mkdocs build --strict,
mismo paso que el pipeline real) -- cero links rotos, cero warnings.

2026-08-26 23:51:18 -05:00

4.2 KiB

Raw Permalink Blame History

Del commit al despliegue: flujo GitOps

El diagrama de abajo refleja el pipeline real (build → push imagen → promoción segura → commit del tag → sync de Argo CD). Después del diagrama hay un ejemplo con hashes de commit reales, tomado de un cambio real hecho sobre este mismo repo.

Secuencia: un commit hasta quedar corriendo en el cluster

sequenceDiagram
    actor Dev as Devops
    participant Gitea
    participant CI as Gitea Actions
    participant Reg as Gitea Registry
    participant Argo as Argo CD
    participant K8s as Cluster k3d

    Dev->>Gitea: push a fix/<rama>
    Dev->>Gitea: abre PR → main
    Gitea->>Gitea: merge a main
    Gitea->>CI: dispara workflow (paths: workloads/**)
    CI->>CI: build de la imagen (Docker)
    CI->>Reg: push imagen vX.Y.Z
    CI->>CI: verifica promoción segura (HEAD == origin/main)
    CI->>Gitea: commit "chore(gitops): release vX.Y.Z" actualizando el manifiesto
    Argo->>Gitea: detecta el nuevo commit (poll/webhook)
    Argo->>K8s: sync (prune:true, selfHeal:true)
    K8s->>K8s: rollout del nuevo pod

Por qué esta separación (build vs. deploy)

El pipeline de CI solo construye y publica la imagen — nunca aplica nada directo al cluster.
El commit al manifiesto (sed sobre el tag de imagen) es lo único que representa "intención de desplegar" — y vive en el mismo repo Git que Argo CD vigila.
Argo CD es la única pieza con permisos de escritura sobre el cluster real. Nada fuera de GitOps toca kubectl apply en producción.
El paso de "promoción segura" (comparar HEAD contra origin/main) evita que un pipeline viejo sobreescriba el tag con una versión anterior si hubo un push más reciente mientras corría.

Ejemplo real: un commit de principio a fin

Fase 3b del ADR 0006 (facetas del sidebar del catálogo, ver decisiones/0006-motor-busqueda-facetas.md) recorrió el flujo completo dos veces seguidas el mismo día:

Paso	Commit / evento real
Feature	`83d448b` — `feat(ecommerce): facetas reales de Meilisearch en el sidebar del catalogo`, en `fix/adr0006-etapa2-fase3b-facetas-sidebar`
Merge a `main`	`6b5450f`
CI build+push	Gitea Actions task 258, imagen `gitea.cruzcloud.net/devops/ecommerce-frontend`
Release commit (CD)	`951682a` — `chore: release v1.0.171 [skip ci]`, bump automático del tag en `frontend/patches/deployment.yaml`
Sync de Argo CD	dos ciclos distintos: primero sincronizó contra `6b5450f` (el merge, todavía con el tag viejo), y en el ciclo siguiente detectó `951682a` y aplicó el tag nuevo
Rollout	`frontend-deploy` con 2/2 réplicas en `v1.0.171`

El gate en vivo contra ese mismo cambio encontró un bug real (estimatedTotalHits en 0 con limit=0 en Meilisearch) — el fix repitió el mismo ciclo completo: 884dbd1 → merge ba3e6c7 → release v1.0.172 → sync → rollout. Dos vueltas completas del diagrama de arriba en la misma sesión, cada una verificada contra el endpoint real antes de darla por cerrada.

Detalle no obvio: Argo CD sincroniza el merge commit primero (todavía con la imagen vieja, porque el bump de tag es un commit posterior que hace el propio pipeline) y recién en un segundo ciclo de poll detecta el commit de release. Son dos sincronizaciones distintas, no una sola — hay que esperar ambas antes de asumir que el pod nuevo está corriendo.

`selfHeal`, con la configuración real

Todas las Applications de este repo comparten el mismo syncPolicy (apps/ecommerce-app.yaml):

syncPolicy:
  automated:
    prune: true
    selfHeal: true

Con selfHeal: true, si alguien corre kubectl scale deployment frontend-deploy --replicas=1 directo contra el cluster (saltándose Git por completo), Argo CD no se queda en mostrar OutOfSync — en el siguiente ciclo de reconciliación vuelve a aplicar el manifiesto tal como está en main y el Deployment queda otra vez en las réplicas declaradas ahí. El cambio manual no se pierde silenciosamente: queda un instante como drift visible en la UI de Argo CD, pero nunca se vuelve el estado final. La única forma de que ese cambio persista es que exista en Git — lo mismo que describe ADR 0002.

4.2 KiB Raw Permalink Blame History