REFERENCE.md

Reference

Table of Contents

Classes

Public Classes

• jenkins: This class manages the Jenkins CI/CD service. Note that if different jenkins listening port(s) are configur
• jenkins::cli::config: This class provides configuration values to override defaults and fact data for PuppetX::Jenkins::Provider::Clihelper based providers. Defau
• jenkins::cli_helper: A helper script for creating resources via the Jenkins cli
• jenkins::master: Install a master
• jenkins::security: Jenkins security configuration
• jenkins::slave: === Examples class { 'jenkins::slave': masterurl => 'http://jenkins-master1.example.com:8080', ui_user => 'adminuser', ui_pass =>

Private Classes

• jenkins::cli: Allow Jenkins commands to be issued from the command line
• jenkins::cli::reload: Command Jenkins to reload config.xml via the CLI.
• jenkins::config: Wire up the configuration
• jenkins::direct_download: Support for directly downloading a package file - for when no repository is available
• jenkins::firewall: Integrate with the puppetlabs-firewall module for opening the port to Jenkins automatically
• jenkins::jobs: Create Jenkins Jobs
• jenkins::package: Installation of the Jenkins native package.
• jenkins::params: Default parameters
• jenkins::plugins: Install Jenkins plugins
• jenkins::proxy: Configure the proxy part
• jenkins::repo: Pull in the platform specific repo classes
• jenkins::repo::debian: Set up the apt repo on Debian-based distros
• jenkins::repo::el: Set up the yum repo on Red Hat-based distros
• jenkins::repo::suse: Set up the Zypper repo on SUSE-based distros
• jenkins::service: Manage the Jenkins service
• jenkins::user_setup: Optionally create the jenkins user and make sure all directories have proper permissions setup.
• jenkins::users: Create Jenkins users

Defined types

Public Defined types

• jenkins::augeas: Change config files using augeas
• jenkins::cli::exec: Executing custom helper script commands via the Jenkins CLI.
• jenkins::credentials: Jenkins credentials via the CloudBees Credentials plugin
• jenkins::job: Manage Jenkins jobs given a name and config xml
• jenkins::plugin: Manage the state of an installed plugin
• jenkins::user: Manage Jenkins user accounts

Private Defined types

• jenkins::job::absent: Removes a jenkins build job
• jenkins::job::present: Creates or updates a jenkins build job

Functions

• jenkins_port: Return the configurad Jenkins port value (corresponds to /etc/defaults/jenkins -> JENKINS_PORT Example: $port = jenkins_port()
• jenkins_prefix: Return the configured Jenkins prefix value (corresponds to /etc/defaults/jenkins -> PREFIX) Example: $prefix = jenkins_prefix()

Data types

• Jenkins::Tunnel: A custom data type for a jenkins tunnel verification

Classes

jenkins

This class manages the Jenkins CI/CD service.

Note that if different jenkins listening port(s) are configured via jenkins::port and jenkins::config_hash resource, "bad things" are likely to happen. This is a known implementation problem with this module that can not be fixed without breaking backwards compatibility.

Examples

Bulk sysconf

class{ 'jenkins':
  config_hash => {
    'JENKINS_PORT' => { 'value' => '9090' },
  }
}

Bulk plugin installation (code)

class{ 'jenkins::plugins':
  plugin_hash => {
    'git' => { version => '1.1.1' },
    'parameterized-trigger' => {},
    'multiple-scms' => {},
    'git-client' => {},
    'token-macro' => {},
  }
}

Bulk plugin installation (hiera)

jenkins::plugin_hash:
   git:
      version: '1.1.1'
   parameterized-trigger: {}
   multiple-scms: {}
   git-client: {}
   token-macro: {}

Bulk user creation (code)

class{ 'jenkins':
  user_hash => {
    'user1' => {
      'password' => 'pass1',
       'email'   => '[email protected]',
    }
  }
}

Bulk user creation (hiera)

jenkins::user_hash:
  user:
    password: 'pass1'
    email: '[email protected]'

Manage version of credentials plugin (hiera)

jenkins::default_plugins: []
jenkins::plugin_hash:
  credentials:
    version: 2.1.5
    digest_string: 7db002e7b053f863e2ce96fb58abb98a9c01b09c
    digest_type: sha1

Explicitly manage all plugins (hiera)

jenkins::default_plugins: []
jenkins::purge_plugins: true
jenkins::plugin_hash:
  credentials:
    version: '2.1.10'
  support-core:
    version: '2.38'
  # support-core deps
  metrics:
    version: '3.1.2.9'
  jackson2-api:
    version: '2.7.3'
  bouncycastle-api:
    version: '2.16.0'
  # /support-core deps

Parameters

The following parameters are available in the jenkins class:

• version
• lts
• repo
• package_name
• direct_download
• package_cache_dir
• package_provider
• manage_service
• service_enable
• service_ensure
• service_override
• service_provider
• config_hash
• plugin_hash
• job_hash
• user_hash
• configure_firewall
• install_java
• repo_proxy
• proxy_host
• proxy_port
• no_proxy_list
• cli
• cli_ssh_keyfile
• cli_username
• cli_password
• cli_password_file
• cli_tries
• cli_try_sleep
• port
• libdir
• manage_datadirs
• localstatedir
• executors
• slaveagentport
• manage_user
• user
• manage_group
• group
• default_plugins
• default_plugins_host
• purge_plugins

version

Data type: String

package to install

• installed (Default) do NOT update jenkins to the most recent version.
• latest automatically update the version of jenkins to the current version available via your package manager.

Default value: 'installed'

lts

Data type: Boolean

use the upstream jenkins "Long Term Support" repos

• false Use the most up to date version of jenkins
• true (Default) Use LTS version of jenkins

Default value: true

repo

Data type: Boolean

configure upstream jenkins package repos

false means do NOT configure the upstream jenkins package repo. This means you'll manage a repo manually outside this module. This can also be your distribution's repo.

Default value: $jenkins::params::repo

package_name

Data type: String

Optionally override the package name

Default value: 'jenkins'

direct_download

Data type: Optional[String]

URL to jenkins package

Ignore repository based package installation and download the package directly. Leave as undef (the default) to download using your OS package manager

Default value: undef

package_cache_dir

Data type: Stdlib::Absolutepath

Directory in which to store a direct_download package

Default value: '/var/cache/jenkins_pkgs'

package_provider

Data type: Optional[String]

Override the package resource provider

This only has effect when using direct_download.

Default value: $jenkins::params::package_provider

manage_service

Data type: Boolean

Enable management of Service[jenkins] resource

When setting to false please ensure something else defines Service[jenkins] in order for some module functionality (e.g. jenkins::cli) to work properly

Default value: true

service_enable

Data type: Boolean

Enable (or not) the jenkins service

Default value: true

service_ensure

Data type: Enum['running', 'stopped']

Status of the jenkins service

• running (default)
• stopped

Default value: 'running'

service_override

Data type: Hash[String[1], String]

Override the jenkins service configuration

Default value: {}

service_provider

Data type: Optional[String]

Override Service[jenkins] resource provider

Setting this to undef on platforms with systemd will force the usage of package provider sysv init scripts.

Default value: undef

config_hash

Data type: Hash

options to set in sysconfig/jenkins defaults/jenkins

(see jenkins::sysconf)

Default value: {}

plugin_hash

Data type: Hash

plugins to install

(see jenkins::plugin)

Default value: {}

job_hash

Data type: Hash

jobs to install

(see jenkins::job)

Default value: {}

user_hash

Data type: Hash

jenkins users to create

Default value: {}

configure_firewall

Data type: Boolean

For folks that want to manage the puppetlabs firewall module.

• If it's not present in the catalog, nothing happens.
• If it is, you need to explicitly set this true / false.
  • We didn't want you to have a service opened automatically, or unreachable inexplicably.
• This default changed in v1.0 to be undef.

Default value: false

install_java

Data type: Boolean

use the puppetlabs-java module to install a JDK

Jenkins requires a JRE. Setting this to false means that you are response for managing a JDK outside of this module.

Default value: true

repo_proxy

Data type: Optional[String]

proxy to download packages

This parameter is only relevant for yum repos managed by this module.

Default value: undef

proxy_host

Data type: Optional[String]

proxy hostname for plugin installation via this module and the UpdateCenter

Default value: undef

proxy_port

Data type: Optional[Integer]

proxy port for plugin installation via this module and the UpdateCenter

Default value: undef

no_proxy_list

Data type: Optional[Array]

List of hostname patterns to skip using the proxy.

• Only effective if "proxy_host" and "proxy_port" are set.
• Only applies to plugins installed via the UpdateCenter

Default value: undef

cli

Data type: Boolean

install jenkins-cli.jar CLI utility

• force installation of the jenkins CLI jar to $libdir/jenkins-cli.jar
• the cli is automatically installed when needed by components that use it, such as the user and credentials types, and the security class

Default value: true

cli_ssh_keyfile

Data type: Optional[Stdlib::Absolutepath]

Provides the location of an ssh private key file to make authenticated connections to the Jenkins CLI.

Default value: undef

cli_username

Data type: Optional[String]

Provides the username for authenticating to Jenkins via username and password.

Default value: undef

cli_password

Data type: Optional[String]

Provides the password for authenticating to Jenkins via username and password. Needed if cli_username is specified.

Default value: undef

cli_password_file

Data type: Optional[String]

Provides the password file for authenticating to Jenkins via username and password. Needed if cli_username is specified and cli_password is undefined.

Default value: undef

cli_tries

Data type: Integer

Retries until giving up talking to jenkins API

Default value: 10

cli_try_sleep

Data type: Integer

Seconds between tries to contact jenkins API

Default value: 10

port

Data type: Integer

Jenkins listening HTTP port

Note that this value is used for CLI communication and firewall configuration. It does not configure the port on which the jenkins service listens. (see config_hash)

Default value: 8080

libdir

Data type: Stdlib::Absolutepath

Path to jenkins core files

Default value: '/usr/share/java'

manage_datadirs

Data type: Boolean

manage the local state dir, plugins dir and jobs dir

Default value: true

localstatedir

Data type: Stdlib::Absolutepath

base path, in the autoconf sense, for jenkins local data including jobs and plugins

Default value: '/var/lib/jenkins'

executors

Data type: Optional[Integer]

number of executors on the Jenkins master

Default value: undef

slaveagentport

Data type: Optional[Integer]

jenkins slave agent

Default value: undef

manage_user

Data type: Boolean

manage the system jenkins user

Default value: true

user

Data type: String

system user that owns the jenkins master's files

Default value: 'jenkins'

manage_group

Data type: Boolean

manage the system jenkins group

Default value: true

group

Data type: String

system group that owns the jenkins master's files

Default value: 'jenkins'

default_plugins

Data type: Array

List of default plugins installed by this module

The the credentials plugin is required for this module to properly function. No version is specified. Set to [] if you want to explicitly manage all plugins version

Default value: $jenkins::params::default_plugins

default_plugins_host

Data type: String

Provide a way to override plugins host for all plugins

Default value: 'https://updates.jenkins.io'

purge_plugins

Data type: Boolean

Purge all plugins not explicitly managed by this module

This will result in plugins manually installed via the UpdateCenter being removed. Only enable this option if you want to manage all plugins (and plugin dependencies) explicitly.

Default value: false

jenkins::cli::config

This class provides configuration values to override defaults and fact data for PuppetX::Jenkins::Provider::Clihelper based providers.

Default and fact data is managed internal to the PuppetX::Jenkins::Provider::Clihelper class for compatiblity with the puppet resource face. No defaults should be set in this classes definition.

Parameters

The following parameters are available in the jenkins::cli::config class:

• cli_jar
• url
• ssh_private_key
• puppet_helper
• cli_tries
• cli_try_sleep
• cli_username
• cli_password
• cli_password_file
• cli_password_file_exists
• ssh_private_key_content

cli_jar

Data type: Optional[Stdlib::Absolutepath]

Default value: undef

url

Data type: Optional[String]

Default value: undef

ssh_private_key

Data type: Optional[Stdlib::Absolutepath]

Default value: undef

puppet_helper

Data type: Optional[Stdlib::Absolutepath]

Default value: undef

cli_tries

Data type: Optional[Integer]

Default value: undef

cli_try_sleep

Data type: Optional[Numeric]

Default value: undef

cli_username

Data type: Optional[String]

Default value: undef

cli_password

Data type: Optional[String]

Default value: undef

cli_password_file

Data type: String

Default value: '/tmp/jenkins_credentials_for_puppet'

cli_password_file_exists

Data type: Boolean

Default value: false

ssh_private_key_content

Data type: Optional[String]

Default value: undef

jenkins::cli_helper

A helper script for creating resources via the Jenkins cli

jenkins::master

Install a master

Parameters

The following parameters are available in the jenkins::master class:

• version

version

Data type: String

Version of the swarm plugin

Default value: $jenkins::params::swarm_version

jenkins::security

Copyright 2014 RetailMeNot, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Parameters

The following parameters are available in the jenkins::security class:

• security_model

security_model

Data type: String

jenkins::slave

=== Examples

class { 'jenkins::slave': masterurl => 'http://jenkins-master1.example.com:8080', ui_user => 'adminuser', ui_pass => 'adminpass' }

=== Authors

Matthew Barr [email protected]

=== Copyright

Copyright 2013 Matthew Barr , but can be used for anything by anyone..

Parameters

The following parameters are available in the jenkins::slave class:

• slave_name
• description
• masterurl
• autodiscoveryaddress
• ui_user
• ui_pass
• tool_locations
• source
• proxy_server
• tunnel
• version
• executors
• manage_slave_user
• slave_user
• slave_groups
• slave_uid
• slave_home
• slave_mode
• disable_ssl_verification
• disable_clients_unique_id
• labels
• install_java
• manage_client_jar
• ensure
• enable
• java_args
• swarm_client_args
• delete_existing_clients
• java_cmd

slave_name

Data type: Optional[String]

Default value: undef

description

Data type: Optional[String]

Default value: undef

masterurl

Data type: Optional[String]

Default value: undef

autodiscoveryaddress

Data type: Optional[String]

Default value: undef

ui_user

Data type: Optional[String]

Default value: undef

ui_pass

Data type: Optional[String]

Default value: undef

tool_locations

Data type: Optional[String]

Default value: undef

source

Data type: Optional[String]

Default value: undef

proxy_server

Data type: Optional[String]

Default value: undef

tunnel

Data type: Optional[Jenkins::Tunnel]

Default value: undef

version

Data type: String

Default value: $jenkins::params::swarm_version

executors

Data type: Integer

Default value: 2

manage_slave_user

Data type: Boolean

Default value: true

slave_user

Data type: String

Default value: 'jenkins-slave'

slave_groups

Data type: Optional[String]

Default value: undef

slave_uid

Data type: Optional[Integer]

Default value: undef

slave_home

Data type: Stdlib::Absolutepath

Default value: '/home/jenkins-slave'

slave_mode

Data type: Enum['normal', 'exclusive']

Default value: 'normal'

disable_ssl_verification

Data type: Boolean

Default value: false

disable_clients_unique_id

Data type: Boolean

Default value: false

labels

Data type: Array[String[1]]

Default value: []

install_java

Data type: Any

Default value: true

manage_client_jar

Data type: Boolean

Default value: true

ensure

Data type: Enum['running', 'stopped']

Default value: 'running'

enable

Data type: Boolean

Default value: true

java_args

Data type: Array[String[1]]

Default value: []

swarm_client_args

Data type: Array[String[1]]

Default value: []

delete_existing_clients

Data type: Boolean

Default value: false

java_cmd

Data type: Any

Default value: '/usr/bin/java'

Defined types

jenkins::augeas

Change config files using augeas

Examples

Configure the git plugin

jenkins::augeas { 'git':
  plugin          => true,
  config_filename => 'hudson.plugins.git.GitSCM.xml',
  context         => '/hudson.plugins.git.GitSCM_-DescriptorImpl',
  changes         => [
    'set globalConfigName/#text "Bob the Builder"',
    'set globalConfigEmail/#text "[email protected]",
  ],
}

Parameters

The following parameters are available in the jenkins::augeas defined type:

• config_filename
• changes
• onlyif
• plugin
• plugin_version
• context
• restart
• show_diff

config_filename

Data type: String

Filename of the configuration file to work on relative to the jenkins localstatedir.

changes

Data type: Variant[Array[String], String]

String or array with augeas changes to perform.

onlyif

Data type: Optional[Variant[Array[String], String]]

Optional augeas command and comparisons to control the execution of this type.

Default value: undef

plugin

Data type: Variant[Boolean,String]

Optionally jenkins::augeas can also install the plugin. If this is set to true, we use the name of the resource as plugin name. If it's a string, that is used as plugin name.

Default value: false

plugin_version

Data type: Optional[String]

Optional plugin version to pass through to jenkins::plugin

Default value: undef

context

Data type: String

Optional context to ease your change rules.

Default value: '/'

restart

Data type: Boolean

If set to true, will trigger a jenkins (safe-)restart in stead of reloading the configuration.

Default value: false

show_diff

Data type: Boolean

Whether to display differences when the file changes, defaulting to true.

Default value: true

jenkins::cli::exec

Executing custom helper script commands via the Jenkins CLI.

Parameters

The following parameters are available in the jenkins::cli::exec defined type:

• unless
• command

unless

Data type: Optional[String]

The unless parameter passed to the exec resource

Default value: undef

command

Data type: Variant[String, Array]

The command or commands to run

Default value: $title

jenkins::credentials

Copyright 2014 RetailMeNot, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Parameters

The following parameters are available in the jenkins::credentials defined type:

• password
• description
• private_key_or_path
• ensure
• uuid

password

Data type: String

description

Data type: String

Default value: 'Managed by Puppet'

private_key_or_path

Data type: String

Default value: ''

ensure

Data type: Enum['present', 'absent']

Default value: 'present'

uuid

Data type: String

Default value: ''

jenkins::job

Manage Jenkins jobs given a name and config xml

Parameters

The following parameters are available in the jenkins::job defined type:

• config
• source
• template
• jobname
• ensure
• difftool
• replace

config

Data type: String

The content of the jenkins job config file (required)

source

Data type: Optional[String]

Path to a puppet file() resource containing the Jenkins XML job description. Will override 'config' if set

Default value: undef

template

Data type: Optional[String[1]]

Path to a puppet template() resource containing the Jenkins XML job description. Will override 'config' if set

Default value: undef

jobname

Data type: String

the name of the jenkins job

Default value: $title

ensure

Data type: Enum['present', 'absent']

choose 'absent' to ensure the job is removed

Default value: 'present'

difftool

Data type: String

Provide a command to execute to compare Jenkins job files

Default value: '/usr/bin/diff -b -q'

replace

Data type: Boolean

Whether or not to replace the job if it already exists.

Default value: true

jenkins::plugin

This can be used to manage the state of individual plugins. Note that it does no dependency management and that's all up to the user. This is particularly important to remember when also purging plugins.

Parameters

The following parameters are available in the jenkins::plugin defined type:

• version
• config_filename
• config_content
• update_url
• source
• extension
• digest_string
• digest_type
• enabled
• pin
• download_options

version

Data type: Optional[String]

The version to ensure

Default value: undef

config_filename

Data type: Optional[String]

Name of the config file for this plugin. Note config_content must also be set.

Default value: undef

config_content

Data type: Optional[String]

Content of the config file for this plugin. It is up to the caller to create this content from a template or any other mean. config_filename must also be set.

Default value: undef

update_url

Data type: Optional[String]

Default value: undef

source

Data type: Optional[String]

Direct URL from which to download plugin without modification. This is particularly useful for development and testing of plugins which may not be hosted in the typical Jenkins' plugin directory structure. E.g.,

https://example.org/myplugin.hpi

Default value: undef

extension

Data type: Enum['hpi', 'jpi']

When no source is given, this extension is used

Default value: 'hpi'

digest_string

Data type: Optional[String]

An optional digest string to verify integrity. The digest_type parameter describes content of this string. It's passed to puppet-archive to verify the downloaded plugin.

Default value: undef

digest_type

Data type: String

This parameter describes the content of digest_string. It's passed to puppet-archive to verify the downloaded plugin.

Default value: 'sha1'

enabled

Data type: Boolean

Ensure whether the plugin is enabled or not. Disabled plugins are still installed.

Default value: true

pin

Data type: Boolean

Pin the plugin to a specific version. This prevents the updater from updating it.

Default value: false

download_options

Data type: Array[String[1]]

Add options to Archive's curl

Default value: ['--http1.1']

jenkins::user

Copyright 2014 RetailMeNot, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Parameters

The following parameters are available in the jenkins::user defined type:

• email
• password
• full_name
• public_key
• ensure

email

Data type: Pattern[/^[^@]+@[^@]+$/]

password

Data type: String

full_name

Data type: String

Default value: 'Managed by Puppet'

public_key

Data type: String

Default value: ''

ensure

Data type: Enum['present', 'absent']

Default value: 'present'

Functions

jenkins_port

Type: Ruby 3.x API

Return the configurad Jenkins port value (corresponds to /etc/defaults/jenkins -> JENKINS_PORT

Example:

$port = jenkins_port()

jenkins_port()

Return the configurad Jenkins port value (corresponds to /etc/defaults/jenkins -> JENKINS_PORT

Example:

$port = jenkins_port()

Returns: Any

jenkins_prefix

Type: Ruby 3.x API

Return the configured Jenkins prefix value (corresponds to /etc/defaults/jenkins -> PREFIX)

Example:

$prefix = jenkins_prefix()

jenkins_prefix()

Return the configured Jenkins prefix value (corresponds to /etc/defaults/jenkins -> PREFIX)

Example:

$prefix = jenkins_prefix()

Returns: Any

Data types

Jenkins::Tunnel

A custom data type for a jenkins tunnel verification

Alias of Variant[Pattern[/.+:$/], Pattern[/.+:[0-9]+/], Pattern[/^:[0-9]+/]]