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, eliminereplicasde la superposición o ignore el campo como se muestra, o bienselfHealrestablece el recuento en cada sincronización. - Autoscaler frente a Terraform: Con
auto_scalingen un grupo de nodos, conservelifecycle { ignore_changes = [node_count] }de la Unidad 3.2, o cada aplicación restablece el grupo. - CI frente a ArgoCD: Elimine
kubectl set imagedel flujo de trabajo de la Unidad 3.3 cuando ArgoCD asuma el control. ConselfHeal, 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-deployconbase/yoverlays/dev/, tal como se indica en la Sección 3 - La CLI
argocd,kustomize,ghy 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-devesSyncedyHealthy - [ ] Un commit a
overlays/devcambia 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:
-
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 imageanterior sigue en el pipeline y elselfHealde 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.
-
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
closedfalló una vez o se ejecutó antes de queterraform initapuntara a la clave de estado de la rama. - Solución: Use una clave de estado por rama, ejecute destroy en
closedy agregue la red de seguridad nocturna de la sección 4.2.
-
Terraform y ArgoCD gestionando el mismo objeto
- Problema: Cada
terraform applymodifica 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 rmy deje que ArgoCD lo gestione.
- Problema: Cada
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: