emmetog.jenkins

Descripción general Versiones Perspectivas

Rol de Ansible para Jenkins

Instala y configura completamente Jenkins usando Ansible.

Este rol se utiliza cuando deseas tener toda tu configuración de Jenkins bajo control de versiones, para que puedas desplegar Jenkins de manera repetible y confiable, y tratar tu Jenkins como una Vaca en lugar de una Mascota.

Si buscas un rol para instalar Jenkins y quieres configurarlo todo a través de la interfaz web, y no te importa poder desplegar este mismo Jenkins completamente configurado de forma repetible, entonces no necesitas este rol. En su lugar, mira el rol de geerlingguy/ansible-role-jenkins.

Requisitos

Si vas a desplegar usando Docker, necesitas tener Docker instalado en el servidor. Docker, apt-get y yum son las únicas formas soportadas en este momento, aunque se pueden añadir más formas fácilmente, se aceptan PRs.

Instalación

Instala usando Ansible Galaxy:

$ ansible-galaxy install emmetog.jenkins

Variables del Rol

Las siguientes variables influyen en cómo se instala Jenkins:

jenkins_install_via: Controla cómo se instala Jenkins. Importante: Esta variable debe definirse con uno de los siguientes valores:
- docker: Instalar en un contenedor Docker
- apt: Instalar Jenkins directamente en sistemas Linux Ubuntu/Debian
- yum: Instalar Jenkins directamente en sistemas Linux RedHat/CentOS
jenkins_version: La versión exacta de Jenkins a instalar

Las siguientes variables influyen en cómo se configura Jenkins:

jenkins_url: La URL en la que Jenkins será accesible
jenkins_port: El puerto en el que Jenkins escuchará
jenkins_home: El directorio en el servidor donde vivirán las configuraciones de Jenkins
jenkins_admin: La dirección de correo electrónico del administrador del servidor de Jenkins
jenkins_java_opts: Opciones que se pasan al ejecutable de Java
jenkins_config_owner: Propietario de los archivos de configuración de Jenkins
jenkins_config_group: Grupo de los archivos de configuración de Jenkins
jenkins_auth: Cómo Ansible debe autenticarse con Jenkins (ver la sección "Autenticación y Seguridad" más abajo)
jenkins_url_health_check: qué URL usar para la verificación de salud después de que Jenkins se haya iniciado (por defecto es jenkins_url)
jenkins_health_check_user: si se define, utiliza autenticación básica para la verificación de salud con este nombre de usuario (útil si configuraste por ejemplo Google OAuth)
jenkins_health_check_password: si se define, utiliza autenticación básica para la verificación de salud con esta contraseña (útil si configuraste por ejemplo Google OAuth)

Las siguientes listas de variables influyen en los trabajos/plugins que se instalarán en Jenkins:

jenkins_jobs: Lista de nombres de los trabajos que se copiarán a Jenkins. El archivo config.xml debe existir bajo jenkins_source_dir_jobs/<job_name>
jenkins_plugins: Lista de IDs de plugins para instalar en Jenkins.
jenkins_custom_plugins: Lista de plugins personalizados para instalar en Jenkins.

Para una lista completa de variables, consulta defaults/main.yml.

Ejemplo de Playbook

- hosts: jenkins

  vars:
    jenkins_version: "2.73.1"
    jenkins_hostname: "jenkins.ejemplo.com"
    jenkins_port: 8080
    jenkins_install_via: "docker"
    jenkins_jobs:
      - "mi-primer-trabajo"
      - "otro-trabajo-asombroso"
    jenkins_include_secrets: true
    jenkins_include_custom_files: true
    jenkins_custom_files:
      - src: "jenkins.plugins.openstack.compute.UserDataConfig.xml"
        dest: "jenkins.plugins.openstack.compute.UserDataConfig.xml"
    jenkins_plugins:
      - git
      - blueocean
    jenkins_custom_plugins:
      - "openstack-cloud-plugin/openstack-cloud.jpi"

  roles:
    - emmetog.jenkins

Gestión de Archivos de Configuración

El ejemplo anterior buscará archivos de configuración de trabajos en {{ playbook_dir }}/jenkins-configs/jobs/mi-primer-trabajo/config.xml y {{ playbook_dir }}/jenkins-configs/jobs/otro-trabajo-asombroso/config.xml.

NOTA: Estas directorios son personalizables, consulta las variables del rol jenkins_source_dir_configs y jenkins_source_dir_jobs.

El rol también buscará {{ playbook_dir }}/jenkins-configs/config.xml. Este archivo config.xml será copiado al servidor y utilizado como plantilla de configuración del trabajo.

