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.
Cada uno de los pasos que se llevan a cabo generan una notificación por Slack. El siguiente bloque de código se ejecuta siempre y se encarga de indicarle al usuario que el proceso ha iniciado, o bien, que un paso en específico ha iniciado.
El siguiente bloque de código se ejecuta siempre que un paso se haya realizado correctamente.
El siguiente bloque de código se ejecuta siempre que un paso no se complete correctamente.
Las últimas instrucciones de esta función se encargan de serializar el contenido de la variable attachments y de enviar la notificación por Slack, directamente al canal especificado para el proyecto. La función slackSend está definida en el plugin para Slack que el administrador de Jenkins instaló previamente, por lo que su definición escapa a este documento.
2) sendEMailNotification
Esta función se encarga de invocar a la función emailext, que se encuentra definida en el plugin de correo electrónico que el administrador de Jenkins instaló previamente.
Para invocar dicha función, se hace referencia a las siguientes variables de entorno de Jenkins:
- env.JOB_NAME: Indica el nombre del job que fue creado por el administrador de Jenkins para el despliegue del proyecto.
- env.BUILD_NUMBER: Indica el número de compilación del proyecto. Este es un número de base 1, que incrementa en 1 cada vez que se hace un nuevo despliegue.
- GIT_BRANCH: Indica el nombre de la rama del repositorio de código fuente del proyecto.
Anexo: Configuración de microservicios .NET Core
Esta sección surge a raíz de que al configurar jenkins para una aplicación de consola de .NET Core con un jenkinsfile similar al mencionado en los ejemplos de esta página se quedaba en espera de un ctrl+c, esto hacía que nunca fuera satisfactorio un despliegue, si tiene este problema, continué leyendo.
Para el correcto despliegue de una aplicación de consola .NET core en el Jenkinsfile se deberá:
- Contar con la apropiada configuración en IIS para desplegar una aplicación de este
- Detener la aplicación en IIS
- Publicar el proyecto
- Inicializar la aplicacion en IIS
1. Configuración en IIS
Se debe contar con una configuración similar a la siguiente en IIS para que se mantenga ejecutando la aplicación.
Luego de esa configuración dar la ruta absoluta donde se aloja el proyecto, la IP del servidor y el puerto por donde escuchará la aplicación.
2. Detener la aplicacion en IIS
El siguiente paso es detener la ejecución de la aplicación en IIS mediante el siguiente comando, de lo contrario no se podrá compilar y publicar el proyecto ya que marcará error de que un proceso (IIS) esta usando los recursos que se deben sobre-escribir en el deploy y debido a ello fallará la integración de Jenkins.
3. Publicar el proyecto
En la imagen se aprecia publicación del proyecto que esta de momento en el WORKSPACE de Jenkins, el cual tiene el cambio más reciente hecho al repositorio, este se publica en la ruta PATH_DEPLOYMENT, ruta que se inicializa en el stage Inicialización.
4. Inicializar proyecto en IIS
Por último solo se deberá iniciar nuevamente la aplicación en IIS, dejando la aplicación funcionando con los cambios más recientes.
Concluidos estos pasos ya puede proceder a consumir sus microservicios.
