14 min de lectura

Objetivos de aprendizaje

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

  • Crear un flujo de trabajo de GitHub Actions que pruebe TaskBoard, envíe imágenes Git-SHA al Private Container Registry y las despliegue en Managed Kubernetes
  • Implementar el pipeline equivalente en GitLab CI con etapas de compilación y despliegue
  • Automatizar Terraform en CI: ejecutar el plan en cada solicitud de extracción con el plan como comentario, y aplicar los cambios al fusionar en `main`
  • Configurar secretos del pipeline para el token de la API de Cloud, las claves de Object Storage, el token del registro y un kubeconfig con ámbito de espacio de nombres
  • Revertir un despliegue fallido con `kubectl rollout undo` y recuperar el estado de Terraform, y extraer la infraestructura de TaskBoard en módulos reutilizables de Terraform

Unidad 3.3: Pipelines de CI/CD para IONOS CLOUD

Introducción

Hasta ahora ha ejecutado cada paso manualmente: terraform apply desde su portátil, docker push desde su shell, kubectl apply con un kubeconfig de administrador. Esto funciona para un solo desarrollador. Para un equipo, cada cambio en main debe pasar por la misma ruta revisada y repetible, y ningún portátil debe contener credenciales de producción.

En esta unidad automatiza ambas mitades de TaskBoard. La pipeline de la aplicación compila, prueba, publica e implementa. La pipeline de infraestructura planifica en las pull requests y aplica en el merge. Almacena cada credencial en el almacén de secretos del sistema de CI, elige una estrategia de despliegue, practica las reversas y convierte el Terraform de TaskBoard en módulos que su equipo puede reutilizar. En el Code Lab crea una pipeline de GitHub Actions que despliega TaskBoard en cada push a main.

1. Diseño de la canalización

TaskBoard utiliza dos canalizaciones con desencadenantes y credenciales diferentes:

Canalización Desencadenante Pasos Credenciales
Aplicación Push a main test, build, push image, deploy Token de push del registro, kubeconfig del implementador
Infraestructura Solicitud de extracción / fusión terraform plan, terraform apply IONOS_TOKEN, claves de Object Storage para el estado

Manténgalas separadas. La canalización de la aplicación nunca necesita el token de la API de Cloud, por lo que un paso de compilación comprometido no puede crear ni eliminar recursos. La canalización de infraestructura nunca necesita el kubeconfig.

1.1 Inventario de secretos

IONOS_TOKEN            Cloud API bearer token (infrastructure pipeline only)
AWS_ACCESS_KEY_ID      Object Storage Access Key for the Terraform state bucket
AWS_SECRET_ACCESS_KEY  Object Storage Secret Key for the Terraform state bucket
CR_HOST                Registry hostname (Unit 3.1)
CR_USERNAME            Push token username
CR_PASSWORD            Push token password
KUBECONFIG_DEPLOYER    Kubeconfig of the taskboard-deployer service account (Unit 3.2)

Genere IONOS_TOKEN para un usuario CI dedicado con solo los privilegios que la infraestructura necesita, y establezca un ttl explícito, como en la Unidad 1.1. El token de push del registro de la Unidad 3.1 lleva pull y push. Object Storage se autentica con una Access Key y una Secret Key, no con el bearer token, por lo que el backend de estado necesita su propio par.

1.2 Un kubeconfig para la pipeline

El kubeconfig de la API otorga acceso completo al clúster. Para CI, construya uno para la cuenta de servicio taskboard-deployer de la Unidad 3.2:

kubectl -n taskboard apply -f - <<'EOF'
apiVersion: v1
kind: Secret
metadata:
  name: taskboard-deployer-token
  annotations:
    kubernetes.io/service-account.name: taskboard-deployer
type: kubernetes.io/service-account-token
EOF

SA_TOKEN="$(kubectl -n taskboard get secret taskboard-deployer-token -o jsonpath='{.data.token}' | base64 -d)"
SERVER="$(kubectl config view --raw -o jsonpath='{.clusters[0].cluster.server}')"
CA="$(kubectl config view --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}')"

kubectl config --kubeconfig=deployer.yaml set-cluster taskboard --server="$SERVER"
kubectl config --kubeconfig=deployer.yaml set clusters.taskboard.certificate-authority-data "$CA"
kubectl config --kubeconfig=deployer.yaml set-credentials deployer --token="$SA_TOKEN"
kubectl config --kubeconfig=deployer.yaml set-context taskboard --cluster=taskboard --user=deployer --namespace=taskboard
kubectl config --kubeconfig=deployer.yaml use-context taskboard

Guarde deployer.yaml codificado en base64 como KUBECONFIG_DEPLOYER y elimine el archivo local. Si configura api_subnet_allow_list en el clúster, la dirección de salida del runner debe estar incluida en él, o kubectl no podrá alcanzar el servidor de API.

2. GitHub Actions: La pipeline de la aplicación

# .github/workflows/deploy.yml
name: deploy
on:
  push:
    branches: [main]

concurrency:
  group: deploy-production
  cancel-in-progress: false

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Test
        run: |
          pip install -r api/requirements.txt -r api/requirements-dev.txt
          pytest api/tests

      - name: Log in to the registry
        env:
          CR_HOST: ${{ secrets.CR_HOST }}
          CR_USERNAME: ${{ secrets.CR_USERNAME }}
          CR_PASSWORD: ${{ secrets.CR_PASSWORD }}
        run: echo "$CR_PASSWORD" | docker login "$CR_HOST" --username "$CR_USERNAME" --password-stdin

      - name: Build and push
        env:
          CR_HOST: ${{ secrets.CR_HOST }}
        run: |
          SHA="${GITHUB_SHA::12}"
          for svc in api web; do
            docker build -t "$CR_HOST/taskboard/$svc:$SHA" "$svc/"
            docker push "$CR_HOST/taskboard/$svc:$SHA"
          done

      - name: Deploy to MKS
        env:
          CR_HOST: ${{ secrets.CR_HOST }}
          KUBECONFIG_DEPLOYER: ${{ secrets.KUBECONFIG_DEPLOYER }}
        run: |
          echo "$KUBECONFIG_DEPLOYER" | base64 -d > "$RUNNER_TEMP/kubeconfig"
          export KUBECONFIG="$RUNNER_TEMP/kubeconfig"
          SHA="${GITHUB_SHA::12}"
          kubectl set image deploy/taskboard-api api="$CR_HOST/taskboard/api:$SHA"
          kubectl set image deploy/taskboard-web web="$CR_HOST/taskboard/web:$SHA"
          kubectl rollout status deploy/taskboard-api --timeout=5m
          kubectl rollout status deploy/taskboard-web --timeout=5m

El grupo concurrency permite que solo una implementación se ejecute a la vez, y rollout status marca el trabajo como fallido cuando los nuevos pods no pasan a estar listos. kubectl set image modifica únicamente la imagen; los propios manifiestos permanecen en Git y se aplican cuando cambian. Si se envían ambas imágenes de forma secuencial, un único runner se mantiene bien dentro de los límites por cliente del registro, que son 100 conexiones simultáneas y 60 solicitudes por segundo.

3. GitLab CI: La pipeline equivalente

# .gitlab-ci.yml
stages: [test, build, deploy]

variables:
  SHA: $CI_COMMIT_SHORT_SHA

test:
  stage: test
  image: python:3.12-slim
  script:
    - pip install -r api/requirements.txt -r api/requirements-dev.txt
    - pytest api/tests

build:
  stage: build
  image: docker:27
  services: [docker:27-dind]
  before_script:
    - echo "$CR_PASSWORD" | docker login "$CR_HOST" --username "$CR_USERNAME" --password-stdin
  script:
    - for svc in api web; do docker build -t "$CR_HOST/taskboard/$svc:$SHA" "$svc/"; docker push "$CR_HOST/taskboard/$svc:$SHA"; done
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy:
  stage: deploy
  image: alpine:3.20
  resource_group: production
  before_script:
    - apk add --no-cache curl
    - curl -sLo /usr/local/bin/kubectl "https://dl.k8s.io/release/v1.34.0/bin/linux/amd64/kubectl" && chmod +x /usr/local/bin/kubectl
    - echo "$KUBECONFIG_DEPLOYER" | base64 -d > /tmp/kubeconfig
  script:
    - export KUBECONFIG=/tmp/kubeconfig
    - kubectl set image deploy/taskboard-api api="$CR_HOST/taskboard/api:$SHA"
    - kubectl rollout status deploy/taskboard-api --timeout=5m
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

resource_group es el equivalente de GitLab al grupo concurrency de GitHub. Defina CR_PASSWORD y KUBECONFIG_DEPLOYER como variables enmascaradas y protegidas. Mantenga la versión de kubectl dentro de una versión menor de su clúster.

4. Terraform en CI/CD

4.1 Plan en la solicitud de extracción, Apply en la fusión

# .github/workflows/infra.yml
name: infra
on:
  pull_request:
    paths: ["infra/**"]
  push:
    branches: [main]
    paths: ["infra/**"]

concurrency:
  group: terraform-production
  cancel-in-progress: false

permissions:
  contents: read
  pull-requests: write

jobs:
  terraform:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: infra
    env:
      IONOS_TOKEN: ${{ secrets.IONOS_TOKEN }}
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_wrapper: false
      - run: terraform init -input=false
      - run: terraform plan -input=false -no-color -out=tfplan
      - name: Comment the plan
        if: github.event_name == 'pull_request'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          terraform show -no-color tfplan > plan.txt
          gh pr comment ${{ github.event.pull_request.number }} --body-file plan.txt
      - name: Apply
        if: github.event_name == 'push'
        run: terraform apply -input=false tfplan

El proveedor lee IONOS_TOKEN del entorno, y el backend s3 de la Unidad 1.2 lee las claves de Object Storage desde AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY. El grupo de concurrencia terraform-production serializa las ejecuciones, lo cual es el valor predeterminado seguro hasta que haya verificado el bloqueo de estado contra su bucket. Mantenga el proveedor fijado en 6.7.39 y commitee .terraform.lock.hcl, para que el plan en la pull request y el apply en main utilicen la misma versión de lanzamiento.

Cada apply espera por las solicitudes asíncronas de IONOS CLOUD. Un clúster o un pool de nodos puede tardar mucho tiempo, por lo que no reduzca el timeouts del proveedor para CI. Si una ejecución falla a mitad de camino, el estado ya contiene los recursos finalizados; vuelva a ejecutar la pipeline después de corregir la causa.

4.2 Gestión de varios entornos

Asigne a cada entorno su propio key de estado y su propio trabajo de workflow, por ejemplo dev/terraform.tfstate y prod/terraform.tfstate. Proteja el trabajo de producción con un entorno de GitHub que requiera un revisor, de modo que una sola fusión no pueda modificar la producción.

5. Estrategias de despliegue y reversión

5.1 Actualización gradual y recreación

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0

RollingUpdate es el valor predeterminado de Kubernetes: los nuevos pods se inician antes de que se detengan los antiguos, y con maxUnavailable: 0 la capacidad nunca disminuye. Recreate detiene primero todos los pods antiguos, lo cual solo se necesita cuando dos versiones no pueden ejecutarse simultáneamente, por ejemplo, durante un cambio de esquema de base de datos que rompe la versión anterior. Las liberaciones canary y blue-green requieren un segundo Deployment detrás del mismo Service con menos réplicas, o un controlador como Argo Rollouts; la Unidad 5.3 cubre GitOps con ArgoCD.

5.2 Reversión de la aplicación

kubectl rollout history deploy/taskboard-api
kubectl rollout undo deploy/taskboard-api
kubectl rollout undo deploy/taskboard-api --to-revision=3

Dado que cada imagen tiene una etiqueta de Git SHA, una reversión restaura una compilación conocida. Una etiqueta móvil como latest haría que la revisión anterior apuntara a la misma imagen defectuosa.

5.3 Recuperación del estado de Terraform

La Unidad 2.4 habilitó el versionado en el bucket de estado. Un estado corrupto o sobrescrito incorrectamente puede restaurarse desde una versión anterior:

EP="https://s3.eu-central-3.ionoscloud.com"
aws s3api list-object-versions --endpoint-url "$EP" \
  --bucket taskboard-tfstate-7f3a --prefix prod/terraform.tfstate
aws s3api get-object --endpoint-url "$EP" --bucket taskboard-tfstate-7f3a \
  --key prod/terraform.tfstate --version-id "<version-id>" restored.tfstate
terraform state push restored.tfstate
terraform plan

Detenga primero todas las canalizaciones. Después de la publicación, terraform plan muestra la diferencia entre el estado restaurado y la infraestructura real; resuélvala mediante importaciones (Unidad 1.2) antes de la siguiente aplicación.

6. Módulos de Terraform para TaskBoard

A medida que TaskBoard crece, los mismos bloques se repiten en cada entorno. Extráelos en módulos:

infra/
  modules/
    mks-cluster/
      main.tf        # ionoscloud_k8s_cluster, ionoscloud_k8s_node_pool
      variables.tf
      outputs.tf
  envs/
    dev/main.tf
    prod/main.tf
# modules/mks-cluster/variables.tf
variable "name"          { type = string }
variable "datacenter_id" { type = string }
variable "lan_id"        { type = string }
variable "k8s_version"   { type = string }
variable "node_count" {
  type    = number
  default = 2
}

# modules/mks-cluster/outputs.tf
output "cluster_id" { value = ionoscloud_k8s_cluster.this.id }
# envs/prod/main.tf
module "mks" {
  source        = "git::https://git.example.com/platform/tf-modules.git//mks-cluster?ref=v1.2.0"
  name          = "taskboard-prod"
  datacenter_id = ionoscloud_datacenter.taskboard.id
  lan_id        = ionoscloud_lan.app.id
  k8s_version   = var.k8s_version
  node_count    = 3
}

Un módulo declara sus entradas como variables y expone únicamente las salidas que necesita el resto del código. Fije los módulos a una etiqueta de Git con ?ref=, de la misma manera que fija el proveedor, y publique los cambios como nuevas etiquetas. Coloque el bloque required_providers con la fuente ionoscloud en cada módulo para que este indique el proveedor con el que se probó.

Tarjeta rápida de referencia de la API

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

Método Endpoint Descripción
GET https://api.ionos.com/auth/v1/tokens/generate?ttl=<seconds> Emitir el token de acceso de CI
GET /k8s/{k8sClusterId}/kubeconfig Descargar el kubeconfig de administrador para la configuración
GET /requests/{requestId}/status Consultar una solicitud asíncrona
POST https://api.ionos.com/containerregistries/registries/{registryId}/tokens Crear un token de registro para una canalización

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

Laboratorio de código

Objetivo: Crear una canalización de GitHub Actions que pruebe TaskBoard, envíe imágenes Git-SHA al registro y las despliegue en MKS en cada envío a main, y luego revierta una versión defectuosa.

Requisitos previos:

  • El registro y el token de envío de la Unidad 3.1.
  • El clúster de MKS, el espacio de nombres taskboard, la cuenta de servicio deployer y las implementaciones en ejecución de la Unidad 3.2.
  • Un repositorio de GitHub con TaskBoard y la CLI gh.

Paso 1: Crear el kubeconfig del deployer

Ejecute los comandos de la Sección 1.2 con el kubeconfig de administrador.

KUBECONFIG=deployer.yaml kubectl auth can-i update deployments
KUBECONFIG=deployer.yaml kubectl auth can-i create namespaces

Salida esperada:

yes
no

Paso 2: Almacenar los secretos

gh secret set CR_HOST --body "$CR_HOST"
gh secret set CR_USERNAME --body "taskboard-ci-push"
gh secret set CR_PASSWORD < ci-push.pass
gh secret set KUBECONFIG_DEPLOYER --body "$(base64 -w0 deployer.yaml)"
rm deployer.yaml
gh secret list

Salida esperada:

CR_HOST              Updated ...
CR_PASSWORD          Updated ...
CR_USERNAME          Updated ...
KUBECONFIG_DEPLOYER  Updated ...

Paso 3: Agregar el flujo de trabajo

Guarde el flujo de trabajo de la sección 2 como .github/workflows/deploy.yml, y luego realice el commit y el push.

git add .github/workflows/deploy.yml
git commit -m "ci: deploy TaskBoard to MKS"
git push origin main
gh run watch

Salida esperada:

✓ build-deploy
  ✓ Test
  ✓ Build and push
  ✓ Deploy to MKS

Paso 4: Verificar la imagen en ejecución

kubectl -n taskboard get deploy taskboard-api -o jsonpath='{.spec.template.spec.containers[0].image}'
git rev-parse --short=12 HEAD

Salida esperada:

<registry-hostname>/taskboard/api:<sha>
<sha>

Paso 5: Publicar una versión defectuosa