El ejemplo anterior también subirá el directorio completo de secretos bajo {{ playbook_dir }}/jenkins-configs/secrets, y también copiará archivos personalizados definidos en la variable {{ jenkins_custom_files }}. Ten en cuenta que las variables {{ jenkins_include_secrets }} y {{ jenkins_include_custom_files }} deben establecerse en true para que estas características funcionen. Además, el rol puede instalar plugins personalizados proporcionando los archivos .jpi o .hpi en la lista de variables {{ jenkins_custom_plugins }}.

El config.xml y los archivos personalizados se tratan como plantillas, por lo que puedes poner variables en ellos, incluidos los datos sensibles del vault de Ansible.

Cuando quieras hacer un cambio en un archivo de configuración, o agregar un nuevo elemento (como un trabajo, plugin, etc.), el flujo de trabajo normal es:

Haz el cambio en la interfaz de usuario de Jenkins
Copia los archivos XML resultantes de vuelta a tu VCS
Para los archivos recién creados, no olvides añadirlos a la lista respectiva:

Para nuevos trabajos, estos deben añadirse a jenkins_jobs
Para archivos personalizados, estos deben añadirse a jenkins_include_custom_files
Para plugins personalizados, estos deben añadirse a jenkins_custom_plugins

Ejemplo de Archivo de Configuración de Jenkins

En {{ jenkins_source_dir_configs }}/config.xml pones tu configuración global de Jenkins, por ejemplo:

<?xml version='1.1' encoding='UTF-8'?>
<hudson>
  <disabledAdministrativeMonitors/>
  <version>2.176.1</version>
  <installStateName>RESTART</installStateName>
  <numExecutors>1</numExecutors>
  <mode>EXCLUSIVE</mode>
  <useSecurity>true</useSecurity>
  <authorizationStrategy class="hudson.security.AuthorizationStrategy$Unsecured"/>
  <securityRealm class="hudson.security.HudsonPrivateSecurityRealm">
    <disableSignup>false</disableSignup>
    <enableCaptcha>false</enableCaptcha>
  </securityRealm>
  <disableRememberMe>false</disableRememberMe>
  <projectNamingStrategy class="jenkins.model.ProjectNamingStrategy$DefaultProjectNamingStrategy"/>
  <workspaceDir>${JENKINS_HOME}/workspace/${ITEM_FULLNAME}</workspaceDir>
  <buildsDir>${ITEM_ROOTDIR}/builds</buildsDir>
  <markupFormatter class="hudson.markup.EscapedMarkupFormatter"/>
  <jdks/>
  <viewsTabBar class="hudson.views.DefaultViewsTabBar"/>
  <myViewsTabBar class="hudson.views.DefaultMyViewsTabBar"/>
  <clouds/>
  <quietPeriod>0</quietPeriod>
  <scmCheckoutRetryCount>0</scmCheckoutRetryCount>
  <views>
    <hudson.model.AllView>
      <owner class="hudson" reference="../../.."/>
      <name>all</name>
      <filterExecutors>false</filterExecutors>
      <filterQueue>false</filterQueue>
      <properties class="hudson.model.View$PropertyList"/>
    </hudson.model.AllView>
  </views>
  <primaryView>all</primaryView>
  <slaveAgentPort>0</slaveAgentPort>
  <disabledAgentProtocols>
    <string>JNLP-connect</string>
    <string>JNLP2-connect</string>
  </disabledAgentProtocols>
  <label>master</label>
  <crumbIssuer class="hudson.security.csrf.DefaultCrumbIssuer">
    <excludeClientIPFromCrumb>false</excludeClientIPFromCrumb>
  </crumbIssuer>
  <nodeProperties/>
  <globalNodeProperties/>
</hudson>

Ejemplo de Archivo de Configuración de Trabajo

Aquí tienes un ejemplo de lo que podrías poner en {{ playbook_dir }}/jenkins-configs/jobs/mi-primer-trabajo/config.xml:

<?xml version='1.0' encoding='UTF-8'?>
<project>
  <actions/>
  <description>Mi primer trabajo, dice "hola mundo"</description>
  <keepDependencies>false</keepDependencies>
  <properties/>
  <scm class="hudson.scm.NullSCM"/>
  <canRoam>true</canRoam>
  <disabled>false</disabled>
  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
  <triggers/>
  <concurrentBuild>false</concurrentBuild>
  <builders>
    <hudson.tasks.Shell>
      <command>echo &quot;¡Hola Mundo!&quot;</command>
    </hudson.tasks.Shell>
  </builders>
  <publishers/>
  <buildWrappers/>
</project>

Autenticación y Seguridad

Este rol soporta los siguientes mecanismos de autenticación para Jenkins:

Autenticación basada en token API (recomendada, requiere al menos Jenkins 2.96)
Autenticación basada en crumb con el plugin Strict Crumb Issuer (requerido si NO se utilizan tokens API y Jenkins 2.176.2 o más reciente)
Sin seguridad (no recomendada)

Autenticación basada en token API

Se recomienda la autenticación basada en token API, pero requiere un poco de esfuerzo adicional para configurarla. La ventaja de los tokens API es que se pueden revocar fácilmente en Jenkins, y su uso también se rastrea. Además, los tokens API no requieren obtener un token de crumb, lo cual se ha vuelto más difícil desde la versión 2.172.2 de Jenkins (ver este boletín de seguridad.

Para crear un token API, deberás hacer lo siguiente:

Todos los tokens API deben pertenecer a un usuario específico. Así que, crea un usuario especial para despliegues, o inicia sesión como el administrador u otra cuenta.
En la página de configuración del usuario, haz clic en el botón "Agregar nuevo Token".
Guarda el valor del token, preferiblemente en un vault de Ansible.
Define las siguientes variables en tu playbook:

jenkins_auth: "api"
jenkins_api_token: "(definido en el vault de Ansible)"
jenkins_api_username: "(definido en el vault de Ansible)"

Crea una copia de seguridad del archivo $JENKINS_HOME/users/the_username/config.xml, donde the_username corresponde al usuario que posee el token API que acabas de crear.
Añade este archivo a tu host de control y asegúrate de que se despliegue en Jenkins en la lista jenkins_custom_files, así:

jenkins_custom_files:
  - src: "users/the_username/config.xml"
    dest: "users/the_username/config.xml"

Ten en cuenta que es posible que necesites cambiar el valor de src, dependiendo de dónde guardes el archivo en la máquina de control en relación al playbook.

Autenticación basada en crumb

La autenticación basada en crumb se puede utilizar para prevenir ataques de falsificación de solicitudes entre sitios y se recomienda si los tokens API son imprácticos. Nota: la autenticación basada en crumb solo funciona con la configuración de control de acceso "Cualquiera puede hacer cualquier cosa". Si tu configuración de Jenkins requiere una configuración de seguridad más estricta, deberías usar tokens API (documentados arriba).

La autenticación basada en crumb también puede ser un poco complicada de configurar debido a los recientes arreglos de seguridad en Jenkins. Para configurar CSRF, deberás hacer lo siguiente:

Si estás usando Jenkins >= 2.176.2, deberás instalar el plugin Strict Crumb Issuer. Esto se puede hacer con este rol añadiendo el ID strict-crumb-issuer a la lista jenkins_plugins.
En Jenkins, haz clic en "Administrar Jenkins" -> "Configurar Seguridad Global"
En la sección "Protección CSRF", habilita "Prevenir exploits de falsificación de solicitudes entre sitios", y luego selecciona "Strict Crumb Issuer" si usas Jenkins >= 2.176.2, o de lo contrario "Default Crumb Issuer". Ten en cuenta que para ver esta opción, deberás tener instalado el plugin Strict Crumb Issuer. Luego, también deberás hacer una copia de seguridad del archivo config.xml principal de Jenkins en el host de control.

Del mismo modo, para que lo anterior funcione, necesitarás al menos Ansible 2.9.0pre5 o 2.10 (que, al momento de escribir esto, están en desarrollo. Consulta este problema de Ansible para más detalles).

HTTPS

Si deseas habilitar HTTPS en Jenkins, esto se puede hacer de la siguiente manera:

Define jenkins_port_https al puerto que Jenkins debería escuchar
Define variables ya sea para el almacén de claves JKS o el certificado firmado por la CA:
- Para el almacén de claves JKS, deberás definir:
  - jenkins_https_keystore: Ruta al archivo del almacén de claves en el host de control, que será copiado al servidor de Jenkins por este rol.
  - jenkins_https_keystore_password: Contraseña para dicho almacén de claves JKS. Se recomienda usar el vault de Ansible para esto. IMPORTANTE: Esta cadena se escribirá en texto plano en el archivo de configuración de Jenkins en el servidor. También será visible en la lista de procesos del servidor. Considera migrar tu certificado a un archivo de certificado firmado (consulta abajo).
- Para un archivo de certificado firmado por la CA, deberás definir:
  - jenkins_https_certificate: Ruta al archivo del certificado, que será copiado al servidor de Jenkins por este rol. Se recomienda usar el vault de Ansible para este archivo.
  - jenkins_https_private_key: Clave privada para dicho certificado firmado por la CA. Se recomienda usar el vault de Ansible para este archivo.
Opcionalmente, jenkins_https_validate_certs debería definirse como false si estás usando un certificado autofirmado.

Si estás desplegando Jenkins con Docker, se recomienda usar un proxy inverso como jwilder/nginx-proxy o traefik en lugar de configurar Jenkins por sí mismo. Esto proporciona un poco más de flexibilidad y permite separaciones de responsabilidades. Consulta la documentación de esos proyectos para más detalles sobre cómo desplegar los proxies y configurar HTTPS.

Si usas un proxy inverso delante de la instancia de Jenkins y despliegas usando Docker, probablemente querrás establecer la variable jenkins_docker_expose_port en falso para que el puerto no se exponga en el host, solo al proxy inverso.