Rol de Ansible Atlassian BambooAgent

Este rol realiza lo necesario para ejecutar un agente remoto de Atlassian Bamboo en una máquina objetivo.

El rol lleva a cabo las siguientes acciones:

• crea el usuario que ejecuta el agente de Bamboo,
• instala el certificado del servidor de Bamboo para que sea posible descargar el archivo jar del agente de Bamboo directamente desde el servidor sin eludir ninguna seguridad (opcional).
• crea los scripts de inicio para el agente de Bamboo, completa rutas adicionales (herramientas de construcción) y opciones adicionales (ya sea del sistema como CUDA_VISIBLE_DEVICES o configuraciones adicionales del agente de Bamboo).
• registra el script de inicio del agente de Bamboo para que se inicie al arrancar el sistema.
• registra un servicio de inicio automático en el sistema operativo.
• completa las capacidades del agente.
• cambia la carpeta de construcción y el nombre del agente.

Requisitos

Java debe estar instalado en el sistema operativo de destino. Considera usar el rol ansible-atlassian-bambooagent-oracle-java para esto.

Variables del rol

Las siguientes variables deben establecerse para el rol.

Java

La versión del agente debe funcionar bien con el Java instalado. Por ejemplo, la versión 5.11 del agente de Bamboo requiere Java 8. El JAVA_HOME se establece automáticamente en OSX durante el inicio del agente.

Capacidad de Bamboo

Una capacidad específica puede ser declarada automáticamente por el agente utilizando una característica de Atlassian Bamboo: el archivo de capacidades. Este archivo tiene un formato muy simple y se encuentra dentro de la carpeta de instalación.

El archivo de capacidad recibirá las capacidades que se declaren al ejecutar el playbook. Esta es una lista de pares (diccionario) que indica el nombre de la capacidad junto con su valor.

- name: '[BAMBOO] declaración de capacidades vacías'
  set_fact:
    bamboo_capabilities: {}

Es posible actualizar las capacidades primero leyendo las de disco, usando por ejemplo un pre_task:

pre_tasks:
    - name: Leyendo el archivo de capacidades del agente
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

y luego escribirlas en disco como un post_task:

post_tasks:
  - name: Actualizando el archivo de capacidades del agente
    include_role:
      name: atlassian_bambooagent_role
      tasks_from: write_capability

La lectura y escritura utilizan el diccionario bamboo_capabilities (como un fact) como entrada/salida. Las funciones se encargan de escapar adecuadamente los / y \ en las diferentes plataformas.

Un play típico en un playbook se vería así:

- hosts: my-bamboo-agents
  vars:
    # esta variable debe establecerse para recuperar el archivo de capacidades
    - bambooagent_agent_root: "la raíz especificada del agente o la predeterminada"

  pre_tasks:
    # esto leerá el archivo de capacidades si existe
    - name: Leyendo el archivo de capacidades del agente
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

  post_tasks:
    # esto actualizará el archivo de capacidades y lo creará si es necesario
    - name: Actualizando el archivo de capacidades del agente
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

  tasks:
    # ... tareas

    - name: 'actualizar capacidad'
      set_fact:
        bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
      loop:
        - key: 'bamboo_custom_capability'
          value: "bamboo_custom_capability_value"
        # ...

Eliminando capacidades

Con el tiempo, poder mantener las capacidades es importante, especialmente cuando aumenta el número de agentes. Usando las mismas herramientas que arriba, es posible eliminar capacidades que se han vuelto obsoletas. Esto se puede hacer indicando en la lista bamboo_capabilities_to_remove los nombres de las capacidades que necesitan ser eliminadas.

- hosts: my-bamboo-agents
  vars:
    - bambooagent_agent_root: "la raíz especificada del agente o la predeterminada"

  tasks:
    - name: '[BAMBOO] eliminar capacidades obsoletas'
      set_fact:
        bamboo_capabilities_to_remove:
          - cache_folder1
          - qt_version3

  post_tasks:
    # esto actualizará el archivo de capacidades y lo creará si es necesario
    - name: Actualizando el archivo de capacidades del agente
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

Obtener el UUID del agente

El rol contiene un ayudante dedicado para recuperar el UUID del agente, lo que facilita gestionar los agentes aprobados en la vista de administración de los agentes de Bamboo. Esto se puede usar como el siguiente ejemplo, que llenará la variable bamboo_agent_UUID.

- hosts: my-bamboo-agents
  vars:
    - bambooagent_agent_root: "la raíz especificada del agente o la predeterminada"

  tasks:
    - name: Recupera el UUID del Agente
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: get_agent_uuid
      tags: ['never', 'bamboo_agent_uuid']

    - name: Imprimir el UUID del agente
      debug:
        var: bamboo_agent_UUID
      tags: ['never', 'bamboo_agent_uuid']

Certificado HTTPS para el servicio

El certificado debe estar en la variable certificate_files (una lista de certificados que son pares de alias/nombre de archivo) como el siguiente:

- certificate_files:
  - alias: "bamboo_server_certificate_alias"
    file: "{{some_root_location}}/bamboo_server_certificate.crt"

Carpeta de construcción

La carpeta de construcción puede ser cambiada después de la instalación y el registro adecuado del agente con el servidor de Bamboo. Esto es particularmente relevante en los siguientes escenarios:

• el agente está instalado en Windows: la longitud de las rutas importa para la mayoría de las herramientas que usarías, acortar el prefijo de la ruta es importante. Entonces es posible instalar el agente en alguna ubicación, y luego apuntar la carpeta de construcción a una carpeta directamente bajo la raíz de una partición.
• cuando deseas separar los datos de construcción de los datos y la configuración del agente: podrías usar diferentes discos (rápidos para la carpeta de construcción, más pequeños para la del agente) o tener una política de respaldo separada en esas carpetas.

Como se mencionó, la carpeta de construcción solo puede ser configurada después de que el agente haya sido correctamente instalado y registrado con el servidor de Bamboo. Después de esto, la estructura de carpetas correcta y el archivo de configuración aparecerán en la carpeta de instalación y será posible cambiar la carpeta de construcción.

Un ejemplo de cómo cambiar la carpeta de construcción sería este:

- hosts: windows-agents
  vars:
    - bambooagent_agent_root: "{{ bamboo_agents[inventory_hostname].bamboo_folder }}"

  tasks:
    - name: Actualizando la configuración de los agentes
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: update_agent_configuration
      vars:
        bamboo_agent_name: "nuevo-nombre-para-el-agente"
        bamboo_agent_description: "Agente remoto en XYZ"
        bamboo_build_folder: "D:\\"
        bambooagent_user: "bamboo_user" # opcional para crear la carpeta de construcción con los derechos adecuados
      tags: ['never', 'update_bamboo_config']

La tarea anterior no se ejecutará a menos que se especifique explícitamente en la línea de comandos. Es mejor detener el servicio antes de realizar esta actualización. Desde la línea de comandos, se puede lograr así, o totalmente integrado en un play:

ansible \
  nombre-o-grupo-de-la-máquina-remota \
  -m win_service \
  -a "name=bamboo-remote-agent state=stopped" \
  --inventory inventory-bamboo.yml \
  --become

# modificamos algunas de las configuraciones de instalación
ansible-playbook \
  --limit nombre-o-grupo-de-la-máquina-remota \
  --inventory inventory-bamboo.yml \
  --become \
  --tags=update_bamboo_config \
  playbooks/my-windows-play.yml

# reiniciamos el servicio nuevamente
ansible \
  nombre-o-grupo-de-la-máquina-remota \
  -m win_service \
  -a "name=bamboo-remote-agent state=restarted" \
  --inventory inventory-bamboo.yml \
  --become

Ten en cuenta que algunos de los campos actualizados no aparecerán en el servidor. Eliminar el agente del servidor y volver a registrarlo después debería funcionar (error conocido en los agentes de Bamboo).

Dependencias

No hay dependencias adicionales.

Ejemplo de Playbook

- hosts: bambooagents

  vars:
    - program_location: /folder/containing/installers/
    - server_url: https://my.local.network/bamboo/

    # la carpeta de inicio del agente de Bamboo (por ejemplo, debería ser diferente en Linux/OSX/etc)
    - local_var_bambooagent_install_root: "/somebigdrive/bambooagent"

    # usado para calcular el nombre del archivo JAR del agente de bamboo para transferirlo al remoto
    - bambooagent_version: "6.8.1"

    # esto apunta a una copia local del .jar que se puede descargar del servidor.
    - local_copy_of_bamboo_agent_jar: "/some/folder/{{ bambooagent_jar_filename }}"

  pre_tasks:
    # Lee las capacidades si ya existen, de lo contrario devuelve un dict vacío
    - name: Leyendo el archivo de capacidades del agente
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

  post_tasks:
    # Escribe las capacidades de vuelta en el archivo
    - name: Actualiza las capacidades del agente
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

  roles:
    # Esto instala el agente de bamboo y sobrescribe las variables
    - name: instalando el agente de bamboo
      role: atlassian_bambooagent_role
      vars:
        bambooagent_user: "bamboo_service_user"
        bambooagent_group: "bamboo_service_group"
        bambooagent_agent_root: "/mount/folder/fast/disk/bamboo-agent"
        bambooagent_service_name: atlassian-bambooagent
        bamboo_server_url: "{{ server_url }}"
        bamboo_java_jar_file: "{{ local_copy_of_bamboo_agent_jar }}"
        bambooagent_install_root: "{{ local_var_bambooagent_install_root }}"
        certificate_files:
          - alias: "my.certificate.authority.crt"
            file: "/some/local/folder/my.certificate.authority.crt"
      tags: bamboo


  tasks:
    # Ejemplo para declarar capacidades personalizadas
    - name: '[BAMBOO] capacidades predeterminadas'
      set_fact:
        bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
      loop:
        - key: 'operating_system'
          value: "{{ bamboo_operating_system }}"
        - key: agent_name
          value: "{{ ansible_fqdn }}"
        - key: osversion
          value: "{{ ansible_distribution_version.split('.')[:2] | join('.') }}"

    # Ejemplo declarando capacidades de constructor del sistema (binario de python, ya instalado)
    - block:
      - name: '[BAMBOO] ejecutando python'
        command: python -c "import sys; print('%d.%d\n%s' % (sys.version_info.major, sys.version_info.minor, sys.executable))"
        register: bamboo_capability_python_version

      - name: '[BAMBOO] registrar python'
        set_fact:
          bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
        loop:
          - key: 'system.builder.command.python{{bamboo_capability_python_version.stdout_lines.0}}'
            value: '{{ bamboo_capability_python_version.stdout_lines.1 }}'

Licencia

BSD

Información del autor

Cualquier comentario sobre Ansible, PR o informes de errores son bienvenidos del proyecto correspondiente en Github.

Registro de cambios

0.1

• primera versión oficial (no realmente, pero las versiones anteriores no tenían registros de cambios)
• Cambio del nombre del rol a atlassian_bambooagent_role para seguir esas pautas
• revisión adicional
• nueva opción bamboo_verify_certificates para evitar verificar el certificado del servidor al obtener el JAR de Bamboo. Esto es útil solo en OSX (ver aquí) cuando el servidor tiene un certificado público. En caso de que el servidor use su propia CA, esa CA ya está instalada a nivel de sistema por el rol.
• ahora el servicio instalado en Windows se toma de la variable bambooagent_service_name (y no del predeterminado bamboo-remote-agent). Esto hace posible ejecutar varios agentes en la misma máquina con Windows.
• arreglo de errores en Windows al obtener el JAR del servidor de Bamboo
• arreglo de errores al escribir las capacidades (Windows vs el resto del mundo)