Problema

Muchas organizaciones que migran a Kubernetes terminan con procesos manuales para dar de alta usuarios, asignar permisos y lanzar pipelines de despliegue. El onboarding de identidades suele tardar días porque cada solicitud implica crear objetos en Azure AD, configurar secretos en Key Vault y actualizar configuraciones en los gateways de API. Paralelamente, los equipos de CI/CD mantienen scripts ad‑hoc que no están versionados ni auditables. El patrón que se repite es la falta de un flujo declarativo que:

  1. Reciba una solicitud de nuevo cliente o proyecto.
  2. Provisione automáticamente recursos de identidad (grupos, roles, secretos).
  3. Actualice los manifiestos de Kubernetes y los charts de Helm que describen los componentes de la aplicación.
  4. Despliegue de forma reproducible con GitOps (ArgoCD) y CI (GitHub Actions).

Cuando estos pasos no están integrados, el tiempo de activación se dispara, los errores humanos se multiplican y el coste operativo crece sin control.

Causa

  1. Separación de dominios – IAM se gestiona en Azure mientras que la infraestructura de Kubernetes se define en repositorios Git. Sin una capa de orquestación, los cambios deben replicarse manualmente.
  2. Falta de GitOps – Los manifiestos de Kubernetes se editan directamente en clústers o se aplican con kubectl apply desde scripts locales, lo que rompe la trazabilidad.
  3. Pipelines estáticos – GitHub Actions o Jenkins usan variables hardcodeadas; cuando cambian credenciales o endpoints, se olvidan de actualizar los archivos, provocando fallos en producción.
  4. Ausencia de plantillas parametrizadas – Helm charts sin valores externos obligan a duplicar archivos YAML por cliente, aumentando la superficie de error.
  5. Control de versiones de secretos – Secretos creados manualmente en Azure Key Vault no están vinculados a los recursos de Kubernetes, lo que lleva a desincronizaciones.

Estos factores se combinan en entornos donde el número de clientes supera las decenas y la velocidad de entrega es crítica.

Solución

Implementar un flujo end‑to‑end declarativo que conecte Azure IAM, Key Vault y los manifiestos de Kubernetes mediante:

  1. Repositorio Git único que contenga:

    • Helm charts parametrizados (values.yaml con placeholders).
    • Plantillas de manifiestos de recursos de Kubernetes (Ingress, ServiceAccount, RoleBinding).
    • Scripts de Azure CLI (az) para crear grupos, asignar roles y generar secretos.

  2. GitHub Actions como motor de CI que:

    • Detecta cambios en la carpeta customers/<id>/ (nuevo cliente).
    • Ejecuta Azure CLI para crear recursos IAM y almacenar credenciales en Key Vault.
    • Genera un archivo values-<id>.yaml con los IDs y secretos recién creados.
    • Commitea el nuevo values al mismo repo y abre un Pull Request automático.

  3. ArgoCD configurado en modo App of Apps:

    • Una aplicación raíz que incluye una plantilla Application por cliente.
    • Cada PR que añada o modifique values-<id>.yaml dispara automáticamente la sincronización del chart correspondiente.

  4. Helm como capa de abstracción:

    • Define recursos comunes (Deployment, Service, Ingress) una sola vez.
    • Usa {{ .Values.iam.clientId }} y {{ .Values.secrets.apiKey }} para inyectar datos creados en Azure.

  5. Política de secret management:

    • Usa ExternalSecret (por ejemplo, el operador external-secrets) para leer directamente de Azure Key Vault y crear Secret de Kubernetes sin exponer valores en Git.

Paso a paso resumido

  1. Estructura del repo

    ├─ charts/
│   └─ app/
│       ├─ Chart.yaml
│       └─ templates/
├─ customers/
│   └─ 001/
│       └─ values.yaml
├─ .github/
│   └─ workflows/
│       └─ onboarding.yml
└─ argo/
    └─ root-app.yaml

  2. Workflow de GitHub Actions (onboarding.yml)

    • Trigger: push en customers/**.
    • Jobs: azure-iam, generate-values, pr-create.

  3. Aplicación raíz de ArgoCD (root-app.yaml)

    • Usa helm como source y directory como path customers/*.

  4. Operador ExternalSecret

    • Configura SecretStore apuntando a Azure Key Vault.
    • En el chart, declara un ExternalSecret que tome client-secret y lo convierta en Secret.

Con este enfoque, la única acción manual es abrir el PR inicial con la información del cliente (nombre, dominio). El resto del proceso se ejecuta automáticamente, reduciendo el tiempo de onboarding de días a minutos.

Cuándo aplicar esta solución

  • Escala de clientes: Más de 10‑15 clientes simultáneos, donde la creación manual se vuelve insostenible.
  • Entorno Kubernetes productivo: Se usa Helm y ArgoCD para despliegues continuos.
  • Infraestructura en Azure: Necesitas crear grupos, aplicaciones y secretos en Azure AD/Key Vault.
  • Requisitos de auditoría: Cada cambio debe quedar registrado en Git y ser revisable mediante PR.

No es adecuada cuando:

  • El clúster es de prueba y solo se despliegan unas pocas aplicaciones.
  • No se dispone de permisos para crear recursos automatizados en Azure (políticas restrictivas).
  • El equipo prefiere herramientas propietarias de CI/CD que no se integran con GitHub Actions.

Código

# 1. Crear grupo de Azure AD y asignar rol
az ad group create --display-name "client-${CLIENT_ID}" --mail-nickname "client-${CLIENT_ID}"
az role assignment create --assignee "client-${CLIENT_ID}" --role "Contributor" --scope "/subscriptions/${SUB_ID}/resourceGroups/${RG}"

# 2. Generar secreto en Key Vault
SECRET=$(openssl rand -base64 32)
az keyvault secret set --vault-name "${KV_NAME}" --name "client-${CLIENT_ID}-api-key" --value "${SECRET}"

# 3. Generar values.yaml para Helm
cat <<EOF > customers/${CLIENT_ID}/values.yaml
iam:
  clientId: "$(az ad sp show --id http://client-${CLIENT_ID} --query appId -o tsv)"
secrets:
  apiKey: "${SECRET}"
EOF

Verificación

  1. Pipeline CI

    • Revisa que el workflow de GitHub Actions finalice sin errores y que el PR se haya creado.

  2. ArgoCD

    • En la UI de ArgoCD, la aplicación del cliente debe aparecer en estado Synced.
    • Verifica que los recursos Deployment, Service y Ingress tengan los valores de clientId y apiKey correctos (kubectl get deployment -n <ns> -o yaml | grep clientId).

  3. Secretos en Kubernetes

    • Ejecuta kubectl get secret client-${CLIENT_ID}-api-key -o yaml y confirma que el campo data contiene el valor codificado del secreto creado en Key Vault.

  4. Acceso de IAM

    • Usa Azure CLI para listar los miembros del grupo creado y comprobar que el Service Principal está asignado: az ad group member list --group "client-${CLIENT_ID}".

Si todos los pasos pasan, el flujo está operativo y listo para nuevos clientes.

Notas adicionales

  • Idempotencia: Los scripts de Azure CLI deben ser idempotentes; usa az ad group create con --only-show-errors y captura códigos de salida para evitar duplicados.
  • Rotación de secretos: Programa un workflow periódico que lea los secretos de Key Vault, los vuelva a generar y actualice los ExternalSecret sin tocar los charts.
  • Política de PR: Configura branch protection para que los cambios en customers/* requieran revisión, evitando despliegues accidentales.
  • Observabilidad: Añade métricas de ArgoCD (por ejemplo, argocd_app_sync_total) a tu stack de Prometheus para detectar fallos de sincronización rápidamente.
  • Escalado de ArgoCD: Cuando el número de clientes supera los cientos, considera usar AppProject para agrupar aplicaciones por entorno (dev, prod) y limitar el número de objetos que ArgoCD gestiona simultáneamente.