Crea tu primera tubería declarativa de Jenkins para CI/CD

Cree su Primera Pipeline Declarativa de Jenkins para CI/CD

Jenkins es el estándar de facto para los servidores de automatización de código abierto, sirviendo como columna vertebral para los pipelines de integración continua y entrega continua (CI/CD) en miles de organizaciones. Aunque Jenkins ofrece dos tipos de sintaxis de pipeline —Scripted y Declarative— la sintaxis de Pipeline Declarativa es el enfoque recomendado para la mayoría de los usuarios debido a su Groovy DSL más simple, estructurado y legible.

Esta guía proporciona un tutorial completo y paso a paso sobre cómo construir su primera Pipeline Declarativa funcional de Jenkins. Cubriremos la integración de la gestión de código fuente (SCM), la definición del entorno de construcción, la ejecución de pruebas y la implementación de una etapa de despliegue de ejemplo, dándole una base sólida para automatizar su ciclo de vida de entrega de software.

Entendiendo la Estructura de la Pipeline Declarativa

La Pipeline Declarativa define todo el flujo de trabajo en un archivo llamado Jenkinsfile, que se almacena junto con el código de su aplicación en su repositorio SCM (por ejemplo, Git). Esta práctica se conoce como Pipeline as Code (Pipeline como Código).

Elementos Centrales de una Pipeline Declarativa

Una Pipeline Declarativa debe contener los siguientes bloques de nivel superior:

pipeline: El bloque exterior obligatorio que define el contenido de la pipeline.
agent: Especifica dónde se ejecutará la pipeline o una etapa específica (por ejemplo, any, none, o etiquetas específicas).
stages: Contiene uno o más bloques stage secuenciales.
stage: Define un bloque conceptual de trabajo (por ejemplo, Construcción, Prueba, Despliegue).
steps: Contiene uno o más comandos o funciones ejecutados dentro de un stage.

pipeline {
    agent any 
    environment { // Opcional: Define variables de entorno
        APP_VERSION = '1.0.0'
    }
    stages {
        stage('Build') {
            steps {
                // Los comandos van aquí
            }
        }
    }
    post { // Opcional: Acciones que se ejecutan después de que la pipeline se completa
        always { 
            echo 'Pipeline finished.' 
        }
    }
}

Paso 1: Configuración del Job de Jenkins

Para ejecutar una Pipeline desde código, necesita configurar un job de Jenkins para que lea el Jenkinsfile de su repositorio.

Navegue a su panel de Jenkins y seleccione New Item (Nuevo Elemento).
Introduzca un nombre para su pipeline (por ejemplo, my-first-ci-pipeline).
Seleccione el tipo de elemento Pipeline y haga clic en OK.
En la página de configuración, desplácese hasta la sección Pipeline.
Cambie la definición de Pipeline script a Pipeline script from SCM (Script de Pipeline desde SCM).
Seleccione su SCM (por ejemplo, Git).
Introduzca la Repository URL (URL del Repositorio) y configure sus credenciales si es necesario.
Asegúrese de que la Script Path (Ruta del Script) esté configurada como Jenkinsfile (el valor predeterminado).

Paso 2: Definición del `Jenkinsfile` para CI/CD

Crearemos un Jenkinsfile completo que simule un flujo de trabajo CI/CD simple, integrando etapas estándar para un despliegue exitoso.

Asuma que tiene una estructura de repositorio que contiene el código fuente de su aplicación (por ejemplo, un proyecto simple de Python o Java) y el Jenkinsfile en la raíz.

El Ejemplo Completo de Pipeline Declarativa

Esta pipeline utiliza el agente node (si está configurado) y emplea pasos básicos de shell (sh) para simular trabajo real. La etapa de despliegue es condicional, ejecutándose solo si las etapas anteriores han finalizado con éxito.

// Jenkinsfile
pipeline {
    // 1. Definición del Agente: Especifica dónde se ejecuta toda la pipeline
    agent { 
        label 'my-build-agent' // Use una etiqueta específica si está disponible, o 'any'
    }

    // 2. Variables de Entorno: Define variables utilizables en toda la pipeline
    environment {
        CONTAINER_REGISTRY = 'registry.example.com'
        IMAGE_NAME = 'myapp'
    }

    stages {

        // Etapa 1: Checkout (Gestión de Código Fuente)
        stage('Checkout Source') {
            steps {
                // El paso 'checkout scm' extrae automáticamente el código 
                // basándose en la configuración definida en los ajustes del job de Jenkins.
                checkout scm
                sh 'echo "Source code successfully checked out."
            }
        }

        // Etapa 2: Construir Artefactos
        stage('Build Artifact') {
            steps {
                sh 'echo "Starting build for $IMAGE_NAME:$BUILD_ID"'
                // Simulación: Construir una imagen Docker o compilar un archivo jar/war
                sh "docker build -t ${IMAGE_NAME}:${BUILD_ID} ."
            }
        }

        // Etapa 3: Pruebas y Puertas de Calidad
        stage('Run Tests') {
            steps {
                sh './run_unit_tests.sh'
                sh 'echo "Running integration tests..."'
                // Ejemplo de recopilación de resultados de pruebas (requiere plugins apropiados)
                // junit '**/target/surefire-reports/*.xml'
            }
        }

        // Etapa 4: Despliegue (Condicional)
        stage('Deploy to Staging') {
            // La directiva 'when' asegura que la etapa solo se ejecute bajo condiciones específicas
            when {
                branch 'main'
            }
            steps {
                sh "docker push ${CONTAINER_REGISTRY}/${IMAGE_NAME}:${BUILD_ID}"
                sh 'kubectl apply -f k8s/deployment-staging.yaml'
                script {
                    // Los bloques script permiten lógica Groovy tradicional dentro de pasos Declarative
                    echo "Deployment successful to Staging environment."
                }
            }
        }
    }

    // 3. Acciones Posteriores: Define acciones basadas en el estado final de la pipeline
    post {
        success {
            echo 'Pipeline completed successfully. Notifying team via Slack...'
            // slackSend channel: '#devops-alerts', message: 'CI/CD Success!'
        }
        failure {
            echo 'Pipeline failed. Review logs for errors.'
        }
        cleanup {
            sh 'docker rmi -f $(docker images -aq --filter label=build_id=$BUILD_ID)'
        }
    }
}

Paso 3: Ejecución y Monitoreo de la Pipeline

Una vez que el Jenkinsfile se ha confirmado (committed) y subido (pushed) a la rama configurada en su job de Jenkins:

En la página del job de Jenkins, haga clic en Build Now (Construir Ahora) (o espere el polling de SCM/disparador webhook).
Monitoree la construcción en el panel Build History (Historial de Construcción).
Haga clic en el número de construcción en curso y seleccione Console Output (Salida de Consola) para ver los detalles de la ejecución paso a paso.
También puede usar la visualización Stage View (Vista de Etapas) (si el plugin está instalado) para ver el progreso de las etapas Checkout, Build, Test y Deploy gráficamente.

Mejores Prácticas y Funcionalidades Avanzadas

Utilización de Librerías y Código Compartido

Para pasos complejos o altamente repetitivos, evite escribir Groovy verboso directamente en el Jenkinsfile. En su lugar, utilice Shared Libraries (Librerías Compartidas). Estas librerías externas le permiten definir funciones comunes (como rutinas de despliegue estándar o funciones de notificación) que pueden ser llamadas desde múltiples pipelines, haciendo su Jenkinsfile más limpio.

// Llamando a un paso de librería compartida
stage('Custom Setup') {
    steps {
        customLibrary.initializeEnvironment(env: 'prod')
    }
}

Trabajando con Credenciales

Nunca codifique información sensible (contraseñas, tokens, claves API) directamente en el Jenkinsfile. Utilice el sistema de Gestión de Credenciales incorporado de Jenkins.

El paso withCredentials le permite acceder de forma segura a los secretos almacenados:

stage('Authenticate Registry') {
    steps {
        withCredentials([usernamePassword(credentialsId: 'docker-registry-creds', 
                                          passwordVariable: 'PASS', 
                                          usernameVariable: 'USER')]) {
            sh "docker login -u ${USER} -p ${PASS} ${CONTAINER_REGISTRY}"
        }
    }
}

Advertencia: Selección de Agente

Consejo: Defina siempre su agent específicamente usando una label en lugar de agent any. Usar agent any significa que la pipeline podría ejecutarse en el nodo controlador de Jenkins, lo cual es un riesgo de seguridad y puede afectar el rendimiento del controlador. Asegúrese de tener agentes de Jenkins (nodos) configurados correctamente con las herramientas necesarias (Docker, Maven, Node.js) instaladas.

Conclusión

La Pipeline Declarativa de Jenkins ofrece un marco potente, legible y mantenible para implementar la Integración Continua y la Entrega Continua. Al definir la estructura del flujo de trabajo, incluyendo agentes, variables de entorno, etapas secuenciales y acciones posteriores a la construcción, usted obtiene visibilidad y control completos sobre su proceso de automatización de software. Con este Jenkinsfile fundamental establecido, ahora está listo para integrar pasos más complejos, como escaneo de seguridad automatizado, publicación de artefactos y promociones a múltiples entornos.