community.general.jenkins_node module – Manage Jenkins nodes

Note

This module is part of the community.general collection (version 10.0.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.jenkins_node.

New in community.general 10.0.0

Synopsis

  • Manage Jenkins nodes with Jenkins REST API.

Requirements

The below requirements are needed on the host that executes this module.

  • python-jenkins >= 0.4.12

Parameters

Parameter

Comments

labels

list / elements=string

When specified, sets the Jenkins node labels.

name

string / required

Name of the Jenkins node to manage.

num_executors

integer

When specified, sets the Jenkins node executor count.

offline_message

string

added in community.general 10.0.0

Specifies the offline reason message to be set when configuring the Jenkins node state.

If offline_message is given and requested state is not disabled, an error will be raised.

Internally offline_message is set via the toggleOffline API, so updating the message when the node is already offline (current state disabled) is not possible. In this case, a warning will be issued.

state

string

Specifies whether the Jenkins node should be present (created), absent (deleted), enabled (online) or disabled (offline).

Choices:

  • "enabled"

  • "disabled"

  • "present" ← (default)

  • "absent"

token

string

API token to authenticate with the Jenkins server.

url

string

URL of the Jenkins server.

Default: "http://localhost:8080"

user

string

User to authenticate with the Jenkins server.

Attributes

Attribute

Support

Description

check_mode

Support: partial

Check mode is unable to show configuration changes for a node that is not yet present.

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Create a Jenkins node using token authentication
  community.general.jenkins_node:
    url: http://localhost:8080
    user: jenkins
    token: 11eb751baabb66c4d1cb8dc4e0fb142cde
    name: my-node
    state: present

- name: Set number of executors on Jenkins node
  community.general.jenkins_node:
    name: my-node
    state: present
    num_executors: 4

- name: Set labels on Jenkins node
  community.general.jenkins_node:
    name: my-node
    state: present
    labels:
      - label-1
      - label-2
      - label-3

- name: Set Jenkins node offline with offline message.
  community.general.jenkins_node:
    name: my-node
    state: disabled
    offline_message: >
      This node is offline for some reason.

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

configured

boolean

Whether or not the Jenkins node was configured by the task.

Returned: success

created

boolean

Whether or not the Jenkins node was created by the task.

Returned: success

deleted

boolean

Whether or not the Jenkins node was deleted by the task.

Returned: success

disabled

boolean

Whether or not the Jenkins node was disabled by the task.

Returned: success

enabled

boolean

Whether or not the Jenkins node was enabled by the task.

Returned: success

name

string

Name of the Jenkins node.

Returned: success

Sample: "my-node"

state

string

State of the Jenkins node.

Returned: success

Sample: "present"

url

string

URL used to connect to the Jenkins server.

Returned: success

Sample: "https://jenkins.mydomain.com"

user

string

User used for authentication.

Returned: success

Sample: "jenkins"

Authors

  • Connor Newton (@phyrwork)