community.general.jenkins_plugin – Add or remove Jenkins plugin
community.general.jenkins_plugin – Add or remove Jenkins plugin
Note
This plugin is part of the community.general collection (version 2.0.1).
To install it use: ansible-galaxy collection install community.general
.
To use it in a playbook, specify: community.general.jenkins_plugin
.
Synopsis
- Ansible module which helps to manage Jenkins plugins.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
attributes string added in 2.3 of ansible.builtin |
The attributes the resulting file or directory should have. To get supported flags look at the man page for chattr on the target system. This string should contain the attributes in the same order as the one displayed by lsattr. The
| |
client_cert path |
PEM formatted certificate chain file to be used for SSL client authentication. This file can also include the key as well, and if the key is included, | |
client_key path |
PEM formatted file that contains your private key to be used for SSL client authentication. If | |
force boolean |
|
If Alias
|
force_basic_auth boolean |
|
Credentials specified with url_username and url_password should be passed in HTTP Header. |
group string |
Default: "jenkins" |
Name of the Jenkins group on the OS. |
http_agent string |
Default: "ansible-httpget" |
Header to identify as, generally appears in web server logs. |
jenkins_home path |
Default: "/var/lib/jenkins" |
Home directory of the Jenkins user. |
mode raw |
Default: "0644" |
File mode applied on versioned plugins. |
name string / required |
Plugin name. | |
owner string |
Default: "jenkins" |
Name of the Jenkins user on the OS. |
selevel string |
The level part of the SELinux file context. This is the MLS/MCS attribute, sometimes known as the When set to | |
serole string |
The role part of the SELinux file context. When set to | |
setype string |
The type part of the SELinux file context. When set to | |
seuser string |
The user part of the SELinux file context. By default it uses the When set to | |
state string |
|
Desired plugin state. If the |
timeout integer |
Default: 30 |
Server connection timeout in secs. |
unsafe_writes boolean added in 2.2 of ansible.builtin |
|
Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target file. By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target files, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted files, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. This option allows Ansible to fall back to unsafe methods of updating files when atomic operations fail (however, it doesn't force Ansible to perform unsafe writes). IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. |
updates_expiration integer |
Default: 86400 |
Number of seconds after which a new copy of the update-center.json file is downloaded. This is used to avoid the need to download the plugin to calculate its checksum when Set it to |
updates_url string |
Default: |
URL of the Update Centre. Used as the base URL to download the plugins and the update-center.json JSON file. |
url string |
Default: |
URL of the Jenkins server. |
url_password string |
The password for use in HTTP basic authentication. If the url_username parameter is not specified, the url_password parameter will not be used. | |
url_username string |
The username for use in HTTP basic authentication. This parameter can be used without url_password for sites that allow empty passwords | |
use_gssapi boolean added in 2.11 of ansible.builtin |
|
Use GSSAPI to perform the authentication, typically this is for Kerberos or Kerberos through Negotiate authentication. Requires the Python library gssapi to be installed. Credentials for GSSAPI can be specified with url_username/url_password or with the GSSAPI env var NTLM authentication is |
use_proxy boolean |
|
If |
validate_certs boolean |
|
If This should only be used on personally controlled sites using self-signed certificates. |
version string |
Plugin version number. If this option is specified, all plugin dependencies must be installed manually. It might take longer to verify that the correct version is installed. This is especially true if a specific version number is specified. Quote the version to prevent the value to be interpreted as float. For example if | |
with_dependencies boolean |
|
Defines whether to install plugin dependencies. This option takes effect only if the version is not defined. |
Notes
Note
- Plugin installation should be run under root or the same user which owns the plugin files on the disk. Only if the plugin is not installed yet and no version is specified, the API installation is performed which requires only the Web UI credentials.
- It’s necessary to notify the handler or call the service module to restart the Jenkins service after a new plugin was installed.
- Pinning works only if the plugin is installed and Jenkins service was successfully restarted after the plugin installation.
- It is not possible to run the module remotely by changing the url parameter to point to the Jenkins server. The module must be used on the host where Jenkins runs as it needs direct access to the plugin files.
Examples
- 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: no
- 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: http://localhost:8888
#
# 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: yes
build-pipeline-plugin:
version: "1.4.9"
pinned: no
enabled: yes
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: no
- name: Check if restart is required by any of the versioned plugins
ansible.builtin.set_fact:
jenkins_restart_required: yes
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: yes
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: http://localhost: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: no
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 }}"
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
plugin string |
success |
plugin name
Sample: build-pipeline-plugin |
state string |
success |
state of the target, after execution
Sample: present |
Authors
- Jiri Tyr (@jtyr)
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/community/general/jenkins_plugin_module.html