community.general.jenkins_plugin 模块 – 添加或移除 Jenkins 插件

注意

此模块是 community.general 集合 (版本 10.1.0) 的一部分。

如果您使用的是 ansible 包，则可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用： ansible-galaxy collection install community.general。

要在 playbook 中使用它，请指定： community.general.jenkins_plugin。

概要

• 一个帮助管理 Jenkins 插件的 Ansible 模块。

参数

参数	注释
attributes 别名：attr 字符串	结果文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上 *chattr* 的手册页。 此字符串应按 *lsattr* 显示的相同顺序包含属性。 默认情况下假定使用 = 运算符，否则需要在字符串中包含 + 或 - 运算符。
client_cert 路径	用于 SSL 客户端身份验证的 PEM 格式证书链文件。 此文件也可以包含密钥，如果包含密钥，则不需要 client_key。
client_key 路径	包含用于 SSL 客户端身份验证的私钥的 PEM 格式文件。 如果 client_cert 包含证书和密钥，则不需要此选项。
force 布尔值	如果为 yes，则不获取缓存的副本。 选项 false ← (默认) true
force_basic_auth 布尔值	使用 url_username 和 url_password 指定的凭据应通过 HTTP 标头传递。 选项 false ← (默认) true
group 字符串	操作系统上 Jenkins 组的 GID 或名称。 默认值： "jenkins"
http_agent 字符串	用于识别的标头，通常出现在 Web 服务器日志中。 默认值： "ansible-httpget"
jenkins_home 路径	Jenkins 用户的主目录。 默认值： "/var/lib/jenkins"
latest_plugins_url_segments 列表 / 元素=字符串 在 community.general 3.3.0 中添加	从 updates_url 内获取最新插件的路径。 默认值： ["latest"]
mode 任意	应用于版本化插件的文件模式。 默认值： "0644"
name 字符串 / 必需	插件名称。
owner 字符串	操作系统上 Jenkins 用户的 UID 或名称。 默认值： "jenkins"
selevel 字符串	SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时称为 range。 设置为 _default 时，如果可用，它将使用策略的 level 部分。
serole 字符串	SELinux 文件系统对象上下文的角色部分。 设置为 _default 时，如果可用，它将使用策略的 role 部分。
setype 字符串	SELinux 文件系统对象上下文的类型部分。 设置为_default时，如果可用，它将使用策略的type部分。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。 默认情况下，它在适用时使用system策略。 设置为_default时，如果可用，它将使用策略的user部分。
state 字符串	所需的插件状态。 如果设置为latest，则每次都会执行新版本检查。这适用于保持插件最新。 选项 "absent" "present" ← (默认) "pinned" "unpinned" "enabled" "disabled" "latest"
timeout 整数	服务器连接超时时间（秒）。 默认值： 30
unsafe_writes 布尔值	影响何时使用原子操作来防止目标文件系统对象的数据损坏或不一致读取。 默认情况下，此模块使用原子操作来防止目标文件系统对象的数据损坏或不一致读取，但有时系统配置错误或损坏，以至于无法执行原子操作。一个例子是 Docker 挂载的文件系统对象，这些对象无法在容器内以原子方式更新，只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全写入）。 重要！不安全写入容易出现竞争条件，并可能导致数据损坏。 选项 false ← (默认) true
update_json_url_segment 列表 / 元素=字符串 在 community.general 3.3.0 中添加	用于从更新中心获取 JSON 文件的 URL 段列表。 默认值： ["update-center.json", "updates/update-center.json"]
updates_expiration 整数	重新下载update-center.json文件的秒数。当指定state=latest时，这用于避免需要下载插件来计算其校验和。 如果不需要使用缓存文件，则将其设置为0。在这种情况下，当指定state=latest时，将始终下载插件文件以计算其校验和。 默认值： 86400
updates_url 列表 / 元素=字符串	用于获取update-center.json和直接插件文件的基 URL 列表。 自 community.general 3.3.0 起，可以是一个列表。 默认值： ["https://updates.jenkins.io", "http://mirrors.jenkins.io"]
url 字符串	Jenkins 服务器的 URL。 默认值： "https://:8080"
url_password 字符串	用于 HTTP 基本身份验证的密码。 如果没有指定url_username参数，则不会使用url_password参数。
url_username 字符串	用于 HTTP 基本身份验证的用户名。 对于允许空密码的站点，此参数可以不与url_password一起使用。
use_gssapi 布尔值 ansible-core 2.11 中添加	使用 GSSAPI 执行身份验证，通常用于 Kerberos 或通过 Negotiate 身份验证的 Kerberos。 需要安装 Python 库gssapi。 GSSAPI 的凭据可以使用url_username/url_password指定，也可以使用 GSSAPI 环境变量KRB5CCNAME指定自定义 Kerberos 凭据缓存。 即使安装了用于 NTLM 的 GSSAPI 机制，也不支持 NTLM 身份验证。 选项 false ← (默认) true
use_proxy 布尔值	如果为no，即使在目标主机上通过环境变量定义了代理，也不会使用代理。 选项 false true ← (默认)
validate_certs 布尔值	如果为no，则不会验证 SSL 证书。 这仅应在使用自签名证书的个人控制站点上使用。 选项 false true ← (默认)
version 字符串	插件版本号。 如果指定此选项，则必须手动安装所有插件依赖项。 验证是否安装了正确的版本可能需要更长时间。如果指定了特定版本号，则尤其如此。 引用版本以防止该值被解释为浮点数。例如，如果1.20未加引号，它将变为1.2。
versioned_plugins_url_segments 列表 / 元素=字符串 在 community.general 3.3.0 中添加	在updates_url内的路径，用于获取特定版本的插件。 默认值： ["download/plugins", "plugins"]
with_dependencies 布尔值	定义是否安装插件依赖项。 此选项仅在未定义version时生效。 选项 false true ← (默认)

属性

属性	支持	描述
check_mode	支持：完全支持	可以在check_mode下运行，并在不修改目标的情况下返回更改状态预测。
diff_mode	支持：不支持	在差异模式下，将返回有关已更改内容（或可能需要在check_mode下更改的内容）的详细信息。

注释

注意

• 插件安装应在 root 用户或拥有磁盘上插件文件的同一用户下运行。只有在尚未安装插件且未指定版本的情况下，才会执行 API 安装，这只需要 Web UI 凭据。

• 安装新插件后，需要通知处理程序或调用ansible.builtin.service模块重新启动 Jenkins 服务。

• 只有在插件已安装并且在插件安装后成功重新启动了 Jenkins 服务的情况下，固定才有效。

• 无法通过更改url参数使其指向 Jenkins 服务器来远程运行该模块。该模块必须在 Jenkins 运行的主机上使用，因为它需要直接访问插件文件。

示例

- name: Install plugin
  community.general.jenkins_plugin:
    name: build-pipeline-plugin

- name: Install plugin without its dependencies
  community.general.jenkins_plugin:
    name: build-pipeline-plugin
    with_dependencies: false

- name: Make sure the plugin is always up-to-date
  community.general.jenkins_plugin:
    name: token-macro
    state: latest

- name: Install specific version of the plugin
  community.general.jenkins_plugin:
    name: token-macro
    version: "1.15"

- name: Pin the plugin
  community.general.jenkins_plugin:
    name: token-macro
    state: pinned

- name: Unpin the plugin
  community.general.jenkins_plugin:
    name: token-macro
    state: unpinned

- name: Enable the plugin
  community.general.jenkins_plugin:
    name: token-macro
    state: enabled

- name: Disable the plugin
  community.general.jenkins_plugin:
    name: token-macro
    state: disabled

- name: Uninstall plugin
  community.general.jenkins_plugin:
    name: build-pipeline-plugin
    state: absent

#
# Example of how to authenticate
#
- name: Install plugin
  community.general.jenkins_plugin:
    name: build-pipeline-plugin
    url_username: admin
    url_password: p4ssw0rd
    url: https://:8888

#
# Example of how to authenticate with serverless deployment
#
- name: Update plugins on ECS Fargate Jenkins instance
  community.general.jenkins_plugin:
    # plugin name and version
    name: ws-cleanup
    version: '0.45'
    # Jenkins home path mounted on ec2-helper VM (example)
    jenkins_home: "/mnt/{{ jenkins_instance }}"
    # matching the UID/GID to one in official Jenkins image
    owner: 1000
    group: 1000
    # Jenkins instance URL and admin credentials
    url: "https://{{ jenkins_instance }}.com/"
    url_username: admin
    url_password: p4ssw0rd
  # make module work from EC2 which has local access
  # to EFS mount as well as Jenkins URL
  delegate_to: ec2-helper
  vars:
    jenkins_instance: foobar

#
# Example of a Play which handles Jenkins restarts during the state changes
#
- name: Jenkins Master play
  hosts: jenkins-master
  vars:
    my_jenkins_plugins:
      token-macro:
        enabled: true
      build-pipeline-plugin:
        version: "1.4.9"
        pinned: false
        enabled: true
  tasks:
    - name: Install plugins without a specific version
      community.general.jenkins_plugin:
        name: "{{ item.key }}"
      register: my_jenkins_plugin_unversioned
      when: >
        'version' not in item.value
      with_dict: "{{ my_jenkins_plugins }}"

    - name: Install plugins with a specific version
      community.general.jenkins_plugin:
        name: "{{ item.key }}"
        version: "{{ item.value['version'] }}"
      register: my_jenkins_plugin_versioned
      when: >
        'version' in item.value
      with_dict: "{{ my_jenkins_plugins }}"

    - name: Initiate the fact
      ansible.builtin.set_fact:
        jenkins_restart_required: false

    - name: Check if restart is required by any of the versioned plugins
      ansible.builtin.set_fact:
        jenkins_restart_required: true
      when: item.changed
      with_items: "{{ my_jenkins_plugin_versioned.results }}"

    - name: Check if restart is required by any of the unversioned plugins
      ansible.builtin.set_fact:
        jenkins_restart_required: true
      when: item.changed
      with_items: "{{ my_jenkins_plugin_unversioned.results }}"

    - name: Restart Jenkins if required
      ansible.builtin.service:
        name: jenkins
        state: restarted
      when: jenkins_restart_required

    - name: Wait for Jenkins to start up
      ansible.builtin.uri:
        url: https://:8080
        status_code: 200
        timeout: 5
      register: jenkins_service_status
      # Keep trying for 5 mins in 5 sec intervals
      retries: 60
      delay: 5
      until: >
         'status' in jenkins_service_status and
         jenkins_service_status['status'] == 200
      when: jenkins_restart_required

    - name: Reset the fact
      ansible.builtin.set_fact:
        jenkins_restart_required: false
      when: jenkins_restart_required

    - name: Plugin pinning
      community.general.jenkins_plugin:
        name: "{{ item.key }}"
        state: "{{ 'pinned' if item.value['pinned'] else 'unpinned'}}"
      when: >
        'pinned' in item.value
      with_dict: "{{ my_jenkins_plugins }}"

    - name: Plugin enabling
      community.general.jenkins_plugin:
        name: "{{ item.key }}"
        state: "{{ 'enabled' if item.value['enabled'] else 'disabled'}}"
      when: >
        'enabled' in item.value
      with_dict: "{{ my_jenkins_plugins }}"

返回值

常见的返回值已在此处记录，以下是此模块独有的字段

键	描述
plugin 字符串	插件名称 返回：成功 示例： "build-pipeline-plugin"
state 字符串	执行后目标的状态 返回：成功 示例： "present"

作者

• Jiri Tyr (@jtyr)

收藏链接

• 问题追踪器
• 代码仓库
• 寻求帮助
• 提交错误报告
• 请求功能
• 沟通