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
mainejecuta 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 undorestaura 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:
-
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) oresource_group(GitLab) por entorno, y aplique solo eltfplanrevisado.
-
Credenciales que expiran silenciosamente
- Problema: La pipeline funcionó durante semanas, y luego cada ejecución falla con
401en la API de Cloud o endocker 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.
- Problema: La pipeline funcionó durante semanas, y luego cada ejecución falla con
-
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-deployercon 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_TOKENpara 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
concurrencyoresource_group - Despliegue etiquetas Git-SHA y espere a
rollout status; revierta conkubectl 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 planpara 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: