Unidad 5.3: GitOps y operaciones de despliegue

Introducción

Cuenta con una implementación funcional de TaskBoard en Managed Kubernetes, una pipeline de CI/CD que construye y publica imágenes, y Terraform que aprovisiona el clúster. El problema es la desviación. Alguien ejecuta kubectl edit para aplicar una corrección rápida a una implementación de producción, el estado en vivo se desvía de lo que hay en Git, y la siguiente ejecución de la pipeline la revierte silenciosamente o, peor aún, falla. GitOps resuelve esto al hacer que un repositorio Git sea la única fuente de verdad y al ejecutar un controlador dentro del clúster que obtiene continuamente el estado deseado y armoniza el estado en vivo para que coincida con él.

En esta unidad, configura ArgoCD en su clúster de MKS, lo conecta al repositorio de manifiestos de TaskBoard y observa cómo repara automáticamente los cambios manuales. Separa el repositorio que Terraform administra (el clúster, la red, las bases de datos) del repositorio que ArgoCD administra (manifiestos de Kubernetes), de modo que los dos controladores nunca se sobrescriban entre sí. Finalmente, automatiza la desinstalación de entornos por rama, de modo que una rama de función cree su propio espacio de nombres y lo desinstale al fusionar o cerrar.

1. Principios de GitOps y el bucle de reconciliación basado en la extracción

GitOps invierte la dirección habitual de despliegue. En lugar de que un ejecutor de CI empuje kubectl apply al clúster desde el exterior (modelo de empuje), un controlador que se ejecuta dentro del clúster extrae el estado deseado desde Git y lo aplica (modelo de extracción). El commit de Git es, al mismo tiempo, el disparador del despliegue, el registro de auditoría y el mecanismo de reversión. Para revertir, usted revierte el commit y el controlador reconcilia de vuelta al estado anterior.

Tres propiedades definen un sistema GitOps: todo el estado deseado es declarativo y se almacena en Git, el controlador compara continuamente el estado deseado con el estado en vivo, y cualquier divergencia (deriva) se informa o se corrige automáticamente. En IONOS CLOUD MKS, esto es importante porque el clúster ya ejecuta sus propios bucles de reconciliación durante la ventana de mantenimiento semanal, por lo que la reconciliación de su aplicación debe coexistir con los cambios impulsados por la plataforma.

1.1 Estado declarativo en Git

Todo lo que ArgoCD gestiona es YAML de Kubernetes plano, comprometido en un repositorio. No hay kubectl run imperativo en un flujo de trabajo GitOps. Un manifiesto de despliegue mínimo de TaskBoard se ve así:

# apps/taskboard/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: taskboard-api
  namespace: taskboard
spec:
  replicas: 2
  selector:
    matchLabels:
      app: taskboard-api
  template:
    metadata:
      labels:
        app: taskboard-api
    spec:
      imagePullSecrets:
        - name: cr-pull-secret
      containers:
        - name: api
          image: my-registry.cr.de-fra.ionos.com/taskboard-api:GIT_SHA
          ports:
            - containerPort: 8080
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 5

La etiqueta image contiene un SHA de git en lugar de latest. Este es el mecanismo de promoción: cambiar la etiqueta en Git es lo que desencadena una nueva implementación, y la etiqueta le indica exactamente qué commit está en ejecución.

1.2 Detección de desviación y autoarreglo

Cuando alguien ejecuta kubectl scale deployment/taskboard-api --replicas=5 directamente contra el clúster, el estado en vivo ya no coincide con Git, que sigue indicando replicas: 2. Un controlador de GitOps en modo de autoarreglo detecta esta diferencia en su próximo ciclo de sincronización y reduce la escala a 2. La lección operativa para su equipo es la siguiente: el clúster es de solo lectura para las personas. Todos los cambios se realizan a través de una solicitud de extracción.

# This manual change will be reverted by ArgoCD self-heal
kubectl -n taskboard scale deployment/taskboard-api --replicas=5

# Within the sync interval, ArgoCD reports OutOfSync, then heals back to 2
argocd app get taskboard --refresh

2. Instalación y configuración de ArgoCD en MKS

ArgoCD es un proyecto de CNCF, no un producto de IONOS CLOUD, por lo que se instala en MKS de la misma manera que en cualquier clúster de Kubernetes conforme. Las partes específicas de IONOS CLOUD son cómo se obtiene el kubeconfig, cómo se expone el servidor de ArgoCD (lo cual depende del modelo de LoadBalancer de MKS descrito en la sección 4) y cómo se autentican las extracciones de imágenes contra IONOS CLOUD Container Registry.

2.1 Obtención del kubeconfig e instalación de ArgoCD

Se aprovisiona el clúster con Terraform y se obtiene el kubeconfig antes de instalar cualquier componente. IONOS CLOUD documenta tres vías de gestión de configuración para obtener el archivo kubeconfig: la CLI ionosctl, Ansible y Terraform. Con Terraform, la fuente de datos ionoscloud_k8s_cluster expone el kubeconfig como un atributo que puede escribirse en un archivo.

data "ionoscloud_k8s_cluster" "taskboard" {
  id = ionoscloud_k8s_cluster.taskboard.id
}

resource "local_file" "kubeconfig" {
  content         = data.ionoscloud_k8s_cluster.taskboard.kube_config
  filename        = "${path.module}/kubeconfig.yaml"
  file_permission = "0600"
}

Con el kubeconfig configurado, instale ArgoCD en su propio espacio de nombres:

export KUBECONFIG=./kubeconfig.yaml

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Wait for the API server to come up on the worker nodes
kubectl -n argocd rollout status deployment/argocd-server

Los pods de ArgoCD se programan en sus nodos de trabajo de MKS. Los componentes del plano de control que IONOS CLOUD administra (el servidor de API de K8s, CSI, CCM, Calico y CoreDNS) se actualizan mediante IONOS CLOUD durante el mantenimiento y no son algo con lo que ArgoCD interactúe.

2.2 Definición de la CRD de la aplicación

El objeto principal de ArgoCD es el recurso personalizado Application. Apunta a un repositorio Git, a una ruta dentro de él y a un clúster y espacio de nombres de destino. automated con prune y selfHeal es lo que lo convierte en un verdadero ciclo de GitOps: prune elimina los recursos que se han quitado de Git, y selfHeal revierte los cambios manuales en el clúster.

# argocd/taskboard-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: taskboard
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/taskboard-manifests.git
    targetRevision: main
    path: overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: taskboard
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Aplicelo con kubectl apply -n argocd -f argocd/taskboard-app.yaml. A partir de este punto, cada commit en la ruta overlays/prod desencadena la reconciliación.

3. Topología de repositorios: Separación de la infraestructura de las aplicaciones

El error más común de GitOps en IONOS CLOUD es mezclar la infraestructura gestionada por Terraform y las aplicaciones gestionadas por ArgoCD en un solo lugar, y luego ver cómo entran en conflicto. El patrón limpio consiste en dos repositorios con un límite de propiedad claro.

El repositorio de infraestructura contiene Terraform: ionoscloud_k8s_cluster, ionoscloud_k8s_node_pool, redes, bases de datos y el Container Registry. Se aplica al fusionar en main a través de su pipeline de CI. El repositorio de aplicaciones contiene manifiestos de Kubernetes y superposiciones de Kustomize, y ArgoCD lo supervisa.

3.1 Límite de propiedad

La regla es sencilla: si un recurso es creado por terraform apply, ArgoCD nunca debe gestionarlo, y si un recurso es creado por la sincronización de ArgoCD, Terraform nunca debe gestionarlo. La transición se produce a través de las salidas. Terraform genera el clúster y el secreto de extracción del registro; ArgoCD consume el clúster y despliega en él.

# infrastructure repo: outputs that the app layer consumes
output "k8s_cluster_id" {
  value = ionoscloud_k8s_cluster.taskboard.id
}

output "registry_hostname" {
  value     = ionoscloud_container_registry.taskboard.hostname
  sensitive = false
}

La siguiente tabla establece explícitamente el límite para TaskBoard.

Como se muestra arriba, los controladores nunca comparten un tipo de recurso, por lo que ninguno revierte al otro.

3.2 La transferencia de imagePullSecret

El Container Registry en IONOS CLOUD utiliza únicamente docker login basado en tokens; no hay RBAC ni repositorios por equipo. El secreto de extracción es la única credencial que cruza el límite de infraestructura a aplicación. Crée una vez a partir del token del registro y luego refiérase a él en los manifiestos que ArgoCD sincroniza.

kubectl create secret docker-registry cr-pull-secret \
  --docker-server=my-registry.cr.de-fra.ionos.com \
  --docker-username='<token-name>' \
  --docker-password='<registry-token>' \
  --namespace=taskboard

Dado que este secreto contiene una credencial, no lo commite en texto plano. Cree de forma imperativa, como se muestra arriba (una sola vez, fuera de Git) o utilice un operador de sealed-secrets o external-secrets para que ArgoCD pueda gestionar una forma cifrada.

4. Riesgos específicos de conciliación en IONOS CLOUD

GitOps asume que el clúster se comporta de manera predecible. Dos comportamientos de MKS rompen esa suposición si no se planifican: los Node son inmutables y se reconstruyen en lugar de aplicarse parches, y un Servicio LoadBalancer no aprovisiona un balanceador de carga externo auténtico.

4.1 Node inmutables y la ventana de mantenimiento

Los Node de MKS son inmutables. Cualquier actualización de un grupo de Node reconstruye cada Node que pertenece al grupo, en lugar de aplicar un parche en el lugar, y las actualizaciones generalmente se producen automáticamente durante la ventana de mantenimiento semanal. Dicha ventana de mantenimiento está limitada a un máximo de 4 horas. Durante esta ventana, IONOS CLOUD actualiza todos los componentes dentro del clúster, incluyendo el plano de control, CSI, CCM, Calico y CoreDNS.

La implicación para GitOps es que los pods son expulsados y reprogramados en Node recién construidos según un horario que usted no controla. Sus manifiestos deben tolerar esto. Configure sondas de preparación para que ArgoCD y los Servicios dirijan el tráfico solo a pods en estado de listo, y utilice un PodDisruptionBudget para que la reconstrucción no deje todos los réplicas fuera de servicio a la vez.

# Survive node rebuilds during the maintenance window
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: taskboard-api
  namespace: taskboard
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: taskboard-api

Una reconstrucción también requiere margen de cuota de servidores: una reconstrucción de Node aprovisiona un nuevo Node antes de eliminar el antiguo, por lo que si ha agotado la cuota de servidores de su contrato, la reconstrucción no podrá completarse. Mantenga un margen de cuota igual a al menos un Node por pool.

4.2 La trampa del servicio LoadBalancer

Este es el peligro que sorprende a la mayoría de los equipos que exponen ArgoCD o TaskBoard. En MKS, un Service de type: LoadBalancer no es un balanceador de carga externo auténtico. IONOS CLOUD reserva una IP pública estática y la asigna como IP secundaria a un Node de trabajo, que actúa como Node de entrada, y kube-proxy aplica NAT al tráfico hacia el pod de destino. La IP de origen se pierde a menos que configure externalTrafficPolicy: Local, y el rendimiento está limitado al tope público de 2 Gbit/s de ese único Node de entrada.

apiVersion: v1
kind: Service
metadata:
  name: taskboard-api-lb
  namespace: taskboard
spec:
  type: LoadBalancer
  externalTrafficPolicy: Local   # preserve client source IP
  selector:
    app: taskboard-api
  ports:
    - port: 443
      targetPort: 8080

Para superar el límite de un solo Node, escale horizontalmente en múltiples IPs de LoadBalancer y nodos de entrada mediante equilibrio de carga de DNS, o coloque el servicio detrás de un ALB administrado aprovisionado de forma independiente (aprovisionado en el repositorio de infraestructura mediante Terraform, nunca creado automáticamente desde un manifiesto). Para el tráfico de TaskBoard en producción, la ruta del ALB es la solución adecuada y mantiene la gestión de la entrada en la capa administrada por Terraform.

5. Promoción de entornos y desmontaje efímero

La promoción entre entornos es una operación de Git, no un script de despliegue. Con Kustomize, una base compartida contiene los manifiestos y cada entorno es una superposición que modifica las cantidades de réplicas, los límites de recursos y la etiqueta de la imagen.

5.1 Superposiciones de Kustomize

La base define TaskBoard una sola vez; las superposiciones lo diferencian por entorno. Promover una compilación de staging a production es un cambio de una línea en la etiqueta de la imagen en la superposición de prod, que se confirma a través de una solicitud de extracción.

# overlays/prod/kustomization.yaml
resources:
  - ../../base
namespace: taskboard
images:
  - name: my-registry.cr.de-fra.ionos.com/taskboard-api
    newTag: 1a2b3c4   # promoted git SHA
patches:
  - path: replicas-patch.yaml

Cada Application de ArgoCD apunta a una ruta de superposición diferente (overlays/dev, overlays/staging, overlays/prod), por lo que el mismo repositorio gestiona los tres entornos y la diferencia entre ellos es auditable en Git.

5.2 Entornos efímeros de ramas y desmontaje

Para las ramas de características, usted inicia un entorno desechable y lo desmonta al fusionar o al cerrar la rama. Los recursos aprovisionados con Terraform generan cargos desde el momento de la aplicación, por lo que el desmontaje automatizado es una gobernanza de costos, no una comodidad. El trabajo de CI llama a terraform destroy para la pila de la rama.

# .github/workflows/teardown.yml (triggered on PR close)
name: teardown-branch-env
on:
  pull_request:
    types: [closed]
jobs:
  destroy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Terraform destroy branch stack
        env:
          IONOS_TOKEN: ${{ secrets.IONOS_TOKEN }}
        run: |
          terraform init -backend-config="key=env/pr-${{ github.event.number }}.tfstate"
          terraform destroy -auto-approve -var="env_name=pr-${{ github.event.number }}"

Un problema de limpieza específico del almacenamiento MKS es el siguiente: los volúmenes de IONOS CLOUD se representan como recursos PersistentVolume en Kubernetes, y la política de recuperación del PV determina lo que ocurre con el volumen subyacente cuando se elimina la solicitud. Si la política de recuperación es Retain, eliminar el espacio de nombres o ejecutar terraform destroy en el clúster deja volúmenes huérfanos de IONOS CLOUD en su VDC que continúan generando cargos. Establezca la política de recuperación como Delete para entornos efímeros o limpie explícitamente los volúmenes restantes después del desmontaje.

Tarjeta rápida de referencia de API

Puntos finales de API clave para operaciones de GitOps y despliegue en MKS:

URL base: https://api.ionos.com/cloudapi/v6 Autenticación: Authorization: Bearer <token>

Laboratorio de código

Objetivo: Configurar la sincronización automática de ArgoCD para los manifiestos de TaskBoard en MKS, aplicar un cambio en un manifiesto y observar cómo la reconciliación lo corrige, y luego eliminar un entorno de rama.

Requisitos previos:

• Cuenta de IONOS CLOUD con token de API
• Un clúster MKS en ejecución aprovisionado mediante Terraform (de la Unidad 3.2)
• kubectl, CLI de argocd y Terraform instalados localmente
• Un repositorio Git que contenga los manifiestos de TaskBoard

Paso 1: Obtener el kubeconfig desde Terraform

terraform output -raw kubeconfig > kubeconfig.yaml
export KUBECONFIG=./kubeconfig.yaml
kubectl get nodes

Salida esperada:

NAME                STATUS   ROLES    AGE   VERSION
taskboard-pool-1    Ready    <none>   12m   v1.34.x
taskboard-pool-2    Ready    <none>   12m   v1.34.x

Paso 2: Instalar ArgoCD

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl -n argocd rollout status deployment/argocd-server

Salida esperada:

deployment "argocd-server" successfully rolled out

Paso 3: Crear el CRD de la aplicación que apunta a los manifiestos de TaskBoard

kubectl apply -n argocd -f argocd/taskboard-app.yaml
argocd app get taskboard

Salida esperada:

Name:               argocd/taskboard
Sync Status:        Synced to main (1a2b3c4)
Health Status:      Healthy

Paso 4: Introducir deriva manualmente

kubectl -n taskboard scale deployment/taskboard-api --replicas=5
kubectl -n taskboard get deploy taskboard-api

Salida esperada:

NAME            READY   UP-TO-DATE   AVAILABLE
taskboard-api   5/5     5            5

Paso 5: Observe cómo ArgoCD se recupera por sí mismo hacia el estado declarado en Git

argocd app get taskboard --refresh
sleep 30
kubectl -n taskboard get deploy taskboard-api

Salida esperada:

NAME            READY   UP-TO-DATE   AVAILABLE
taskboard-api   2/2     2            2

Paso 6: Promover una nueva imagen mediante un commit de Git

# In the manifests repo, update overlays/prod/kustomization.yaml newTag
git commit -am "promote taskboard-api to 9f8e7d6"
git push origin main
argocd app wait taskboard --sync

Salida esperada:

taskboard   Synced   Healthy

Paso 7: Desmontar un entorno de rama

terraform init -backend-config="key=env/pr-42.tfstate"
terraform destroy -auto-approve -var="env_name=pr-42"

Salida esperada:

Destroy complete! Resources: 7 destroyed.

Paso 8: Verificar que no queden volúmenes huérfanos

ionosctl volume list --datacenter-id $DC_ID

Salida esperada:

No volumes found  (or: only volumes belonging to retained environments)

Lista de verificación:

• [ ] ArgoCD informa Synced y Healthy para TaskBoard
• [ ] El cambio manual de escala se revierte mediante la auto-reparación dentro del intervalo de sincronización
• [ ] El commit de la etiqueta de imagen desencadena una implementación sin ningún kubectl apply
• [ ] terraform destroy elimina la pila de ramas y no deja volúmenes de facturación

Limpieza:

kubectl delete -n argocd -f argocd/taskboard-app.yaml
kubectl delete namespace argocd
terraform destroy -auto-approve

Errores comunes

Errores de desarrollo a evitar con GitOps y operaciones de despliegue en IONOS CLOUD:

1. Terraform y ArgoCD en conflicto por el mismo recurso

   • Problema: Terraform gestiona un Service de Kubernetes mientras que ArgoCD también lo sincroniza desde Git. Cada apply y cada sincronización revierte los cambios del otro, produciendo un bucle de conflicto continuo y recursos inestables.
   • Por qué ocurre: No hay un límite claro de propiedad entre el repositorio de infraestructura y el repositorio de la aplicación.
   • Solución: Hacer que Terraform sea propietario únicamente de la infraestructura de IONOS CLOUD (clúster, grupos de nodos, registro, bases de datos) y que ArgoCD sea propietario únicamente de los manifiestos dentro del clúster. Pasar el clúster y el registro entre ellos a través de las salidas de Terraform, nunca gestionando ambos el mismo objeto.

2. Exponer ArgoCD o TaskBoard con type: LoadBalancer y esperar un LB real

   • Problema: Todo el tráfico llega a un solo nodo de trabajo, se pierde la IP de origen del cliente y el rendimiento se estanca alrededor de 2 Gbit/s sin una causa evidente.
   • Por qué ocurre: Un Service MKS LoadBalancer no aprovisiona un equilibrador de carga externo. IONOS CLOUD asigna una IP pública estática como IP secundaria a un solo nodo de entrada y kube-proxy aplica NAT al pod.
   • Solución: Establecer externalTrafficPolicy: Local para preservar la IP de origen, y para producción colocar un Managed ALB aprovisionado por separado desde la capa de Terraform frente al service, en lugar de depender del Service de un solo nodo.

3. Volúmenes de IONOS CLOUD huérfanos tras la desmontaje de un entorno de rama

   • Problema: Usted terraform destroy un entorno de rama pero sigue recibiendo facturas, y los volúmenes sobrantes permanecen en el VDC.
   • Por qué ocurre: Los volúmenes de IONOS CLOUD respaldan PersistentVolumes cuya política de recuperación es Retain, por lo que eliminar la solicitud o el espacio de nombres deja el volumen subyacente atrás.
   • Solución: Usar un StorageClass con política de recuperación Delete para entornos efímeros, o añadir un paso de desmontaje que liste y elimine los volúmenes restantes con ionosctl volume list y ionosctl volume delete.

Resumen

Ahora puede ejecutar un flujo de trabajo GitOps basado en extracción (pull) de forma nativa en IONOS CLOUD Managed Kubernetes. ArgoCD reconcilia el estado declarado de TaskBoard desde Git, corrige de forma autónoma las desviaciones manuales y promueve las compilaciones a través de los entornos mediante un único commit de etiqueta de imagen. Mantiene Terraform y ArgoCD en repositorios separados con un límite de propiedad claro, de modo que los dos controladores nunca se sobrescriban entre sí. También conoce los dos comportamientos de MKS que rompen las suposiciones ingenuas de GitOps y cómo diseñar alrededor de ellos.

La ventaja operativa es que la producción ahora es de solo lectura para los humanos, cada cambio es un commit revisable y la reversión es un git revert. Los entornos de rama son desechables y se desmontan por sí mismos, y evita la trampa de facturación por volúmenes huérfanos estableciendo la política de recuperación adecuada.

Puntos clave:

• GitOps utiliza un modelo de extracción (pull): un controlador dentro del clúster reconcilia el estado deseado de Git, lo que convierte a los commits en el mecanismo de activación de despliegues y de reversión
• Separe el repositorio de infraestructura propiedad de Terraform del repositorio de aplicaciones propiedad de ArgoCD para evitar bucles de conflicto de reconciliación
• Los nodos de MKS son inmutables y se reconstruyen durante la ventana de mantenimiento semanal (máximo 4 horas); utilice PodDisruptionBudgets y sondas de preparación para que los despliegues sobrevivan a las reconstrucciones
• Un servicio LoadBalancer de MKS no es un LB externo verdadero: un solo nodo de entrada, pérdida de la IP de origen a menos que se use externalTrafficPolicy: Local, y un límite de 2 Gbit/s; utilice un ALB administrado para producción
• Automatice terraform destroy para entornos de rama y establezca la política de recuperación de PV en Delete para evitar volúmenes huérfanos que sigan facturándose

Terminología importante:

• GitOps: Un modelo operativo en el que Git es la única fuente de verdad y un controlador dentro del clúster reconcilia continuamente el estado en vivo para que coincida con el estado declarativo commitado
• Desviación (Drift): Divergencia entre el estado en vivo del clúster y el estado deseado declarado en Git, causada por cambios manuales o procesos externos
• Autocuración (Self-heal): Un modo de sincronización de ArgoCD que revierte automáticamente los cambios en vivo al estado declarado en Git
• Política de recuperación: La configuración de PersistentVolume de Kubernetes (Retain o Delete) que determina si el volumen de IONOS CLOUD subyacente se elimina cuando se elimina su solicitud
• Nodo de entrada: El único nodo de trabajo de MKS que recibe la IP pública reservada de un servicio LoadBalancer como IP secundaria y aplica NAT al tráfico hacia los pods de destino

Próximos pasos

Continuar aprendiendo: Unidad 5.4: Verificación de conocimientos - Operaciones de producción

Temas relacionados:

• Unidad 3.3: Pipelines de CI/CD para IONOS CLOUD
• Unidad 5.2: Automatización de seguridad