carnufex/gitops-app-onboarding

Incorporación de aplicaciones GitOps

El método es genérico; los hechos del clúster (rutas, listas blancas, registro, clases de almacenamiento, gateways, aplicaciones de referencia, dónde viven las alertas) están en .claude/profiles/gitops.md en el repositorio GitOps. Lee primero el perfil. Si falta, créalo a partir de templates/profile.md leyendo el repositorio (el ApplicationSet, el AppProject, el almacén de secretos, una o dos aplicaciones existentes, la carpeta de monitorización) e informa al usuario en una línea que lo has escrito. Nunca adivines una ruta.

Cómo una aplicación se vuelve activa

• Un ApplicationSet con un generador de directorios convierte cada carpeta bajo el directorio de aplicaciones del perfil en su propia aplicación y namespace de ArgoCD. Una carpeta se despliega una vez que tiene un kustomization.yaml válido.
• Nada llega al clúster hasta que se envía a la rama que ArgoCD rastrea. Un cambio aplicado solo con kubectl se revierte en la próxima sincronización.
• Los componentes de plataforma (CNI, almacenamiento, controladores) no van en el directorio de aplicaciones; el perfil indica dónde viven.

Un nuevo namespace debe estar en lista blanca en todas partes, en el mismo commit

La sección Listas blancas del perfil lista cada archivo que nombra namespaces (típicamente: los destinations del AppProject, las conditions del ClusterSecretStore, y el pool de IPs de Load Balancer y los selectores de anuncio L2/BGP si la aplicación necesita una IP de LB). Si falta uno, la aplicación falla al sincronizar, sus ExternalSecrets quedan en SecretSyncError, o su IP de LB nunca se anuncia. Añade el namespace a todos los archivos aplicables en el commit que añade la carpeta.

Orden de incorporación (la forma segura más pequeña primero)

1. ns.yaml: el namespace con las etiquetas de seguridad de pods del perfil.
2. kustomization.yaml: recursos en orden de dependencia (namespace y configuración, luego cargas de trabajo, luego rutas).
3. Secretos: crea primero las entradas en el backend de secretos (perfil: Secretos), luego un ExternalSecret por secreto. Nunca subas valores de secretos; los secretos de arranque y de emergencia quedan fuera de Git.
4. Manifiestos de ejecución (Deployment, Service, PVCs, ConfigMap), solo después de que los nombres de imágenes y secretos estén confirmados. Sondas de readiness y liveness en un endpoint de salud real, solicitudes de recursos y el contexto de seguridad que requiere el nivel de seguridad de pods del namespace.
5. La señal de las 3 am (abajo), en el mismo cambio que la carga de trabajo.
6. La ruta, al final, una vez que la imagen se ejecuta, los secretos se resuelven y las sondas pasan (ver Exposición).
7. Un README.md en la carpeta de la aplicación: qué es, sus dependencias de ejecución, sus nombres de secretos, su almacenamiento, cómo se accede.

Convenciones (el perfil tiene los valores)

• Imágenes: fija tag@sha256:<digest> a menos que el perfil indique que la aplicación sigue una etiqueta móvil; las imágenes propias vienen del registro del perfil con etiquetas inmutables. Las imágenes privadas necesitan el patrón de pull-secret del perfil.
• Secretos: recursos ExternalSecret contra el ClusterSecretStore del perfil, nunca datos Secret en línea.
• Almacenamiento: las clases de almacenamiento del perfil y para qué sirve cada una (volúmenes de bloque pequeños replicados vs datos masivos en NFS). Los límites de capacidad en el perfil son límites estrictos.
• Enrutamiento: gateways públicos e internos y sus patrones de host; TCP/UDP puro a través de un Service LoadBalancer.
• Copia la forma de las Aplicaciones de referencia del perfil en lugar de inventar una nueva.

La señal de las 3 am

Pregunta antes de enviar: si esta aplicación se rompiera a las 3 am, ¿cómo lo sabría alguien, y qué mirarían primero?

• La aplicación debe estar cubierta por una alerta que llegue a una persona: añade su namespace y carga de trabajo a las reglas de alerta de Monitorización del perfil (réplicas no disponibles, bucles de crash, pods o PVCs pendientes), o añade una regla específica de la aplicación si tiene un modo de fallo que esas no pueden ver (una cola que deja de drenarse, un job que deja de ejecutarse, un certificado o token que expira).
• Los logs de la aplicación deben indicar qué falló con los IDs que lo localizan; si la imagen es nuestra y no lo hacen, eso es una tarea.
• Escribe la señal en el mensaje del commit: 3 am: <nombre de alerta> vía <receptor>.

Exposición

No añadas una ruta pública hasta que la aplicación se ejecute, sus secretos se resuelvan y sus comprobaciones de salud pasen. Las herramientas solo internas se conectan únicamente al gateway interno y no reciben ruta pública. Cuando expongas públicamente, sigue las Habilidades relacionadas del perfil para la ruta de entrada pública (DNS, túnel, certificados).

Después de la incorporación (verifica, no asumas)

1. Envía; observa que la nueva aplicación aparezca y converja (kubectl get applications.argoproj.io -n argocd, o los comandos de Verificación del perfil). Solicita un refresh para saltar el retardo de sondeo si el perfil muestra cómo.
2. Comprueba: aplicación Synced y Healthy, cada ExternalSecret SecretSynced, pods listos, la ruta responde y la regla de alerta está cargada (aparece en la lista de reglas del stack de monitorización).
3. Si no converge, recorre la cadena de arriba abajo: listas blancas → secretos → errores de sincronización de ArgoCD → pods → enrutamiento. Las listas blancas suelen ser las culpables. Las Habilidades relacionadas del perfil nombran la habilidad de diagnóstico del clúster.