Unidad 3.3: CI/CD Pipelines para IONOS

Introducción

Usted ha containerizado TaskBoard, ha enviado sus imágenes a IONOS Container Registry y lo ha desplegado en Managed Kubernetes manualmente. Ejecutar docker push y kubectl apply desde su laptop no es escalable para un equipo, y no sobrevive al momento en que olvida qué etiqueta de imagen está en producción. En esta unidad, usted conecta todo el ciclo para que un git push sea el único paso manual. Un compromiso desencadena una compilación, la imagen llega a Container Registry con la etiqueta SHA de git, y la nueva etiqueta se implementa en el Cluster.

También pondrá la infraestructura bajo la misma disciplina. Terraform plan se ejecuta en cada solicitud de extracción para que los revisores vean la diferencia antes de que se realicen cambios, y apply se ejecuta solo después de la fusión. Dos limitaciones de IONOS dan forma a cada tubería que escriba aquí: el API es asíncrono, por lo que las implementaciones deben esperar a la preparación en lugar de asumirla, y la autenticación de Container Registry es basada en tokens Docker de inicio de sesión solo, sin RBAC y sin repositorios por equipo, por lo que las credenciales viven en secretos de CI.

1. Diseño de Pipeline para IONOS

Un pipeline de CI/CD en IONOS se divide en dos flujos distintos que no deben compartir un trabajo. Los cambios de aplicación siguen build -> test -> push image -> deploy to Kubernetes. Los cambios de infraestructura siguen plan -> apply. Mezclarlos significa que un error tipográfico en un manifiesto de Kubernetes puede bloquear una corrección urgente de infraestructura, y una actualización lenta de terraform apply retrasa cada implementación de aplicación.

El flujo de aplicación termina con kubectl apply o, más precisamente, una actualización controlada de la etiqueta de imagen contra una implementación existente. El flujo de infraestructura termina con terraform apply contra sus recursos de IONOS. Ambos flujos se autenticarán en IONOS, pero utilizan credenciales diferentes: el flujo de aplicación necesita un token de Container Registry y un kubeconfig, mientras que el flujo de infraestructura necesita un token de portador IONOS_TOKEN para la nube API.

1.1 Etiquetado de Imágenes con el SHA de Git

Nunca implemente :latest. Una etiqueta mutable hace que las reversiones sean ambiguas y rompe el enlace entre un pod en ejecución y el compromiso que lo produjo. Etiquete cada imagen con el SHA de Git inmutable para que la revisión en ejecución siempre sea trazable.

# Derive an immutable tag from the commit
REGISTRY="taskboard.cr.de-fra.ionos.com"
SHA=$(git rev-parse --short HEAD)
IMAGE="${REGISTRY}/taskboard-api:${SHA}"

docker build -t "${IMAGE}" ./api
docker push "${IMAGE}"

El nombre de host del registro sigue el patrón {registry-name}.cr.{location-with-dash}.ionos.com, por ejemplo tue1608es.cr.es-vit.ionos.com. El nombre de host se asigna solo después de que el registro alcance el estado de ejecución y está vacío hasta entonces, por lo que un pipeline que provisiona un registro fresco debe leer el nombre de host desde la salida de Terraform en lugar de codificarlo de forma rígida.

1.2 Separación de los Repositorios de Aplicación e Infraestructura

Mantenga Terraform en un repositorio de infraestructura y los manifiestos de Kubernetes más el código de aplicación en un repositorio de aplicación. El repositorio de infraestructura se aplica al fusionar; el repositorio de aplicación se construye y se implementa al realizar un push. Esta separación mantiene el radio de acción de un cambio malo pequeño y le permite conceder a diferentes equipos diferentes accesos.

taskboard-app/          # build, push, kubectl deploy
  api/Dockerfile
  k8s/deployment.yaml
  .github/workflows/deploy.yml
taskboard-infra/        # terraform plan/apply
  main.tf
  modules/
  .github/workflows/terraform.yml

2. GitHub Actions para IONOS

Un flujo de trabajo de GitHub Actions para el flujo de la aplicación tiene tres etapas lógicas en un solo trabajo: compilar y probar, inicio de sesión en Docker y push, y luego implementar en Managed Kubernetes. Las partes específicas de IONOS son el inicio de sesión en el registro (basado en token) y la recuperación de kubeconfig.

2.1 Almacenar secretos de IONOS

Los tokens nunca pertenecen al repositorio. Almacene el token del registro de contenedores y el kubeconfig como secretos del repositorio o del entorno. La contraseña del token del registro de contenedores se muestra solo una vez en el momento de la creación, así que caṕtúrela de inmediato y almacénela en CI. Un token de registro puede ser permanente o temporal con un expiryDate, y al expirar, el token se elimina en lugar de deshabilitarse, lo que significa que un token expirado en CI falla el inicio de sesión en Docker de manera directa en lugar de degradarse silenciosamente.

2.2 El flujo de trabajo de implementación

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

env:
  REGISTRY: taskboard.cr.de-fra.ionos.com
  IMAGE_NAME: taskboard-api

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

      - name: Set image tag
        run: echo "TAG=$(git rev-parse --short HEAD)" >> "$GITHUB_ENV"

      - name: Run tests
        run: |
          cd api
          pip install -r requirements.txt
          pytest

      - name: Log in to IONOS Container Registry
        run: echo "${{ secrets.CR_PASSWORD }}" | docker login "$REGISTRY" \
             -u "${{ secrets.CR_USERNAME }}" --password-stdin

      - name: Build and push image
        run: |
          docker build -t "$REGISTRY/$IMAGE_NAME:$TAG" ./api
          docker push "$REGISTRY/$IMAGE_NAME:$TAG"

      - name: Configure kubectl
        run: |
          mkdir -p "$HOME/.kube"
          echo "${{ secrets.KUBECONFIG }}" | base64 -d > "$HOME/.kube/config"

      - name: Deploy to Managed Kubernetes
        run: |
          kubectl set image deployment/taskboard-api \
            api="$REGISTRY/$IMAGE_NAME:$TAG"
          kubectl rollout status deployment/taskboard-api --timeout=180s

kubectl set image actualiza solo el campo de la imagen en la implementación existente, lo que desencadena una actualización incremental sin volver a aplicar todo el manifiesto. El paso kubectl rollout status bloquea hasta que se complete la implementación o se produzca un tiempo de espera, lo que es la forma correcta de mostrar una implementación fallida como una tubería fallida. El kubeconfig en sí proviene del Managed Kubernetes Cluster: puede descargarlo desde la configuración de Cluster o, en una tubería automatizada, leerlo desde la salida de Terraform (cubierto en la Unidad 3.2) y almacenar el valor codificado en base64 como el secreto KUBECONFIG.

3. GitLab CI para IONOS

GitLab CI expresa el mismo flujo como etapas discretas en .gitlab-ci.yml. Las especificaciones de IONOS son idénticas: inicio de sesión basado en token en el registro y un kubeconfig para el Cluster. GitLab proporciona un servicio de Docker-en-Docker para compilar imágenes dentro de la tubería.

3.1 Etapas de la tubería

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

variables:
  REGISTRY: taskboard.cr.de-fra.ionos.com
  IMAGE_NAME: taskboard-api

test:
  stage: test
  image: python:3.12
  script:
    - cd api && pip install -r requirements.txt && pytest

build:
  stage: build
  image: docker:24
  services: [docker:24-dind]
  script:
    - export TAG=$CI_COMMIT_SHORT_SHA
    - echo "$CR_PASSWORD" | docker login "$REGISTRY" -u "$CR_USERNAME" --password-stdin
    - docker build -t "$REGISTRY/$IMAGE_NAME:$TAG" ./api
    - docker push "$REGISTRY/$IMAGE_NAME:$TAG"

deploy:
  stage: deploy
  image: bitnami/kubectl:latest
  script:
    - echo "$KUBECONFIG_B64" | base64 -d > /tmp/kubeconfig
    - export KUBECONFIG=/tmp/kubeconfig
    - kubectl set image deployment/taskboard-api api="$REGISTRY/$IMAGE_NAME:$CI_COMMIT_SHORT_SHA"
    - kubectl rollout status deployment/taskboard-api --timeout=180s
  only: [main]

Almacene CR_USERNAME, CR_PASSWORD y KUBECONFIG_B64 como variables protegidas y enmascaradas de CI/CD en la configuración del proyecto de GitLab. Las variables protegidas solo se exponen a las tuberías que se ejecutan en ramas protegidas, lo que mantiene las credenciales de producción fuera de las tuberías de las ramas de características. CI_COMMIT_SHORT_SHA es el equivalente de GitLab del tag de SHA de git, lo que da la misma garantía de etiqueta inmutable que el ejemplo de GitHub Actions.

4. Terraform en CI/CD

Los cambios de infraestructura merecen una revisión antes de afectar los recursos de IONOS, porque terraform apply crea recursos facturables y puede destruirlos. El patrón estándar ejecuta terraform plan en cada solicitud de extracción y publica el plan como un comentario de PR, luego ejecuta terraform apply solo después de la fusión en main. Esto proporciona a los revisores la diferencia exacta y evita que alguien aplique cambios no revisados.

4.1 Planificar en PR, Aplicar en la fusión

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

env:
  IONOS_TOKEN: ${{ secrets.IONOS_TOKEN }}

jobs:
  plan:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
      - run: terraform plan -no-color -out=tfplan
      - run: terraform show -no-color tfplan > plan.txt
      - uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const plan = fs.readFileSync('plan.txt', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '```\n' + plan.slice(0, 60000) + '\n```'
            });

  apply:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
      - run: terraform apply -auto-approve

El proveedor de IONOS Terraform se autentica desde la variable de entorno IONOS_TOKEN, por lo que pasar el token de portador como una variable de entorno es todo lo que necesita el bloque del proveedor. El proveedor sondea las operaciones asíncronas de IONOS internamente, por lo que terraform apply bloquea hasta que cada recurso alcance su estado listo antes de continuar. Esto significa que la tubería no necesita sus propios bucles de preparación para los recursos administrados por Terraform.

4.2 Estado remoto para CI/CD

El estado local no funciona en CI/CD porque cada ejecutor comienza con una copia de trabajo limpia. Utilice el backend de IONOS Object Storage compatible con S3 para que cada ejecución de la tubería lea y escriba el mismo estado, y para que el bloqueo de estado evite que dos aplicaciones concurrentes lo corrompan.

terraform {
  backend "s3" {
    bucket                      = "taskboard-tfstate"
    key                         = "infra/terraform.tfstate"
    region                      = "de"
    endpoints = { s3 = "https://s3-eu-central-1.ionoscloud.com" }
    skip_credentials_validation = true
    skip_region_validation      = true
    skip_requesting_account_id  = true
  }
}

Object Storage utiliza la autenticación de Access Key más Secret Key, no tokens de portador, por lo que las credenciales de backend son separadas de IONOS_TOKEN. Proporciónelas a la tubería como secretos AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY, que el backend de S3 lee automáticamente.

5. Estrategias de implementación y reversión

La estrategia de implementación predeterminada de Kubernetes es RollingUpdate, que reemplaza Pods de forma incremental para que el servicio siga disponible durante la implementación. Para las cargas de trabajo que no pueden ejecutar dos versiones al mismo tiempo, use Recreate, que termina todos los Pods antiguos antes de iniciar los nuevos, con el costo de un breve tiempo de inactividad.

5.1 Configuración de la estrategia

apiVersion: apps/v1
kind: Deployment
metadata:
  name: taskboard-api
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels: { app: taskboard-api }
  template:
    metadata:
      labels: { app: taskboard-api }
    spec:
      imagePullSecrets:
        - name: cr-pull-secret
      containers:
        - name: api
          image: taskboard.cr.de-fra.ionos.com/taskboard-api:abc1234
          readinessProbe:
            httpGet: { path: /healthz, port: 8080 }
            initialDelaySeconds: 5

maxUnavailable: 0 garantiza que no se pierda capacidad durante la implementación, y readinessProbe garantiza que el tráfico solo llegue a Pods que informan de un estado saludable. La entrada imagePullSecrets hace referencia al token del Registro de contenedores, ya que Cluster extrae imágenes utilizando las mismas credenciales basadas en tokens que su canalización utilizó para enviarlas. Las versiones canarias y azul-verdes son posibles con implementaciones paralelas y cambio de tráfico, o con una herramienta de GitOps como ArgoCD, que se cubre como un patrón en la Unidad 5.3 en lugar de aquí.

5.2 Reversión

Cuando una implementación sale mal, revierta la aplicación con kubectl rollout undo, que devuelve la implementación a su revisión anterior sin reconstruir nada.

# Inspect revision history
kubectl rollout history deployment/taskboard-api

# Roll back to the immediately previous revision
kubectl rollout undo deployment/taskboard-api

# Roll back to a specific revision
kubectl rollout undo deployment/taskboard-api --to-revision=4

Dado que cada imagen está etiquetada con su SHA de git, también puede revertir de forma determinista con kubectl set image apuntando a una etiqueta conocida como buena. Para la infraestructura, la reversión significa revertir el compromiso ofensivo y volver a ejecutar terraform apply, que reconcilia los recursos en vivo con el estado comprometido. Si el estado en sí mismo está dañado, restaúrelo desde una copia versionada en el Object Storage de backend.

6. Creación de una biblioteca de módulos Terraform

Una vez que la infraestructura de TaskBoard funcione, extraiga los patrones repetidos en módulos para que el próximo servicio no tenga que empezar desde cero. Un módulo agrupa recursos relacionados detrás de variables de entrada y expone salidas, convirtiendo una pila verbosa en unas pocas líneas de código del llamador.

6.1 Estructura del módulo

# modules/k8s-service/variables.tf
variable "name"        { type = string }
variable "node_count"  { type = number, default = 2 }
variable "k8s_version" { type = string, default = "1.34" }

# modules/k8s-service/main.tf
resource "ionoscloud_k8s_cluster" "this" {
  name        = var.name
  k8s_version = var.k8s_version
}

resource "ionoscloud_k8s_node_pool" "this" {
  name        = "${var.name}-pool"
  k8s_cluster_id = ionoscloud_k8s_cluster.this.id
  node_count  = var.node_count
  # ... cores, ram, availability_zone, etc.
}

# modules/k8s-service/outputs.tf
output "cluster_id" { value = ionoscloud_k8s_cluster.this.id }

Las versiones de Kubernetes admitidas son 1.34, 1.33, 1.32 y 1.31, así que fije una versión conocida y buena en el módulo predeterminado y permita que los llamadores la reemplacen. Node Pools puede utilizar tipos Dedicated Core o vCPU Server, y un grupo Node tiene un máximo absoluto de 100 nodos con un máximo recomendado de 20, así que valide node_count contra esos límites en lugar de permitir que un error tipográfico proporcione un grupo de tamaño excesivo.

6.2 Uso del módulo

module "taskboard" {
  source     = "./modules/k8s-service"
  name       = "taskboard-prod"
  node_count = 3
}

output "taskboard_cluster" {
  value = module.taskboard.cluster_id
}

Versione su repositorio de módulos con etiquetas git y haga referencia a una etiqueta específica en source para que un cambio posterior en el módulo no altere silenciosamente una pila existente. Esta es la forma en que un equipo convierte una implementación de trabajo en una biblioteca reutilizable.

API Tarjeta de referencia rápida

Puntos de conexión clave utilizados por las tuberías de CI/CD en IONOS:

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

Laboratorio de código

Objetivo: Construir una tubería de GitHub Actions que construye, envía y despliega TaskBoard en Managed Kubernetes en cada envío a main.

Requisitos previos:

• Cuenta de IONOS Cloud con token de API (IONOS_TOKEN)
• Un registro de contenedores existente y Managed Kubernetes Cluster (de las Unidades 3.1 y 3.2)
• Un repositorio de GitHub para la aplicación TaskBoard
• docker, kubectl, y ionosctl instalados localmente

Paso 1: Crear un token de registro para CI

ionosctl container-registry token create \
  --registry-id "$REGISTRY_ID" --name ci-deploy

Salida esperada:

TokenId    Name        Status   ExpiryDate
a1b2c3d4   ci-deploy   enabled  -
Password: <shown once - copy it now>

Paso 2: Almacenar secretos en GitHub

gh secret set CR_USERNAME --body "ci-deploy"
gh secret set CR_PASSWORD --body "<password from step 1>"
gh secret set KUBECONFIG  --body "$(ionosctl k8s kubeconfig get \
  --cluster-id "$CLUSTER_ID" | base64 -w0)"

Salida esperada:

✓ Set secret CR_USERNAME
✓ Set secret CR_PASSWORD
✓ Set secret KUBECONFIG

Paso 3: Agregar el archivo de flujo de trabajo Confirmar .github/workflows/deploy.yml de la Sección 2.2 en el repositorio. Salida esperada:

[main 9f3c1ab] add deploy workflow
 1 file changed, 38 insertions(+)

Paso 4: Activar la tubería

git commit --allow-empty -m "trigger deploy"
git push origin main

Salida esperada:

To github.com:you/taskboard-app.git
   8d2e1f0..9f3c1ab  main -> main

Paso 5: Ver la ejecución

gh run watch

Salida esperada:

✓ build-and-deploy succeeded
  ✓ Build and push image
  ✓ Deploy to Managed Kubernetes

Paso 6: Verificar la implementación en el Cluster

kubectl get deployment taskboard-api -o wide

Salida esperada:

NAME            READY   IMAGE
taskboard-api   3/3     taskboard.cr.de-fra.ionos.com/taskboard-api:9f3c1ab

Lista de verificación:

• [ ] La imagen con la etiqueta git-SHA existe en el Registro de contenedores
• [ ] La imagen de implementación coincide con la etiqueta enviada
• [ ] kubectl rollout status informó éxito en la tubería
• [ ] Un segundo envío produce una nueva etiqueta SHA y una actualización de rodillo limpia

Limpieza:

gh secret delete CR_USERNAME CR_PASSWORD KUBECONFIG
ionosctl container-registry token delete --registry-id "$REGISTRY_ID" --token-id "$TOKEN_ID"

Errores comunes

Errores de los desarrolladores que deben evitarse con CI/CD en IONOS:

1. Codificar de forma rígida el nombre de host del registro antes de que el registro esté en ejecución

   • Problema: La canalización falla en el inicio de sesión de Docker con un error de resolución de DNS contra un nombre de host vacío.
   • Por qué sucede: El nombre de host del registro se asigna solo después de que el registro alcance el estado de ejecución, por lo que un registro recién provisionado no tiene nombre de host todavía.
   • Solución: Leer el nombre de host desde la salida de Terraform en lugar de codificarlo de forma rígida, y controlar el trabajo de envío en función de que el registro esté listo:

   output "registry_hostname" { value = ionoscloud_container_registry.this.hostname }
   

2. Esperar que un servicio LoadBalancer de Kubernetes sea un verdadero equilibrador de carga externo Load Balancer

   • Problema: El rendimiento se estanca y la fuente IP de cada solicitud se muestra como una dirección interna de Cluster, lo que rompe la limitación de velocidad y los registros de auditoría.
   • Por qué sucede: Un servicio LoadBalancer en Managed Kubernetes no provisiona un equilibrador de carga externo. IONOS reserva una dirección pública estática IP y la asigna como una dirección secundaria IP a un trabajador Node, y kube-proxy NATs el tráfico hacia el pod, limitando el rendimiento en el techo público de ese trabajador Node y perdiendo la fuente IP.
   • Solución: Establecer externalTrafficPolicy: Local para preservar la fuente IP, y colocar el servicio frente a un ALB administrado provisionado por separado o distribuirlo en varias direcciones IP de equilibrador de carga para superar el rendimiento de un trabajador Node:

   spec:
     type: LoadBalancer
     externalTrafficPolicy: Local
   

3. Ejecutar Terraform con estado local en CI/CD

   • Problema: Cada ejecución de la canalización comienza con un estado vacío, por lo que terraform apply intenta recrear recursos que ya existen y produce un error por nombres duplicados.
   • Por qué sucede: Los ejecutores de CI verifican un espacio de trabajo limpio sin archivo de estado, y no hay un backend compartido.
   • Solución: Configurar el backend compatible con S3 Object Storage para que todas las ejecuciones compartan estado, y suministrar credenciales de clave de acceso y clave secreta como secretos de la canalización:

   export AWS_ACCESS_KEY_ID="$IONOS_S3_KEY"
   export AWS_SECRET_ACCESS_KEY="$IONOS_S3_SECRET"
   terraform init
   

Resumen

Ahora puede controlar el ciclo completo de construcción-pruebas-despliegue desde un solo git push. La tubería de la aplicación construye un contenedor, lo etiqueta con el SHA de git, inicia sesión en IONOS Container Registry con un inicio de sesión basado en token Docker, empuja la imagen y la despliega en Managed Kubernetes con un kubectl set image y un kubectl rollout status con puerta de preparación. La tubería de infraestructura mantiene Terraform honesto planeando en solicitudes de extracción y aplicando solo en la unión, respaldado por un estado compartido en Object Storage. Cuando algo se rompe, kubectl rollout undo y un compromiso revertido de Terraform lo devuelven a un estado conocido y bueno, y su biblioteca de módulos extraída significa que el próximo servicio reutiliza estos patrones en lugar de reinventarlos.

Puntos clave:

• Divida el flujo de aplicación (build -> test -> push -> deploy) del flujo de infraestructura (plan -> apply); nunca comparta un trabajo entre ellos
• Etiquete cada imagen con el SHA de git inmutable, nunca :latest, para que la revisión en ejecución sea siempre trazable y los retrocesos sean deterministas
• Los tokens de Container Registry se muestran una vez en la creación y se eliminan en la expiración; almacénelos como secretos de CI y extraiga las imágenes con las mismas credenciales basadas en token
• Ejecute terraform plan en las solicitudes de extracción y terraform apply en la unión, con un estado compartido compatible con S3 en Object Storage y IONOS_TOKEN como secreto
• Retroceda las aplicaciones con kubectl rollout undo y la infraestructura revirtiendo el compromiso y volviendo a aplicar

Terminología importante:

• Etiqueta inmutable: Una etiqueta de imagen de contenedor derivada del SHA de git que nunca cambia, vinculando cada pod en ejecución al compromiso exacto que lo construyó.
• Actualización incremental: La estrategia de implementación predeterminada de Kubernetes que reemplaza Pods de forma incremental para que el servicio permanezca disponible durante una implementación.
• Planificar en la solicitud de extracción: El patrón de CI de Terraform de ejecutar terraform plan en las solicitudes de extracción y publicar la diferencia para revisión antes de cualquier apply.
• Backend de estado remoto: Un almacén de estado compartido de Terraform (compatible con S3 Object Storage en IONOS) que permite que cada ejecución de CI lea y escriba el mismo estado con bloqueo.
• imagePullSecret: Un secreto de Kubernetes que contiene credenciales de token de Container Registry para que Cluster pueda extraer imágenes privadas.

Próximos pasos

Continúe aprendiendo: Unidad 3.4: Verificación de conocimientos - Contenedores y CI/CD

Temas relacionados:

• Unidad 3.1: Registro de contenedores y pipelines de imágenes
• Unidad 3.2: Despliegue y operaciones de Kubernetes
• Unidad 5.3: GitOps y operaciones de despliegue