Cambie la ruta de la sonda de preparación en la API para que devuelva 500, y realice el commit y el push.

git commit -am "break health check" && git push origin main
gh run watch

Salida esperada:

X Deploy to MKS
error: timed out waiting for the condition

Paso 6: Revertir

kubectl -n taskboard rollout undo deploy/taskboard-api
kubectl -n taskboard rollout status deploy/taskboard-api

Salida esperada:

deployment.apps/taskboard-api rolled back
deployment "taskboard-api" successfully rolled out

Lista de verificación de validación:

  • [ ] Un push a main ejecuta pruebas, envía ambas imágenes y actualiza los Deployments
  • [ ] La etiqueta de la imagen en ejecución coincide con el SHA del commit
  • [ ] Un despliegue fallido hace que la pipeline falle, y rollout undo restaura el servicio
  • [ ] No se almacena ninguna credencial en el repositorio

Limpieza:

git revert --no-edit HEAD && git push origin main

Mantenga el clúster para la Unidad 3.4 y el Módulo 5, o ejecute terraform destroy desde la Unidad 3.2.

Errores comunes

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

  1. Dos ejecuciones de Terraform al mismo tiempo

    • Problema: Dos fusiones en rápida sucesión inician dos aplicaciones, y una de ellas falla o deja el estado inconsistente.
    • Por qué ocurre: Ambas ejecuciones leen y escriben el mismo objeto de estado en el bucket.
    • Solución: Serialice las ejecuciones con un grupo concurrency (GitHub) o resource_group (GitLab) por entorno, y aplique solo el tfplan revisado.
  2. Credenciales que expiran silenciosamente

    • Problema: La pipeline funcionó durante semanas, y luego cada ejecución falla con 401 en la API de Cloud o en docker login.
    • Por qué ocurre: El token de acceso alcanzó su ttl, o el token del registro alcanzó su fecha de expiración y fue eliminado.
    • Solución: Registre cada fecha de expiración junto a la clave secreta, realice la rotación antes de esa fecha, y cree el token de registro de reemplazo antes de eliminar el antiguo.
  3. kubeconfig de administrador en CI

    • Problema: Un paso de compilación comprometido elimina espacios de nombres o lee todas las claves secretas del clúster.
    • Por qué ocurre: La pipeline utiliza el kubeconfig de la API, que tiene acceso completo al clúster.
    • Solución: Utilice el kubeconfig taskboard-deployer con alcance de espacio de nombres de la sección 1.2, y mantenga el kubeconfig de administrador fuera de CI.

Resumen

Ahora puede distribuir TaskBoard únicamente a través de la revisión de código. La canalización de la aplicación realiza pruebas, construye imágenes Git-SHA, las envía al Private Container Registry y las despliega en MKS con una cuenta con ámbito de espacio de nombres. La canalización de infraestructura publica el plan de Terraform en cada solicitud de extracción y lo aplica al fusionar, una ejecución a la vez. Puede revertir una versión, restaurar una versión anterior del estado y compartir la infraestructura como módulos versionados.

Puntos clave:

  • Divida las canalizaciones de la aplicación y de la infraestructura para que cada una contenga solo las credenciales que necesita
  • Utilice IONOS_TOKEN para Terraform, un par de Access Key y Secret Key para el backend de estado, y un token de registro para Docker
  • Serialice las ejecuciones de Terraform y los despliegues por entorno con concurrency o resource_group
  • Despliegue etiquetas Git-SHA y espere a rollout status; revierta con kubectl rollout undo
  • Fije la versión del proveedor y de sus módulos, y restaure el estado desde versiones del bucket solo con todas las canalizaciones detenidas

Terminología importante:

  • Plan en PR: Ejecutar terraform plan para cada solicitud de extracción y publicar el resultado para su revisión
  • Grupo de concurrencia: Una configuración de CI que permite solo una ejecución por grupo a la vez
  • kubeconfig de cuenta de servicio: Un kubeconfig con un token de cuenta de servicio de Kubernetes limitado por RBAC
  • Actualización gradual: La estrategia de Deployment predeterminada que reemplaza los pods de forma gradual
  • Módulo de Terraform: Un directorio reutilizable de recursos con variables de entrada y salidas

Próximos pasos

Siga aprendiendo: Unidad 3.4: Verificación de conocimientos: contenedores y CI/CD

Temas relacionados: