Implementación paso a paso de pipelines GitLab CI con Testcontainers y despliegue Canary en Kubernetes vía Helm
Introducción
En entornos de microservicios, la automatización de pruebas de integración y el despliegue controlado son esenciales para reducir riesgos y acelerar la entrega de valor. En este artículo veremos cómo construir un pipeline de GitLab CI que:
- Ejecute pruebas de integración usando Testcontainers, levantando contenedores reales (bases de datos, colas, etc.) en tiempo de ejecución.
- Empaquete la aplicación como imagen Docker y la publique en un registro privado.
- Despliegue automáticamente una versión Canary en un clúster Kubernetes mediante Helm, permitiendo el traffic shifting progresivo.
Todo ello con ejemplos concretos, comandos listos para copiar y una sección de troubleshooting para los errores más habituales.
1. Preparación del repositorio y de los recursos
1.1 Estructura mínima del proyecto
.
├─ .gitlab-ci.yml
├─ Dockerfile
├─ helm/
│ └─ myapp/
│ ├─ Chart.yaml
│ ├─ values.yaml
│ └─ templates/
│ └─ deployment.yaml
├─ src/
│ └─ main/
│ └─ java/...
└─ test/
└─ integration/
└─ MyIntegrationTest.java
Esta estructura separa claramente la lógica de CI (.gitlab-ci.yml), la construcción de la imagen (Dockerfile) y los artefactos de Helm.
1.2 Configuración de variables de entorno en GitLab
En Settings > CI/CD > Variables crea las siguientes variables (marcadas como protected y masked cuando corresponda):
CI_REGISTRY_USERyCI_REGISTRY_PASSWORD– credenciales del registro Docker.KUBE_CONFIG– contenido delkubeconfigcodificado en base64.HELM_REPO_PASSWORD– si usas un repositorio privado de charts.CANARY_WEIGHT– porcentaje inicial de tráfico (ej.10).
1.3 Instalación de dependencias en el runner
El runner debe disponer de Docker, docker-login, helm y kubectl. Si usas un runner Docker‑in‑Docker (DinD) con imagen oficial docker:stable, añade los siguientes paquetes:
apk add --no-cache curl git openssh-client bash
curl -LO https://get.helm.sh/helm-v3.12.0-linux-amd64.tar.gz
tar -zxvf helm-v3.12.0-linux-amd64.tar.gz
mv linux-amd64/helm /usr/local/bin/helm
2. Definición del pipeline GitLab CI
2.1 Etapas del pipeline
El archivo .gitlab-ci.yml tendrá cuatro stages:
- build: compila el código y crea la imagen Docker.
- test: ejecuta Testcontainers.
- push: publica la imagen en el registro.
- deploy: despliega Canary con Helm.
2.2 YAML completo con comentarios
stages: - build - test - push - deployvariables: IMAGE_TAG: “$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA” DOCKER_DRIVER: overlay2 MAVEN_OPTS: “-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository”
---------- BUILD ----------
build: stage: build image: maven:3.9-eclipse-temurin-17 services: - docker:dind script: - echo “Compilando proyecto…” - mvn -B clean package -DskipTests - echo “Construyendo imagen Docker…” - docker build -t $IMAGE_TAG . artifacts: paths: - target/*.jar expire_in: 1 hour
---------- TEST ----------
integration_test: stage: test image: maven:3.9-eclipse-temurin-17 services: - docker:dind script: - echo “Ejecutando pruebas de integración con Testcontainers…” - mvn verify -DskipUnitTests needs: - job: build artifacts: when: always reports: junit: target/surefire-reports/*.xml
---------- PUSH ----------
push_image: stage: push image: docker:stable services: - docker:dind script: - echo “Login al registro Docker…” - echo “$CI_REGISTRY_PASSWORD” | docker login -u “$CI_REGISTRY_USER” —password-stdin $CI_REGISTRY - echo “Publicando imagen $IMAGE_TAG” - docker push $IMAGE_TAG only: - main needs: - job: integration_test
---------- DEPLOY ----------
canary_deploy: stage: deploy image: alpine/helm:3.12.0 before_script: - apk add —no-cache curl bash git jq - echo “$KUBE_CONFIG” | base64 -d > /tmp/kubeconfig - export KUBECONFIG=/tmp/kubeconfig script: - echo “Desplegando versión Canary con Helm” - helm repo add myrepo https://myhelm.repo/charts —username $CI_REGISTRY_USER —password $HELM_REPO_PASSWORD - helm dependency update helm/myapp - | helm upgrade —install myapp-canary helm/myapp
—namespace production
—set image.repository=$CI_REGISTRY_IMAGE
—set image.tag=$CI_COMMIT_SHORT_SHA
—set canary.enabled=true
—set canary.weight=$CANARY_WEIGHT
—wait —timeout 5m only: - main needs: - job: push_image
2.3 Por qué cada paso
- services: docker:dind permite crear contenedores dentro del job, necesario para Testcontainers y para
docker build. - needs asegura que los jobs se ejecuten en orden y que los artefactos estén disponibles.
- El job
integration_testusamvn verify -DskipUnitTestspara que solo se ejecuten pruebas de integración, evitando duplicación de pruebas unitarias. - En
canary_deployse exportaKUBECONFIGdesde la variable codificada, garantizando que el runner no necesite acceso directo al archivo. - Los flags
--waity--timeouthacen que Helm reporte fallos de despliegue antes de que el pipeline continúe.
3. Configuración de Testcontainers
3.1 Dependencias Maven
<dependency> <groupId>org.testcontainers</groupId> <artifactId>testcontainers</artifactId> <version>1.19.0</version> <scope>test</scope> </dependency><dependency> <groupId>org.testcontainers</groupId> <artifactId>junit-jupiter</artifactId> <version>1.19.0</version> <scope>test</scope> </dependency>
<dependency> <groupId>org.testcontainers</groupId> <artifactId>postgresql</artifactId> <version>1.19.0</version> <scope>test</scope> </dependency>
3.2 Ejemplo de prueba de integración
import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import org.testcontainers.containers.PostgreSQLContainer; import org.testcontainers.junit.jupiter.Container; import org.testcontainers.junit.jupiter.Testcontainers; import static org.junit.jupiter.api.Assertions.*;@Testcontainers @ExtendWith(SpringExtension.class) public class MyIntegrationTest {
@Container static PostgreSQLContainer<?> pg = new PostgreSQLContainer<>("postgres:15-alpine") .withDatabaseName("testdb") .withUsername("test") .withPassword("test"); @Test void whenSavingEntity_thenItCanBeRead() { // Configura datasource usando pg.getJdbcUrl() DataSource ds = DataSourceBuilder.create() .url(pg.getJdbcUrl()) .username(pg.getUsername()) .password(pg.getPassword()) .driverClassName("org.postgresql.Driver") .build(); // Aquí tu lógica de repositorio… assertTrue(someRepository.save(new Entity("demo")).getId() > 0); }
}
Testcontainers inicia automáticamente un contenedor PostgreSQL, lo expone en un puerto aleatorio y lo destruye al final del test. Gracias a docker:dind el runner tiene acceso al daemon Docker necesario.
3.3 Ajustes de rendimiento
Para evitar la sobrecarga de descargar imágenes en cada job, habilita una cache de Docker en el runner o usa la opción --cache-from en docker build. Asimismo, puedes pre‑pullar imágenes usadas por Testcontainers en la fase before_script:
before_script:
- docker pull postgres:15-alpine
4. Despliegue Canary con Helm en Kubernetes
4.1 Chart de Helm con soporte Canary
En helm/myapp/templates/deployment.yaml agregamos una sección que habilita el despliegue Canary usando un canary label y una estrategia de rolling update.
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "myapp.fullname" . }}
labels:
app: {{ include "myapp.name" . }}
spec:
replicas: {{ .Values.replicaCount }}
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 25%
maxUnavailable: 0
selector:
matchLabels:
app: {{ include "myapp.name" . }}
template:
metadata:
labels:
app: {{ include "myapp.name" . }}
{{- if .Values.canary.enabled }}
version: canary
{{- else }}
version: stable
{{- end }}
spec:
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
ports:
- containerPort: 8080
env:
- name: JAVA_OPTS
value: "-Xms512m -Xmx1024m"
4.2 Configuración de Service y Traffic Splitting
Usaremos Ingress con canary annotations (por ejemplo, NGINX Ingress Controller).
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: myapp-ingress
annotations:
nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-weight: "{{ .Values.canary.weight }}"
spec:
rules:
- host: myapp.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: myapp-service
port:
number: 80
El valor de canary.weight proviene de la variable de CI $CANARY_WEIGHT. Incrementar este valor en despliegues posteriores permite un traffic shift progresivo.
4.3 Actualización gradual
Para automatizar el aumento del peso, añade un job opcional que se ejecute después del despliegue inicial:
increase_canary:
stage: deploy
image: alpine/helm:3.12.0
script:
- echo "$KUBE_CONFIG" | base64 -d > /tmp/kubeconfig
- export KUBECONFIG=/tmp/kubeconfig
- NEW_WEIGHT=$(( $CANARY_WEIGHT + 10 ))
- |
helm upgrade myapp-canary helm/myapp \
--set canary.enabled=true \
--set canary.weight=$NEW_WEIGHT
only:
- schedules
Este job puede ser disparado mediante un pipeline schedule cada 10‑15 minutos, monitorizando métricas antes de continuar.
Troubleshooting
5.1 Error: Cannot connect to the Docker Daemon en jobs con Testcontainers
- Causa: El runner no tiene permiso para acceder al socket Docker.
- Solución: Usa la imagen
docker:stable-dindy habilita el privilegio:
docker:
image: docker:stable
services:
- name: docker:dind
command: ["--registry-mirror", "https://registry-1.docker.io"]
variables:
DOCKER_HOST: tcp://docker:2375
DOCKER_TLS_CERTDIR: ""
5.2 Error: Failed to pull image postgres:15-alpine
- Causa: El runner está detrás de un proxy o no tiene acceso a internet.
- Solución: Configura variables
HTTP_PROXY/HTTPS_PROXYen el runner o cachea la imagen en un registro interno y usaimage: myregistry.local/postgres:15-alpine.
5.3 Despliegue Canary no recibe tráfico
- Causa: Anotaciones de Ingress incorrectas o controlador Ingress sin soporte de Canary.
- Solución: Verifica que el Ingress Controller sea NGINX (v1.2+). Ejecuta:
kubectl describe ingress myapp-ingress | grep canary
Si la anotación no aparece, corrige el annotations en el chart y vuelve a aplicar.
5.4 Helm falla con cannot re-use a name that is still in use
- Causa: Release existente en estado
FAILEDoPENDING_INSTALL. - Solución: Limpia el release:
helm uninstall myapp-canary --namespace production
helm delete --purge myapp-canary
5.5 Timeout en helm upgrade --wait
- Causa: Liveness/Readiness probes no pasan.
- Solución: Revisa logs del pod:
kubectl logs -l app=myapp -n production
kubectl describe pod -l app=myapp -n production
Corrige la configuración de probes en values.yaml y vuelve a lanzar el pipeline.
Conclusión
Integrar Testcontainers dentro de un pipeline GitLab CI permite ejecutar pruebas de integración realistas sin depender de entornos externos, mientras que el despliegue Canary con Helm y Kubernetes brinda un mecanismo seguro para lanzar nuevas versiones a producción con control de tráfico.
Los pasos descritos—configuración del runner, definición del .gitlab-ci.yml, escritura de pruebas con Testcontainers y creación de un chart Helm preparado para Canary—constituyen una base reproducible que los sysadmins pueden adaptar a cualquier stack Java, Node.js o Go. Con la sección de troubleshooting incluida, los problemas más comunes se resuelven rápidamente, asegurando que el flujo CI/CD sea estable y escalable.
Al adoptar esta práctica, tu equipo gana en velocidad de entrega, confiabilidad de pruebas y capacidad para detectar fallos en producción antes de que afecten a todos los usuarios.
comentarios(0)
$ dejar comentario