Ansible Atlassian BambooAgent 角色

该角色在目标机器上运行 Atlassian Bamboo 远程代理所需的操作。

此角色执行以下操作：

• 创建运行 Bamboo 代理的用户，
• 安装 Bamboo 服务器的证书，使得可以从服务器直接下载 Bamboo 代理的 jar 文件而不绕过任何安全措施（可选）。
• 创建 Bamboo 代理的启动脚本，填充额外路径（构建工具）和其他选项（来自系统的选项如 CUDA_VISIBLE_DEVICES 或额外的 Bamboo 代理配置）
• 注册 Bamboo 代理的启动脚本，以便在启动时启动代理。
• 在操作系统上注册自动启动服务
• 填充代理的能力
• 更改构建文件夹和代理名称

要求

目标操作系统上需要安装 Java。可以考虑使用 ansible-atlassian-bambooagent-oracle-java 角色。

角色变量

以下变量需要为该角色设置。

Java

代理的版本应与已安装的 Java 运行良好。例如，Bamboo 代理版本 5.11 需要 Java 8。在 OSX 上，JAVA_HOME 在代理启动时会自动设置。

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 代理中存在已知 bug）。

依赖

无额外依赖。

示例剧本

- 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"

    # 用于计算要传输到远程的 bamboo 代理 JAR 文件的名称
    - 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: 'operating_system'
          value: "{{ bamboo_operating_system }}"
        - key: agent_name
          value: "{{ ansible_fqdn }}"
        - key: osversion
          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

作者信息

欢迎在相应的 Github 项目上对 Ansible 提出任何评论、PR 或 bug 报告。

变更日志

0.1

• 第一个正式版本（实际上不是，但之前的发布没有变更日志）
• 将角色名称更改为 atlassian_bambooagent_role 以遵循 这些指南
• 额外的代码审查
• 新选项 bamboo_verify_certificates，在从 Bamboo 获取 JAR 时避免检查服务器证书。这在 OSX 上非常有用（见 这里），当服务器有公共证书时。 如果服务器使用自己的 CA，该 CA 已通过角色在系统范围内安装。
• 现在 Windows 上安装的服务取自变量 bambooagent_service_name（而不是默认的 bamboo-remote-agent）。这使得在同一台 Windows 机器上运行多个代理成为可能。
• 在从 Bamboo 服务器获取 JAR 时修复了在 Windows 上的 bug。
• 在编写能力时修复了 Windows 与其他操作系统的区别问题。