15 min de lectura

Objetivos de aprendizaje

Al final de este módulo, podrás:

  • Instalar ArgoCD en Managed Kubernetes y desplegar TaskBoard desde Git con un `Application` que se sincronice automáticamente y se autorrepare
  • Dividir TaskBoard en un repositorio de infraestructura (Terraform, aplicar al fusionar) y un repositorio de aplicación (manifiestos, sincronización de ArgoCD)
  • Promover etiquetas de imagen desde dev a staging y luego a production mediante superposiciones de Kustomize y solicitudes de extracción
  • Crear y destruir entornos de rama automáticamente desde CI para mantener los costos bajo control
  • Establecer una línea clara de responsabilidad entre Terraform y ArgoCD para que las dos herramientas no compitan por el mismo objeto

Unidad 5.3: GitOps y operaciones de despliegue

Introducción

La canalización de TaskBoard de la Unidad 3.3 aplica cambios en el clúster: CI mantiene un kubeconfig y ejecuta kubectl set image. Esto funciona, pero el estado del clúster es el que dejó la última tarea, un kubectl edit manual permanece sin ser notado, y cada canalización necesita credenciales para el clúster.

GitOps invierte este enfoque. Git mantiene el estado deseado de la aplicación, y un agente dentro del clúster lo recupera y lo reconcilia de forma continua. Si alguien modifica un Deployment manualmente, el agente lo restaura. Si desea revertir, revierte un commit. En esta unidad, instala ArgoCD en MKS, lo conecta con los manifiestos de TaskBoard, estructura los repositorios, promueve liberaciones entre entornos y desmantela automáticamente los entornos de rama. También decide qué herramienta administra qué objeto, para que Terraform y ArgoCD no deshagan el trabajo del otro.

1. Principios de GitOps en la práctica

1.1 Push frente a Pull

Aspecto Push (Unidad 3.3) Pull (GitOps)
Quién modifica el clúster Tarea de CI con un kubeconfig Agente dentro del clúster
Fuente de verdad Última tarea exitosa Rama o etiqueta de Git
Cambio manual en el clúster Permanece hasta la próxima implementación Se detecta y se revierte
Reversión kubectl rollout undo git revert
Credenciales del clúster en CI Requeridas No requeridas

El modelo de pull también simplifica el acceso a la API de Kubernetes. Si lo restringió con api_subnet_allow_list (Unidad 3.2), cada ejecutor de CI externo debe estar en esa lista. ArgoCD se ejecuta dentro del clúster y se comunica con el servidor de API a través de https://kubernetes.default.svc, y el tráfico interno del clúster no se ve afectado por la lista de permitidos.

1.2 Detección de desviación

La desviación es cualquier diferencia entre Git y el estado en vivo. Ya detecta la desviación de infraestructura con terraform plan -detailed-exitcode (Unidad 5.2). ArgoCD hace lo mismo para los manifiestos:

argocd app diff taskboard-dev        # exit code 1 when live state differs from Git
argocd app get taskboard-dev -o json | jq -r '.status.sync.status, .status.health.status'

Synced y Healthy significan que el clúster coincide con Git y que todos los recursos superan sus comprobaciones de estado, incluidas las sondas de preparación de la Unidad 5.1.

2. ArgoCD en MKS

2.1 Instalación

kubectl create namespace argocd
kubectl apply -n argocd \
  -f "https://raw.githubusercontent.com/argoproj/argo-cd/${ARGOCD_VERSION}/manifests/install.yaml"
kubectl -n argocd rollout status deploy/argocd-server
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d

Fije ARGOCD_VERSION a una etiqueta de versión, exactamente de la misma manera que fija el proveedor de Terraform, y realice la actualización mediante una solicitud de extracción (pull request). Acceda a la interfaz de usuario con kubectl -n argocd port-forward svc/argocd-server 8080:443. No lo exponga con type: LoadBalancer: en MKS, ese servicio obtiene una dirección IP estática en un solo nodo, no un equilibrador de carga (Unidad 3.2). Si el equipo necesita acceso permanente, diríjalo a través del controlador de entrada (ingress controller) detrás del ALB.

2.2 Conexión del repositorio de la aplicación

apiVersion: v1
kind: Secret
metadata:
  name: taskboard-deploy-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://git.example.com/taskboard/deploy.git
  username: argocd
  password: <read-only access token>

Cree este Secret desde su almacén de secretos, como en la Unidad 5.2, y nunca desde un archivo en Git. ArgoCD solo necesita acceso de lectura; nunca realiza operaciones de empuje.

2.3 La CRD de Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: taskboard-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://git.example.com/taskboard/deploy.git
    targetRevision: main
    path: overlays/dev
  destination:
    server: https://kubernetes.default.svc
    namespace: taskboard
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

automated sincroniza cada nuevo commit en main. prune elimina los objetos que usted quitó de Git, y selfHeal revierte los cambios manuales en el clúster. ArgoCD aplica los manifiestos, pero no proporciona las credenciales del registro: los pods aún necesitan la entrada imagePullSecrets y el Secret de extracción de la Unidad 3.2, o permanecerán en ImagePullBackOff.

3. Topología del repositorio y promoción

3.1 Dos repositorios, dos propietarios

taskboard-infra/                 taskboard-deploy/
  modules/                         base/
    mks-cluster/                     api-deployment.yaml
    postgres/                        web-deployment.yaml
  envs/                              worker-deployment.yaml
    dev/main.tf                      kustomization.yaml
    staging/main.tf                overlays/
    prod/main.tf                     dev/kustomization.yaml
  .github/workflows/infra.yml        staging/kustomization.yaml
                                     prod/kustomization.yaml

taskboard-infra es el repositorio de infraestructura de la Unidad 3.3: planificar en la solicitud de extracción (pull request) y aplicar al fusionar (merge), con IONOS_TOKEN en sus secretos. taskboard-deploy contiene únicamente manifiestos de Kubernetes y no tiene credenciales de nube. El código fuente de la aplicación permanece en un tercer repositorio cuya CI construye y publica las imágenes.

3.2 Superposiciones y etiquetas de imagen

La superposición de producción, overlays/prod/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: taskboard
resources:
  - ../../base
images:
  - name: taskboard-api
    newName: <registry-hostname>/taskboard/api
    newTag: 3f9c2a1b7d04
replicas:
  - name: taskboard-api
    count: 3

Los manifiestos base hacen referencia a la imagen como taskboard-api, y cada superposición fija la etiqueta de SHA de Git de la Unidad 3.1. La promoción es un commit que copia una etiqueta probada de una superposición a la siguiente.

3.3 Promoción desde CI

La CI de la aplicación ya no interactúa con el clúster. Después de que publica la imagen, abre una solicitud de extracción (pull request) contra taskboard-deploy:

SHA="${GITHUB_SHA::12}"
git clone "https://x-access-token:${DEPLOY_REPO_TOKEN}@git.example.com/taskboard/deploy.git"
cd deploy/overlays/dev
kustomize edit set image "taskboard-api=${CR_HOST}/taskboard/api:${SHA}"
git checkout -b "promote-dev-${SHA}"
git commit -am "dev: taskboard-api ${SHA}"
git push origin "promote-dev-${SHA}"
gh pr create --title "dev: taskboard-api ${SHA}" --body "Automated promotion" --base main

Para el entorno de desarrollo, puede fusionar automáticamente una vez que las comprobaciones se aprueben. Para los entornos de staging y producción, exija una revisión, de modo que el historial de la pull request sea su registro de versiones. Una reversión es git revert del commit de promoción; ArgoCD sincroniza la etiqueta anterior.

4. Entornos de ramas y desmontaje automatizado

4.1 Un estado por rama

El flujo de trabajo .github/workflows/branch-env.yml en taskboard-infra:

on:
  pull_request:
    types: [opened, synchronize, closed]
jobs:
  env:
    runs-on: ubuntu-latest
    concurrency: branch-${{ github.head_ref }}
    defaults:
      run:
        working-directory: envs/branch
    env:
      IONOS_TOKEN: ${{ secrets.IONOS_TOKEN }}
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      TF_VAR_branch: ${{ github.head_ref }}
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init -input=false -backend-config="key=branches/${TF_VAR_branch}/terraform.tfstate"
      - if: github.event.action != 'closed'
        run: terraform apply -input=false -auto-approve
      - if: github.event.action == 'closed'
        run: terraform destroy -input=false -auto-approve

Cada pull request tiene su propio objeto de estado en el bucket de estado, por lo que un entorno de rama nunca puede tocar el estado de dev o production. Nombre cada recurso según var.branch y mantenga la pila de la rama pequeña: un bucket de Object Storage, una base de datos y un namespace en el clúster de dev compartido, no un clúster propio.

4.2 Desmontaje que realmente se ejecuta

Los recursos generan cargos desde el momento en que existen, y un entorno de rama olvidado cuesta dinero cada hora. La red de seguridad nocturna destruye los estados de ramas cuyo pull request está cerrado:

for key in $(aws s3 ls --endpoint-url "$EP" "s3://taskboard-tfstate-7f3a/branches/" | awk '{print $2}' | tr -d /); do
  state=$(gh pr list --head "$key" --state open --json number --jq 'length')
  if [ "$state" = "0" ]; then
    terraform init -reconfigure -input=false -backend-config="key=branches/${key}/terraform.tfstate"
    TF_VAR_branch="$key" terraform destroy -input=false -auto-approve
  fi
done

Ese es uno de los tres mecanismos de protección. En primer lugar, el evento closed destruye la pila cuando la solicitud de incorporación de cambios se fusiona o se cierra. En segundo lugar, la tarea nocturna detecta las ejecuciones que fallaron; asume nombres de rama sin /, por lo que debe utilizar un identificador si los suyos contienen uno. En tercer lugar, debe etiquetar los recursos de la rama con el nombre de la rama y una fecha de creación, siempre que el recurso lo admita, para que una revisión del contrato muestre los elementos rezagados. Si un clúster de Managed Kubernetes forma parte de una pila de rama, sus grupos de nodos deben eliminarse antes que el clúster; Terraform ordena esto a través de la dependencia entre ionoscloud_k8s_node_pool y ionoscloud_k8s_cluster.

El lado de ArgoCD también realiza la limpieza. Con prune: true y un ApplicationSet que genera un Application por cada solicitud de incorporación de cambios abierta, el cierre de la solicitud de incorporación de cambios elimina el Application generado y sus recursos de espacio de nombres.

5. Terraform y ArgoCD: ¿Quién es propietario de qué?

5.1 La línea de propiedad

Objeto Propietario Motivo
Centros de datos, LAN, NSG, ALB, grupos de destino Terraform Recursos de IONOS CLOUD, requieren IONOS_TOKEN
Clúster MKS, grupos de nodos, kubeconfig Terraform Recursos de IONOS CLOUD
DBaaS, In-Memory DB, Kafka, cubos de Object Storage Terraform Recursos de IONOS CLOUD
Deployments, Services, Ingress, ConfigMaps, NetworkPolicies ArgoCD Objetos de Kubernetes, versionados con la aplicación
Secrets con credenciales External Secrets Operator, sincronizado por ArgoCD Los valores permanecen en el almacén de secretos
ArgoCD en sí mismo y sus objetos Application Bootstrap una vez, luego ArgoCD Evita un bucle de huevo y gallina

Un objeto, un propietario. El puente entre los dos mundos son los datos, no los recursos compartidos: las salidas de Terraform, como pg_host, van al almacén de secretos, y los manifiestos hacen referencia al Secret de Kubernetes resultante (Unidad 5.2).

5.2 Evitar bucles de conflicto

Un bucle de conflicto ocurre cuando dos controladores continúan modificando el mismo campo. Para permitir que un HorizontalPodAutoscaler sea propietario del recuento de réplicas, agregue lo siguiente al Application:

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      name: taskboard-api
      jsonPointers:
        - /spec/replicas

Casos típicos de TaskBoard:

  • HPA frente a Git: Si un HPA escala taskboard-api, elimine replicas de la superposición o ignore el campo como se muestra, o bien selfHeal restablece el recuento en cada sincronización.
  • Autoscaler frente a Terraform: Con auto_scaling en un grupo de nodos, conserve lifecycle { ignore_changes = [node_count] } de la Unidad 3.2, o cada aplicación restablece el grupo.
  • CI frente a ArgoCD: Elimine kubectl set image del flujo de trabajo de la Unidad 3.3 cuando ArgoCD asuma el control. Con selfHeal, ArgoCD lo revierte en cuestión de minutos, y el despliegue parece revertirse por sí solo.
  • Terraform frente a MKS: Los servidores, NICs e IPs que Managed Kubernetes crea en su centro de datos se muestran en solo lectura en el DCD. Nunca los importe a Terraform; adminístrelos a través del grupo de nodos.

Tarjeta rápida de referencia de la API

Endpoints principales de la API para el tema de esta unidad:

Método Endpoint Descripción
GET /k8s/{k8sClusterId}/kubeconfig Descargar el kubeconfig para iniciar ArgoCD
GET /k8s/{k8sClusterId}/nodepools Verificar los grupos de nodos antes de un desmontaje de rama
DELETE /k8s/{k8sClusterId}/nodepools/{nodepoolId} Eliminar un grupo de nodos (antes que su clúster)
DELETE /k8s/{k8sClusterId} Eliminar un clúster sin grupos de nodos
GET /requests/{requestId}/status Consultar una eliminación asíncrona

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, aplicar un cambio en un manifiesto y observar la conciliación, revertir un cambio manual mediante la auto-reparación y desmontar un entorno de rama.

Requisitos previos:

  • El clúster MKS y el espacio de nombres TaskBoard de la Unidad 3.2, con el kubeconfig de administrador
  • Un repositorio taskboard-deploy con base/ y overlays/dev/, tal como se indica en la Sección 3
  • La CLI argocd, kustomize, gh y Terraform, con el cubo de estado de la Unidad 2.4

Paso 1: Instalar ArgoCD

export ARGOCD_VERSION="<release tag>"
kubectl create namespace argocd
kubectl apply -n argocd -f "https://raw.githubusercontent.com/argoproj/argo-cd/${ARGOCD_VERSION}/manifests/install.yaml"
kubectl -n argocd rollout status deploy/argocd-server

Salida esperada:

deployment "argocd-server" successfully rolled out

Paso 2: Iniciar sesión

kubectl -n argocd port-forward svc/argocd-server 8080:443 &
argocd login localhost:8080 --username admin --insecure \
  --password "$(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d)"

Salida esperada:

'admin:login' logged in successfully

Paso 3: Registrar el repositorio y la Aplicación

Aplique el Secret del repositorio (sección 2.2) y el Application (sección 2.3).

kubectl apply -f argocd/repo-secret.yaml -f argocd/taskboard-dev.yaml
argocd app wait taskboard-dev --health --timeout 300

Salida esperada:

Name:     argocd/taskboard-dev
Sync Status:   Synced to main (<sha>)
Health Status: Healthy

Paso 4: Enviar un cambio de manifiesto

cd taskboard-deploy/overlays/dev
kustomize edit set image "taskboard-api=${CR_HOST}/taskboard/api:<new-sha>"
git commit -am "dev: taskboard-api <new-sha>" && git push
argocd app get taskboard-dev --refresh | grep -E "Sync Status|Health"

Salida esperada:

Sync Status:   Synced to main (<new commit>)
Health Status: Healthy

Paso 5: Supervisar la auto reparación

kubectl -n taskboard scale deploy/taskboard-web --replicas=0
sleep 30
kubectl -n taskboard get deploy taskboard-web

Salida esperada:

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

Paso 6: Crear y destruir un entorno de rama

Abra una pull request en taskboard-infra con el flujo de trabajo de la sección 4.1, espere a que se aplique y luego cierre la pull request.

gh pr close <number>
gh run watch

Salida esperada:

✓ env
  ✓ terraform destroy -input=false -auto-approve
Destroy complete! Resources: <n> destroyed.

Lista de verificación de validación:

  • [ ] taskboard-dev es Synced y Healthy
  • [ ] Un commit a overlays/dev cambia la imagen en ejecución sin ningún acceso de CI al clúster
  • [ ] Una reducción manual se revierte mediante la auto-reparación
  • [ ] Cerrar la solicitud de extracción destruye la pila de ramas y no deja ningún estado detrás, excepto el objeto de estado vacío

Limpieza:

argocd app delete taskboard-dev --yes
kubectl delete namespace argocd
kill %1

Errores comunes

Errores de desarrollo que debe evitar con el tema de esta unidad:

  1. La implementación que se revierte a sí misma

    • Problema: CI implementa una nueva imagen y, unos minutos después, la imagen anterior vuelve a estar en ejecución.
    • Causa: El paso kubectl set image anterior sigue en el pipeline y el selfHeal de ArgoCD restaura la etiqueta desde Git.
    • Solución: Cambie las imágenes solo mediante commits en el overlay (sección 3.3) y elimine las credenciales del clúster de la CI de la aplicación.
  2. Entornos de rama que nadie destruye

    • Problema: La factura aumenta cada mes y el contrato incluye cubos y bases de datos con nombres de ramas fusionadas hace mucho tiempo.
    • Causa: La tarea closed falló una vez o se ejecutó antes de que terraform init apuntara a la clave de estado de la rama.
    • Solución: Use una clave de estado por rama, ejecute destroy en closed y agregue la red de seguridad nocturna de la sección 4.2.
  3. Terraform y ArgoCD gestionando el mismo objeto

    • Problema: Cada terraform apply modifica un Deployment y cada sincronización de ArgoCD lo revierte.
    • Causa: El Deployment se creó con el proveedor de Terraform para Kubernetes y también está en el repositorio de despliegue.
    • Solución: Elija un propietario por objeto (sección 5.1); elimine el recurso del estado de Terraform con terraform state rm y deje que ArgoCD lo gestione.

Resumen

Ahora puede operar TaskBoard de forma declarativa. Terraform administra todo lo que constituye un recurso de IONOS CLOUD y se aplica al fusionar; ArgoCD administra todo lo que constituye un objeto de Kubernetes y lo sincroniza desde Git con poda y auto sanación. Las versiones se trasladan entre entornos como commits revisados a superposiciones de Kustomize, y los entornos de rama se crean y destruyen mediante el ciclo de vida de la solicitud de extracción.

Puntos clave:

  • Git es la fuente de verdad; ArgoCD extrae y reconcilia, por lo que la integración continua no necesita credenciales de clúster
  • ArgoCD utiliza kubernetes.default.svc, por lo que la lista de permisos de la API no lo bloquea
  • Promocione mediante el commit de etiquetas de imagen a superposiciones; revierta con git revert
  • Una clave de estado por rama, destrucción al cerrar la solicitud de extracción, además de una red de seguridad nocturna
  • Un propietario por objeto: Terraform para recursos de IONOS CLOUD, ArgoCD para objetos de Kubernetes

Terminología importante:

  • GitOps: Operar un sistema declarando su estado deseado en Git y reconciliándolo automáticamente
  • Application: El recurso personalizado de ArgoCD que asocia una ruta de Git con un espacio de nombres del clúster
  • Self-heal: La reversión automática por parte de ArgoCD de los cambios realizados directamente en el clúster
  • Overlay: Un directorio de Kustomize que modifica la base compartida para un entorno
  • Fight loop: Dos controladores que sobrescriben repetidamente el mismo campo del mismo objeto

Próximos pasos

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

Temas relacionados: