Роль Ansible Atlassian BambooAgent

Эта роль выполняет необходимые действия для запуска удаленного агента Atlassian Bamboo на целевой машине.

Роль выполняет следующие действия:

• создает пользователя, под которым будет работать агент Bamboo,
• устанавливает сертификат сервера Bamboo, чтобы можно было загружать файл jar агента Bamboo напрямую с сервера без обхода какой-либо безопасности (по желанию),
• создает сценарии автозагрузки для агента Bamboo, заполняет дополнительные пути (инструменты сборки) и дополнительные параметры (либо из системы, такие как CUDA_VISIBLE_DEVICES, либо из конфигураций агента Bamboo),
• регистрирует сценарий запуска агента Bamboo для его запуска при загрузке системы,
• регистрирует сервис автозапуска в операционной системе,
• наполняет возможности агента,
• изменяет папку сборки и имя агента.

Требования

Java должна быть установлена на целевой операционной системе. Рекомендуется использовать роль ansible-atlassian-bambooagent-oracle-java для этого.

Переменные роли

Следующие переменные должны быть заданы для роли.

Java

Версия агента должна хорошо работать с установленной Java. Например, версия 5.11 агента Bamboo требует Java 8. Переменная JAVA_HOME устанавливается автоматически на OSX во время запуска агента.

Возможности Bamboo

Специальные возможности могут быть объявлены автоматически агентом с использованием функции Atlassian Bamboo: файла возможностей. Этот файл имеет очень простой формат и находится внутри папки установки.

Файл возможностей будет получать возможности, объявленные при выполнении плейбука. Это список пар (словари), указывающий имя возможности и ее значение.

- name: '[BAMBOO] декларация пустых возможностей'
  set_fact:
    bamboo_capabilities: {}

Возможно обновить возможности, сначала прочитав их с диска, например, с помощью pre_task:

pre_tasks:
    - name: Чтение файла возможностей агента
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

И затем записать их на диск с помощью post_task:

post_tasks:
  - name: Обновление файла возможностей агента
    include_role:
      name: atlassian_bambooagent_role
      tasks_from: write_capability

Чтение и запись оба используют словарь bamboo_capabilities (как fact) как вход/выход. Функции заботятся об экранировании / и \ правильно на разных платформах.

Типичный плей в плейбуке будет выглядеть следующим образом:

- hosts: my-bamboo-agents
  vars:
    # эта переменная должна быть установлена для получения файла возможностей
    - bambooagent_agent_root: "указанный корень агента или по умолчанию"

  pre_tasks:
    # это будет читать файл возможностей, если он существует
    - name: Чтение файла возможностей агента
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

  post_tasks:
    # это обновит файл возможностей и создаст его, если это необходимо
    - name: Обновление файла возможностей агента
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

  tasks:
    # ... задачи

    - name: 'обновить возможность'
      set_fact:
        bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
      loop:
        - key: 'bamboo_custom_capability'
          value: "bamboo_custom_capability_value"
        # ...

Удаление возможностей

Со временем возможность поддерживать возможности важна, особенно когда количество агентов увеличивается. Используя те же инструменты, что и выше, можно удалить возможности, которые стали устаревшими. Это можно сделать, указав в списке bamboo_capabilities_to_remove имена возможностей, которые необходимо удалить.

- hosts: my-bamboo-agents
  vars:
    - bambooagent_agent_root: "указанный корень агента или по умолчанию"

  tasks:
    - name: '[BAMBOO] удаление устаревших возможностей'
      set_fact:
        bamboo_capabilities_to_remove:
          - cache_folder1
          - qt_version3

  post_tasks:
    # это обновит файл возможностей и создаст его, если это необходимо
    - name: Обновление файла возможностей агента
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

Получение UUID агента

Роль содержит специальный вспомогательный инструмент для извлечения UUID агента, что облегчает управление одобренными агентами в интерфейсе администрирования агентов Bamboo. Это можно использовать, как в следующем примере, который заполнит переменную bamboo_agent_UUID.

- hosts: my-bamboo-agents
  vars:
    - bambooagent_agent_root: "указанный корень агента или по умолчанию"

  tasks:
    - name: Извлечение UUID агента
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: get_agent_uuid
      tags: ['never', 'bamboo_agent_uuid']

    - name: Печать UUID агента
      debug:
        var: bamboo_agent_UUID
      tags: ['never', 'bamboo_agent_uuid']

HTTPS сертификат для сервиса

Сертификат должен быть в переменной certificate_files (список сертификатов, состоящий из пар алиас/имя файла) следующим образом:

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

Папка сборки

Папка сборки может быть изменена после установки и правильной регистрации агента на сервере Bamboo. Это особенно актуально в следующих сценариях:

• агент установлен на Windows: длина путей имеет значение для большинства инструментов, которые вы будете использовать, сокращение префикса пути важно. Затем возможно установить агента в некотором месте и затем указать папку сборки на папку непосредственно под корнем раздела.
• когда вы хотите отделить данные сборки от данных и конфигурации агента: вы можете использовать разные диски (быстрые для папки сборки, меньшие для данных агента), или иметь отдельную политику резервного копирования для этих папок.

Как уже упоминалось, папка сборки может быть установлена только после того, как агент был правильно установлен и зарегистрирован на сервере Bamboo. После этого в папке установки появится правильная структура папок и файл конфигурации, и можно будет изменить папку сборки.

Пример изменения папки сборки может быть таким:

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

  tasks:
    - name: Обновление конфигурации агентов
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: update_agent_configuration
      vars:
        bamboo_agent_name: "новое-имя-агента"
        bamboo_agent_description: "Удаленный агент на XYZ"
        bamboo_build_folder: "D:\\"
        bambooagent_user: "bamboo_user" # необязательно для создания папки сборки с правильными правами
      tags: ['never', 'update_bamboo_config']

Предыдущая задача не будет выполнена, если это не указано явно в командной строке. Лучше остановить сервис перед выполнением этого обновления. Из командной строки это можно сделать так или полностью интегрировано в плей:

ansible \
  имя-или-группа-удаленной-машины \
  -m win_service \
  -a "name=bamboo-remote-agent state=stopped" \
  --inventory inventory-bamboo.yml \
  --become

# мы изменяем некоторые настройки установки
ansible-playbook \
  --limit имя-или-группа-удаленной-машины\
  --inventory inventory-bamboo.yml \
  --become \
  --tags=update_bamboo_config \
  playbooks/my-windows-play.yml

# мы снова перезапускаем сервис
ansible \
  имя-или-группа-удаленной-машины \
  -m win_service \
  -a "name=bamboo-remote-agent state=restarted" \
  --inventory inventory-bamboo.yml \
  --become

Обратите внимание, что некоторые из обновленных полей не появятся на сервере. Удаление агента с сервера и последующая его повторная регистрация должны помочь (известная ошибка в агентах Bamboo).

Зависимости

Нет дополнительных зависимостей.

Пример плейбука

- hosts: bambooagents

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

    # домашняя папка агента Bamboo (например, должна отличаться на Linux/OSX и т.д.)
    - local_var_bambooagent_install_root: "/somebigdrive/bambooagent"

    # используется для вычисления имени JAR файла агента Bamboo, который будет передан на удаленный
    - bambooagent_version: "6.8.1"

    # указывает на локальную копию .jar, которая может быть загружена с сервера.
    - local_copy_of_bamboo_agent_jar: "/some/folder/{{ bambooagent_jar_filename }}"

  pre_tasks:
    # Читает возможности, если они уже существуют, иначе возвращает пустой словарь
    - name: Чтение файла возможностей агента
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

  post_tasks:
    # Записывает возможности обратно в файл
    - name: Обновление возможностей агента
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

  roles:
    # Это устанавливает агента Bamboo и переопределяет переменные
    - name: установка агента 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:
    # Пример объявления пользовательских возможностей
    - name: '[BAMBOO] стандартные возможности'
      set_fact:
        bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
      loop:
        - key: 'операционная система'
          value: "{{ bamboo_operating_system }}"
        - key: имя_агента
          value: "{{ ansible_fqdn }}"
        - key: версия_os
          value: "{{ ansible_distribution_version.split('.')[:2] | join('.') }}"

    # Пример объявления возможностей системного сборщика (бинарный файл python, уже установлен)
    - block:
      - name: '[BAMBOO] запуск 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] регистрация 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 }}'

Лицензия

BSD

Информация об авторе

Любые комментарии по Ansible, PR или сообщения об ошибках приветствуются в соответствующем проекте Github.

Журнал изменений

0.1

• первая официальная версия (на самом деле, предыдущие релизы не имели журналов изменений)
• Изменение имени роли на atlassian_bambooagent_role в соответствии с такими рекомендациями
• дополнительное линтирование
• новая опция bamboo_verify_certificates, чтобы избежать проверки сертификата сервера при получении JAR из Bamboo. Это полезно только на OSX (см. здесь), когда сервер имеет публичный сертификат. Если сервер использует свой собственный CA, этот CA уже установлен системно ролью.
• теперь устанавливаемый сервис на Windows берется из переменной bambooagent_service_name (а не по умолчанию bamboo-remote-agent). Это позволяет запускать несколько агентов на одной машине с Windows.
• исправление ошибок на Windows при получении JAR с сервера Bamboo
• исправление ошибок при записи возможностей (Windows против остального мира)