Admin-Sistemas ·

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_USER y CI_REGISTRY_PASSWORD – credenciales del registro Docker.
  • KUBE_CONFIG – contenido del kubeconfig codificado 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
  - deploy

variables: 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_test usa mvn verify -DskipUnitTests para que solo se ejecuten pruebas de integración, evitando duplicación de pruebas unitarias.
  • En canary_deploy se exporta KUBECONFIG desde la variable codificada, garantizando que el runner no necesite acceso directo al archivo.
  • Los flags --wait y --timeout hacen 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-dind y 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_PROXY en el runner o cachea la imagen en un registro interno y usa image: 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 FAILED o PENDING_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.