Unidad 5.3: GitOps y operaciones de implementación

Introducción

Usted tiene una implementación de TaskBoard en funcionamiento en Managed Kubernetes, una tubería CI/CD que construye y envía imágenes, y Terraform que aprovisiona el Cluster. El problema es la deriva. Alguien ejecuta kubectl edit para solucionar un problema en una implementación de producción, el estado en vivo se desvía de lo que está en Git, y la siguiente ejecución de la tubería revierte silenciosamente el cambio o, peor aún, falla. GitOps soluciona esto haciendo que un repositorio Git sea la única fuente de verdad y ejecutando un controlador dentro del Cluster que continúa extrayendo el estado deseado y reconciliando el estado en vivo para que coincida con él.

En esta unidad, usted configura ArgoCD en su MKS Cluster, lo conecta al repositorio de manifiestos de TaskBoard y lo observa mientras se autorepara los cambios manuales. Usted separa el repositorio que Terraform posee (el Cluster, la red, las bases de datos) del repositorio que ArgoCD posee (los manifiestos Kubernetes), para que los dos controladores nunca se sobrescriban entre sí. Finalmente, usted automatiza la eliminación de la rama-entorno, de modo que una rama de características active su propio espacio de nombres y lo elimine al fusionar o cerrar.

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

GitOps invierte la dirección de implementación habitual. En lugar de un ejecutor de CI que empuja kubectl apply hacia el Cluster desde el exterior (modelo de empuje), un controlador que se ejecuta dentro del Cluster extrae el estado deseado de Git y lo aplica (modelo de extracción). El compromiso de Git es el desencadenador de implementación, el registro de auditoría y el mecanismo de reversión todo al mismo tiempo. Para revertir, se revierte el compromiso y el controlador vuelve a reconciliar con el estado anterior.

Tres propiedades definen un sistema GitOps: el estado deseado completo 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 MKS esto es importante porque el Cluster ya ejecuta bucles de reconciliación propios 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 un archivo Kubernetes YAML plano comprometido en un repositorio. No hay código kubectl run imperativo en un flujo de trabajo de GitOps. Un manifiesto de implementación de TaskBoard mínimo 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 lleva un SHA de Git en lugar de latest. Esto es el mecanismo de promoción: cambiar la etiqueta en Git es lo que desencadena una nueva implementación, y la etiqueta le dice exactamente qué compromiso se está ejecutando.

1.2 Detección de deriva y auto-curación

Cuando alguien ejecuta kubectl scale deployment/taskboard-api --replicas=5 directamente contra el Cluster, el estado en vivo ya no coincide con Git, que todavía dice replicas: 2. Un controlador de GitOps en modo de auto-curación detecta esta diferencia en su próximo ciclo de sincronización y vuelve a escalar hacia abajo a 2. La lección para su equipo es operativa: el Cluster es de solo lectura para los humanos. 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, por lo que se instala en MKS de la misma manera que se instala en cualquier Kubernetes Cluster conforme. Las partes específicas de IONOS son cómo obtener el kubeconfig, cómo se expone el servidor ArgoCD (que depende del modelo LoadBalancer de MKS cubierto en la Sección 4) y cómo las imágenes se autenticen contra el Registro de contenedores de IONOS.

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

Usted proporciona el Cluster con Terraform y recupera el kubeconfig antes de instalar cualquier cosa. IONOS documenta tres rutas de administración de configuración para recuperar el archivo kubeconfig: la CLI ionosctl, Ansible y Terraform. Con Terraform, el origen de datos ionoscloud_k8s_cluster expone el kubeconfig como un atributo que puede escribir 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 en su lugar, 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

El programa ArgoCD Pods se programa en su MKS Worker Nodes. Los componentes del plano de control que IONOS gestiona (el servidor K8s API, CSI, CCM, Calico y CoreDNS) se actualizan durante el mantenimiento y no son algo que ArgoCD modifique.

2.2 Definiendo la CRD de la aplicación

El objeto principal de ArgoCD es el Application de recurso personalizado. Apunta a un repositorio Git, una ruta dentro de él y un destino Cluster y espacio de nombres. automated sincroniza con prune y selfHeal es lo que lo convierte en un verdadero bucle GitOps: prune elimina los recursos eliminados de Git, y selfHeal revierte los cambios manuales Cluster.

# 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

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

3. Topología del repositorio: separación de la infraestructura de las aplicaciones

El error más común de GitOps en IONOS es mezclar la infraestructura gestionada por Terraform y las aplicaciones gestionadas por ArgoCD en un solo lugar, y luego ver cómo luchan. El patrón limpio es tener 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 Registro de contenedores. Se aplica en la unión a main a través de su tubería de CI. El repositorio de aplicaciones contiene manifiestos de Kubernetes y superposiciones de Kustomize, y ArgoCD lo observa.

3.1 Límite de propiedad

La regla es simple: 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 entrega se produce a través de salidas. Terraform produce el Cluster y el secreto de extracción del registro; ArgoCD consume el Cluster y lo despliega.

# 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 el límite explícitamente para TaskBoard.

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

3.2 La entrega del secreto de extracción de imagen

El Registro de contenedores en IONOS utiliza un token de autenticación basado en docker login solamente; no hay RBAC y no hay repositorios por equipo. El secreto de extracción es la única credencial que cruza el límite de infraestructura a aplicación. Créelo una vez a partir del token de registro, luego hágalo referencia en 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

Como este secreto contiene una credencial, no lo comite en texto plano. Créelo imperativamente como se muestra arriba (una vez, fuera de Git) o utilice un operador de secretos sellados o externos para que ArgoCD pueda gestionar una forma cifrada.

4. Peligros de Reconciliación Específicos de IONOS

GitOps asume que el Cluster se comporta de manera predecible. Dos comportamientos de MKS rompen esa suposición si no se planean: los nodos son inmutables y se reconstruyen en lugar de parchearse, y un LoadBalancer Service no proporciona un verdadero Load Balancer externo.

4.1 Nodos Inmutables y la Ventana de Mantenimiento

Los nodos de MKS son inmutables. Cualquier actualización del grupo de Node reconstruye cada Node que pertenece al grupo en lugar de parchearlo en su lugar, y las actualizaciones suelen ocurrir automáticamente durante la ventana de mantenimiento semanal. Esa ventana de mantenimiento está limitada a un máximo de 4 horas. Durante esta ventana, IONOS actualiza todos los componentes dentro de Cluster, incluyendo el plano de control, CSI, CCM, Calico y CoreDNS.

La implicación de GitOps es que los Pods son expulsados y vuelven a programarse en nodos recién construidos según un calendario que no controla. Sus manifestos deben tolerar esto. Establezca sondas de preparación para que ArgoCD y Services enrutén tráfico solo a Pods listos, y utilice un PodDisruptionBudget para que la reconstrucción no retire todas las réplicas al mismo tiempo.

# 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 holgura en la cuota del servidor: una reconstrucción de Node proporciona un nuevo Node antes de eliminar el antiguo, así que si ha agotado la cuota de servidores de su contrato, la reconstrucción no puede completarse. Mantenga una holgura en la cuota igual a al menos un Node por grupo.

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 verdadero Load Balancer externo. IONOS Cloud reserva una dirección IP pública estática y la asigna como una dirección IP secundaria a un Node de trabajador, que actúa como el Node de ingreso, y kube-proxy NATs el tráfico al pod objetivo. La dirección IP de origen se pierde a menos que establezca externalTrafficPolicy: Local, y el rendimiento está limitado en el techo público de 2 Gbit/s de ese único Node de ingreso.

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 techo de un solo Node, escalar horizontalmente a través de múltiples direcciones IP de LoadBalancer y nodos de ingreso utilizando DNS de equilibrio de carga, o frente al servicio con un ALB administrado separadamente (provisionado en el repositorio de infraestructura a través de Terraform, nunca creado automáticamente a partir de un manifiesto). Para el tráfico de producción de TaskBoard, el camino ALB es la respuesta correcta y mantiene la preocupación de ingreso en la capa propiedad de Terraform.

5. Promoción de entorno y desmantelamiento efímero

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

5.1 Superposiciones de Kustomize

La base define TaskBoard una vez; las superposiciones se diferencian por entorno. Promover una compilación desde la etapa de prueba a producción es un cambio de una línea de etiqueta de imagen en la superposición de producción, comprometido 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 ArgoCD Application apunta a una ruta de superposición diferente (overlays/dev, overlays/staging, overlays/prod), por lo que el mismo repositorio impulsa los tres entornos y la diferencia entre ellos es audible en Git.

5.2 Entornos de ramas efímeras y desmantelamiento

Para las ramas de características, usted crea un entorno desechable y lo desmantela en la unión o cierre de la rama. Los recursos aprovisionados por Terraform incurran en cargos desde el momento de la aplicación, por lo que el desmantelamiento automatizado es gobernanza de costos, no una comodidad. El trabajo de CI llama 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 }}"

Una trampa de limpieza específica para el almacenamiento de MKS es que los volúmenes de IONOS se representan como recursos de PersistentVolume en Kubernetes, y la política de reclamación de PV determina qué sucede con el Volume subyacente cuando se elimina la reclamación. Si la política de reclamación es Retain, eliminar el espacio de nombres o ejecutar terraform destroy en el Cluster deja volúmenes de IONOS huérfanos en su VDC que siguen facturando. Establezca la política de reclamación en Delete para entornos efímeros o limpie explícitamente los volúmenes sobrantes después de la desmantelación.

API Tarjeta de referencia rápida

Puntos de conexión clave de API para GitOps y operaciones de implementación en MKS:

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

Laboratorio de código

Objetivo: Configurar ArgoCD auto-sync para manifestos de TaskBoard en MKS, realizar un cambio en el manifesto y observar cómo la reconciliación lo soluciona, y luego desmantelar un entorno de rama.

Requisitos previos:

• Cuenta de IONOS Cloud con token API
• Un MKS Cluster en ejecución provisionado a través de Terraform (de la Unidad 3.2)
• kubectl, argocd CLI, y Terraform instalados localmente
• Un repositorio de Git que contiene manifestos de TaskBoard

Paso 1: Recuperar el kubeconfig de 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 la CRD de Aplicación que apunta a los manifestos 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: Observar cómo ArgoCD se auto-repara hacia el estado declarado por 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 a través de un compromiso 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: Desmantelar 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 de escala manual es revertido por la auto-reparación dentro del intervalo de sincronización
• [ ] El compromiso de la etiqueta de imagen desencadena una implementación sin ningún kubectl apply
• [ ] terraform destroy elimina la pila de la rama 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 los desarrolladores que deben evitarse con GitOps y operaciones de implementación en IONOS:

1. Terraform y ArgoCD luchando por el mismo recurso

   • Problema: Terraform administra un servicio Kubernetes mientras que ArgoCD también lo sincroniza desde Git. Cada apply y cada sincronización revierten la otra, produciendo un bucle de lucha interminable y recursos que fluctúan.
   • Por qué sucede: No hay una clara delimitación de propiedad entre el repositorio de infraestructura y el repositorio de aplicación.
   • Solución: Hacer que Terraform sea propietario solo de la infraestructura de IONOS (Cluster, Node Pools, registro, bases de datos) y que ArgoCD sea propietario solo de los manifiestos dentro de Cluster. Pasar Cluster y el registro entre ellos a través de las salidas de Terraform, nunca administrando el mismo objeto por ambos.

2. Exponer ArgoCD o TaskBoard con type: LoadBalancer y esperar un equilibrio de carga real

   • Problema: Todo el tráfico aterriza en un trabajador Node, se pierde la fuente del cliente IP y el rendimiento se estanca alrededor de 2 Gbit/s sin causa aparente.
   • Por qué sucede: Un servicio MKS LoadBalancer no provisiona un Load Balancer externo. IONOS asigna una dirección IP pública estática como una dirección IP secundaria a un solo ingreso Node y kube-proxy NAT a la cápsula.
   • Solución: Establecer externalTrafficPolicy: Local para preservar la fuente IP, y para la producción, frente al servicio con un ALB administrado separadamente provisionado desde la capa Terraform en lugar de confiar en el servicio Node único.

3. Volúmenes de IONOS huérfanos después de la eliminación del entorno de rama

   • Problema: Usted terraform destroy un entorno de rama pero sigue recibiendo facturas, y los volúmenes extraños perduran en el VDC.
   • Por qué sucede: Los volúmenes de IONOS respaldan PersistentVolumes cuya política de reclamación es Retain, por lo que eliminar la reclamación o el espacio de nombres deja el Volume subyacente detrás.
   • Solución: Utilizar una clase de almacenamiento con política de reclamación Delete para entornos efímeros, o agregar un paso de eliminación que enumere y elimine los volúmenes restantes con ionosctl volume list y ionosctl volume delete.

Resumen

Ahora puede ejecutar un flujo de trabajo de GitOps basado en extracción en IONOS Managed Kubernetes. ArgoCD reconcilia el estado declarado de TaskBoard desde Git, se auto-repara en caso de desviación manual y promueve compilaciones a través de entornos con un solo compromiso de etiqueta de imagen. Usted mantiene Terraform y ArgoCD en repositorios separados con un límite de propiedad limpio, por lo que los dos controladores nunca se sobrescriben entre sí. También conoce los dos comportamientos de MKS que rompen las suposiciones de GitOps ingenuas y cómo diseñar alrededor de ellos.

El beneficio operativo es que la producción ahora es de solo lectura para los humanos, cada cambio es un compromiso revisable y la reversión es un git revert. Los entornos de rama son desechables y se desmontan solos, y evita la trampa de facturación de Volume huérfano estableciendo la política de reclamación correcta.

Puntos clave:

• GitOps utiliza un modelo de extracción: un controlador dentro de la Cluster reconcilia el estado deseado de Git, haciendo que los compromisos sean el desencadenador de implementación y mecanismo de reversión
• Separe el repositorio de infraestructura propiedad de Terraform del repositorio de aplicación propiedad de ArgoCD para evitar bucles de lucha de reconciliación
• Los nodos de MKS son inmutables y se reconstruyen durante la ventana de mantenimiento semanal (máximo 4 horas); use PodDisruptionBudgets y sondas de preparación para que las implementaciones sobrevivan a las reconstrucciones
• Un servicio de MKS LoadBalancer no es un verdadero equilibrador de carga externo: una entrada Node, fuente IP perdida a menos que externalTrafficPolicy: Local, y un techo de 2 Gbit/s; use un ALB administrado para producción
• Automatice terraform destroy para entornos de rama y establezca la política de reclamación de PV en Delete para evitar volúmenes huérfanos que siguen facturando

Terminología importante:

• GitOps: Un modelo de operación en el que Git es la única fuente de verdad y un controlador dentro de la Cluster reconcilia continuamente el estado en vivo para que coincida con el estado declarativo comprometido
• Desviación: Divergencia entre el estado en vivo de la Cluster y el estado deseado declarado en Git, causada por cambios manuales o procesos externos
• Auto-reparación: Un modo de sincronización de ArgoCD que automáticamente revierte los cambios en vivo hacia el estado declarado en Git
• Política de reclamación: La configuración de PersistentVolume de Kubernetes (Retain o Delete) que determina si el soporte de IONOS Volume se elimina cuando se elimina su reclamación
• Entrada Node: La única entrada de trabajador de MKS Node que recibe una dirección pública IP reservada de un servicio LoadBalancer como una dirección secundaria IP y NAT de tráfico a destino Pods

Próximos pasos

Continúe aprendiendo: Unidad 5.4: Verificación de conocimientos - Operaciones de producción

Temas relacionados:

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