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

注意

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

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

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

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

概要

• Ansible 模块，用于帮助管理 Jenkins 插件。

参数

参数	注释
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 用户的 home 目录。 默认: "/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 属性，有时称为 范围。 设置为 _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 integer	服务器连接超时时间，单位为秒。 默认值: 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 integer	下载新的 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://127.0.0.1:8080"
url_password 字符串	用于 HTTP 基本身份验证的密码。 如果未指定 url_username 参数，则不会使用 url_password 参数。
url_username 字符串	用于 HTTP 基本身份验证的用户名。 对于允许空密码的站点，可以使用此参数，而无需 url_password。
use_gssapi 布尔值 在 ansible-core 2.11 中添加	使用 GSSAPI 执行身份验证，通常用于 Kerberos 或通过协商进行 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	支持: 无	当处于 diff 模式时，将返回有关已更改（或可能需要在 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://127.0.0.1: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://127.0.0.1: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)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 寻求帮助
• 提交错误报告
• 请求功能
• 沟通