Pipeline
Sumario
Jenkins Pipeline
Esta página describe la estructura del archivo Jenkinsfile, necesario para la programación del Pipeline de cada proyecto que se despliegue con Jenkins.
Lo primero que se debe considerar es que el archivo Jenkinsfile debe estar contenido dentro de la raíz del proyecto, como se puede visualizar en la siguiente imagen.
De forma general, la estructura del archivo Jenkinsfile está dividida en 4 partes:
1. Importación de Librerías
2. Declaración de variables globales
3. Definición del Pipeline
4. Declaración de Funciones
Importación de Librerías
En esta sección se le indica a Jenkins cuáles serán las librerías externas que se necesitarán para realizar diversas operaciones a lo largo de la definición del Pipeline. En este caso utilizamos las siguientes dos librerías, las cuales nos permitirán trabajar con arreglos, como podrá ver más adelante.
Declaración de variables globales
El archivo Jenkinsfile está compuesto por un conjunto de funciones y por la definición del Pipeline, por lo que muchas veces será necesario configurar el valor de ciertos parámetros que posteriormente serán utilizados en otras partes del Pipeline. Para lograr esto, Jenkins nos permite definir cualquier cantidad de variables que sean necesarias, siguiendo la siguiente sintaxis.
def NOMBRE_VARIABLE
Para el proyecto que estamos empleando, se han definido las siguientes variables:
La función que cumple cada variable se describe a continuación:
- PATH_DEPLOYMENT: Es la carpeta en la cual se hará el despliegue del sistema, está directamente relacionada con la estructura de carpetas del IIS.
- PATH_CONFIGURATION: Es la carpeta en la cual se almacenan los archivos de configuración del proyecto (Web.config) específicos para el servidor en el cual se realiza la liberación del sistema (development, qa, etc.).
- PATH_BACKUP: Es la carpeta en la cual se realizará un respaldo completo del sistema, previo a realizar la liberación.
Definición del Pipeline
El Pipeline del proyecto que estamos desarrollando se compone de tres partes:
1. Parámetros
Se utiliza la instrucción "agent any" para indicarle a Jenkins que cualquiera de sus nodos disponibles puede realizar el proceso de despliegue.
Se utiliza el trigger pollSCM para comprobar periódicamente si existen cambios en el repositorio que deban integrarse. Mediante este trigger, Jenkins es capaz de detectar cuando sea necesario realizar un nuevo despliegue, el cual realizará de forma automática y siguiendo los pasos que se hayan definido en la sección de Stages.
La definición del periodo para este trigger se hace basándose en Cron
3. Stages
En esta parte se define cada uno de los pasos que debe seguir Jenkins para realizar el despliegue del proyecto.
En este ejemplo se utilizan 4 pasos:
a) Inicialización
En esta etapa se identifica el servidor en el cual se realizará el despliegue y se inicializan las variables globales, de la siguiente manera:
- En la línea 24 se declara el stage, especificando un nombre para ésta
- En la línea 26 se declaran las instrucciones que Jenkins debe ejecutar, uno detrás del otro
- Entre las líneas 28 y 53 se identifica el servidor en el cual se realizará el despliegue. Esto se hace obteniendo el nombre de la rama del repositorio de código fuente, mediante la variable de entorno GIT_BRANCH. Una vez que se ha obtenido el nombre de la rama, se establece el valor de las variables PATH_DEPLOYMENT, PATH_CONFIGURATION y PATH_BACKUP
- En la línea 56 se declaran los pasos a seguir, posteriores a la ejecución de las instrucciones definidas anteriormente
- En la línea 57 se definen los pasos a seguir después de haber completado el stage, sin importar el resultado de ésta
- En la línea 60 se definen los pasos a seguir siempre y cuando el resultado de la ejecución del stage sea exitoso
- En la línea 63 se definen los pasos a seguir cuando el resultado de la ejecución del stage sea incorrecto
b) Respaldo
En esta etapa se realiza un respaldo previo de todo el proyecto (previamente desplegado), antes de realizar un nuevo despliegue. Esto es de utilidad más adelante, cuando se define el proceso de rollback en caso de error.
El único paso definido para este stage es el de copiar los archivos contenidos en la carpeta especificada por la variable PATH_DEPLOYMENT y colocarlos en la carpeta especificada por la variable PATH_BACKUP, a través del comando xcopy.
Cuando se especifica la ejecución de un comando, a través de la consola del sistema, se utiliza la palabra reservada bat.
c) Despliegue
En esta etapa se realiza la copia del proyecto, desde la variable de entorno WORKSPACE de Jenkins, y se coloca en la carpeta definida por la variable PATH_DEPLOYMENT
d) Configuración
En esta etapa se cargan los archivos de configuración Web.config del proyecto. Para este proyecto se definen 3 archivos, cada uno de ellos se copia desde la carpeta especificada por la variable PATH_CONFIGURATION y se colocan en la carpeta especificada por la variable PATH_DEPLOYMENT.
El comando para copiar los archivos de configuración es diferente a los anteriores, ya que emplea un ciclo for para recorrer todos los archivos del proyecto y localizar aquellos que tengan la extensión .congif. Este proceso es así porque en .NET se pueden sobrecargar los archivos de configuración, logrando tener un archivo de configuración para cada ambiente.
Para el ejemplo que se está revisando se tienen tres líneas (111 a 113) y cada una de ellas realiza la copia de un archivo específico. En otros proyectos lo normal será un solo archivo o dos como máximo pero eso dependerá de cada uno.
4. Funciones
En este proyecto se utilizan las funciones sendSlackNotification y sendEMailNotification, las cuales se encargan de notificar sobre el progreso del despliegue, a través de Slack y de Correo Electrónico, respectivamente.
A continuación se describen ambas funciones.
1) sendSlackNotification
Esta función se encarga de enviar notificaciones por Slack. Para ello recibe los siguientes parámetros:
- stageName: Es el nombre del stage en la cual se invoca a esta función.
- stageStatus Indica el estatus del proceso, el cual puede ser always, success o failure.
- isFirstStage Indica si se debe enviar un mensaje de inicio del despliegue. Su valor por defecto es false.
Las primeras instrucciones de la función se encargan de declarar el objeto attachment, en el cual se almacenan los mensajes que serán mostrados. Se define el color de los mensajes y se coloca un mensaje por defecto en caso de que la notificación no se pueda enviar.
