Name: puppet-jenkins
Owner: Vox Pupuli
Description: Puppet module for Jenkins
Created: 2013-04-28 20:34:40.0
Updated: 2018-02-18 02:07:53.0
Pushed: 2018-02-19 22:09:12.0
Homepage: http://forge.puppetlabs.com/puppet/jenkins
Size: 1912
Language: Ruby
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
This is intended to be a re-usable Puppet module that you can include in your own tree.
The experimental types/providers are not for the faint of heart. If you are starting out with this module you probably want to skip directly to Getting Started.
A family of experimental native types and providers has been added to this module, in parallel to the existing classes and defined types, with the goal of soliciting feedback. One of the primary benefits of these new types is not requiring manifest changes to manage jenkins with or without “security” enabled. The goal is to eventually replace the functionality of the existing classes/defines with the new types. Usage feedback (positive and negative), bug reports and/or PRs would be greatly welcomed.
The semantics and API of these types should be considered unstable and almost certainly will change based on feedback. It is currently unclear if these types will be considered part of the public API or treated as private to the module.
See NATIVE_TYPES_AND_PROVIDERS.md
Jenkins refactored the CLI in 2.54 and 2.46.2 in response to several security incidents (See JENKINS-41745. This module has been adjusted to support the new CLI. However you need to tell the module if the new remoting free cli is in place. Please set
: This is not the default to support backward compatibility. This may become
fault once this module is released in a new version.
note that the module tries to do heuristics for this setting if not specified.
can always set this parameter to enforce usage of old or new CLI interface.
istics:
LTS:
* If manage_repo and repo == lts and version = latest -> true
* If manage_repo and repo == lts and version >= 2.46.2 -> true
* else false
Non-LTS:
* If manage_repo and repo != lts and version = latest -> true
* If manage_repo and repo != lts and version >= 2.54 -> true
* else false
sername and Password Auth
new CLI also supports proper authentication with username and password. This
not been supported in this module for a long time, but is a requirement for
orting AD and OpenID authentications (there is no ssh key there). You can now
supply ```$::jenkins::cli_username``` and ```$::jenkins::cli_password``` to
username / password based authentication. Then the puppet automation user can
reside in A.D
: latest jenkins (2.54++ and 2.46.2++) require a ssh username, so you must also
ide ```$::jenkins::cli_username``` for ssh. If you specify both username/password
ssh key file, SSH authentication is preferred.
ing puppet-jenkins
etting Started
puppet module install rtyler/jenkins
node 'hostname.example.com' {
include jenkins
}
the service should be running at [http://hostname.example.com:8080/](http://hostname.example.com:8080/).
Jenkins' options
Master Executor Threads
class { 'jenkins': executors => 0, }
Managing Jenkins jobs
d jobs can be managed using the `jenkins::job` define
Creating or updating a build job
jenkins::job { 'test-build-job':
config => template("${templates}/test-build-job.xml.erb"),
}
Disabling a build job
jenkins::job { 'test-build-job':
enabled => 0,
config => template("${templates}/test-build-job.xml.erb"),
}
Removing an existing build job
jenkins::job { 'test-build-job':
ensure => 'absent',
}
Installing Jenkins plugins
Jenkins puppet module defines the `jenkins::plugin` resource which
download and install the plugin "[by
](https://wiki.jenkins-ci.org/display/JENKINS/Plugins#Plugins-Byhand)"
names of the plugins can be found on the [update
](https://updates.jenkins-ci.org/download/plugins)
Latest
efault, the resource will install the latest plugin, i.e.:
jenkins::plugin { 'git': }
ou specify `version => 'latest'` in current releases of the module, the
in will be downloaded and installed with *every* run of Puppet. This is a
n issue and will be addressed in future releases.
By version
ou need to peg a specific version, simply specify that as a string, i.e.:
jenkins::plugin { 'git':
version => '1.1.11',
}
that plugin will timeout if it takes longer than 120 seconds to download.
can increase this by specifying a timeout value, i.e: `timeout => 240`.
Verifying
module will download the jenkins modules over HTTP, without SSL.
rder to add some verification regarding the downloaded file, you
specify a checksum. You can also define a checksum type with
est_type' (default to sha1 if unspecified) ie.:
jenkins::plugin { 'git':
version => '2.2.12',
digest_string => '48141822e0eea1faa1a1a99b35372494e7352c2746ca3aa3a19a07f34b021848d2cd0bffc8959c1b809c5be231c1b49e9ffec0430dd68938197ac0f34588ee25',
digest_type => 'sha512',
}
Direct URL
ct URL from which to download plugin without modification. This is
icularly useful for development and testing of plugins which may not be
ed in the typical Jenkins' plugin directory structure.
jenkins::plugin { 'myplugin':
source => 'https://example.org/myplugin.hpi',
}
that that when `source` is specified, the `version` and `plugin_url`
meters will have no effect on the plugin retrieval URL.
Plugin dependencies
ndencies are not automatically installed. You need to manually determine the plugin dependencies and include those as well. The Jenkins wiki is a good place to do this. For example: The Git plugin page is at https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin.
Slaves
can automatically add slaves to jenkins, and have them auto register themselves. Most options are actually optional, as nodes will auto-discover the master, and connect.
documentation for the slave code is in jenkins::slave.
equires the swarm plugin on the master & the class jenkins::slave on the slaves, as below:
node /jenkins-slave.*/ {
class { 'jenkins::slave':
masterurl => 'http://jenkins-master1.domain.com:8080',
ui_user => 'adminuser',
ui_pass => 'adminpass',
}
}
node /jenkins-master.*/ {
include jenkins
include jenkins::master
}
Depending on Jenkins
ou have any resource in Puppet that *depends* on Jenkins being present, add
following `require` statement:
exec { 'some-exec':
require => Class['jenkins::package'],
# ... etc
}
Advanced features
lugin Hash - jenkins::plugins
onfig Hash - jenkins::config
onfigure Firewall - jenkins (init.pp)
utbound Jenkins Proxy Config - jenkins (init.pp)
CLI Helper](#cli-helper)
* [`exec_cli_helper`](#exec_cli_helper)
enkins Users
redentials
imple security model configuration
API-based Resources and Settings (Users, Credentials, security)
module includes a groovy-based helper script that uses the
kins CLI](https://wiki.jenkins-ci.org/display/JENKINS/Jenkins+CLI) to
ract with the Jenkins API. Users, Credentials, and security model
iguration are all driven through this script.
an API-based resource is defined, the Jenkins' CLI is installed and run
nst the local system (127.0.0.1). Jenkins is assumed to be listening on
8080, but the module is smart enough to notice if you've configured an
rnate port using jenkins::config_hash['HTTP_PORT'].
s and credentials are Puppet-managed, meaning that changes made to them
outside Puppet will be reset at the next puppet run. In this way, you can
re that certain accounts are present and have the appropriate login
entials.
CLI Helper
CLI helper assumes unauthenticated access unless configured otherwise.
can configure `jenkins::cli_helper` to use an SSH key on the managed system
assing the keyfile path as a class parameter:
class {'jenkins':
cli_ssh_keyfile => '/path/to/id_rsa',
}
or via hiera:
jenkins::cli_ssh_keyfile: "/path/to/id_rsa"
rect including of the `jenkins::cli_helper` class into the manifest is deprecated.__
e's an open bug in Jenkins (JENKINS-22346) that causes authentication to
when a key is used but authentication is disabled. Until the bug is fixed,
may need to bootstrap jenkins out-of-band to ensure that resources and
rity policy are configured in the correct order. For example:
# In puppet:
anchor {'jenkins-bootstrap-start': } ->
Class['jenkins::cli_helper'] ->
Exec[$bootstrap_script] ->
anchor {'jenkins-bootstrap-complete': }
# Code for $bootstrap_script
#!/bin/bash -e
# Generate an SSH key for the admin user
ADMIN_USER='<%= admin_user_name %>'
ADMIN_EMAIL='<%= admin_user_email %>'
ADMIN_PASSWORD='<%= admin_user_password %>'
ADMIN_FULLNAME='<%= admin_user_full_name %>'
ADMIN_SSH_KEY='<%= admin_ssh_keyfile %>'
JENKINS_CLI='<%= jenkins_libdir %>/jenkins-cli.jar'
PUPPET_HELPER='<%= jenkins_libdir %>/puppet_helper.groovy'
HELPER="java -jar $JENKINS_CLI -s http://127.0.0.1:8080 groovy $PUPPET_HELPER"
DONEFILE='<%= jenkins_libdir %>/jenkins-bootstrap.done'
ADMIN_PUBKEY="$(cat ${ADMIN_SSH_KEY}.pub)"
# Create the admin user, passing no credentials
$HELPER create_or_update_user "$ADMIN_USER" "$ADMIN_EMAIL" "$ADMIN_PASSWORD" "$ADMIN_FULLNAME" "$ADMIN_PUBKEY"
# Enable security. After this, credentials will be required.
$HELPER set_security full_control
touch $DONEFILE
`jenkins::cli::exec`
defined type `jenkins::cli::exec` may be used to execute arbitrary CLI helper
ands.
ments to the CLI helper script may be specified as the resource's title.
jenkins::cli::exec { 'set_num_executors 0': }
assed as an array to the `command` parameter. This example is
ntically equivalent to the first.
jenkins::cli::exec { 'set_num_executors 0':
command => ['set_num_executors', '0'],
}
h is also equivalent to:
jenkins::cli::exec { 'set_num_executors 0':
command => 'set_num_executors 0',
}
he `unless` parameter is specified, an environment variable named
LPER_CMD` is declared which contains the complete string needed to execute
CLI helper script (minus arguments). This may be useful in constructing
potent `exec` statements.
$num_executors = 0 jenkins::cli::exec { “set_num_executors ${num_executors}“:
unless => "[ \$(\$HELPER_CMD get_num_executors) -eq ${num_executors} ]"
}
Users
l and password are required.
te a `johndoe` user account whose full name is "Managed by Puppet":
jenkins::user { 'johndoe':
email => 'jdoe@example.com',
password => 'changeme',
}
Credentials
word is required. For ssh credentials, `password` is the key passphrase (or
f there is none). `private_key_or_path` is the text of key itself or an
lute path to a key file on the managed system.
te ssh credentials named 'github-deploy-key', providing an unencrypted
ate key:
jenkins::credentials { 'github-deploy-key':
password => '',
private_key_or_path => hiera('::github_deploy_key'),
}
tting a UUID:_*
can also specify a UUID to use with the credentials, which will be used to
tify the credentials from within the job config. This is necessary when setting
entials for use with the [git plugin](http://docs.openstack.org/infra/jenkins-job-builder/scm.html#scm.git), for example.
can either manually generate a UUID from a site like https://www.uuidgenerator.net,
se the UUID from an existing user, which is accessible within the URL of the
ins console when managing an existing user's credentials.
jenkins::credentials { 'deploy-user':
password => '',
private_key_or_path => hiera('::deploy_key'),
uuid => hiera('::deploy_credentials_uuid'),
}
Configuring Security
Jenkins security model can be set to one of two modes:
ull_control` - Users have full control after login. Authentication uses
nkins' built-in user database.
nsecured` - Authentication is not required.
ins security is not managed by puppet unless jenkins::security is defined.
sing from Github / source
With librarian
ou use [librarian-puppet](https://github.com/rodjek/librarian-puppet), add
following to your `Puppetfile`:
mod “rtyler/jenkins”
With the "puppet module" tool
module is compatible with the puppet module tool. Appropriately this
le has been released to the [Puppet Forge](http://forge.puppetlabs.com/),
wing you to easily install the released version of the module
uickly try this module with the puppet module tool:
% sudo puppet module install rtyler/jenkins
% sudo puppet apply -v -e 'include jenkins'
info: Loading facts in facter_dot_d
info: Loading facts in facter_dot_d
info: Applying configuration version '1323459431'
notice: /Stage[main]/Jenkins::Repo::El/Yumrepo[jenkins]/descr: descr changed '' to 'Jenkins'
notice: /Stage[main]/Jenkins::Repo::El/Yumrepo[jenkins]/baseurl: baseurl changed '' to 'http://pkg.jenkins-ci.org/redhat/'
notice: /Stage[main]/Jenkins::Repo::El/Yumrepo[jenkins]/gpgcheck: gpgcheck changed '' to '1'
notice: /Stage[main]/Jenkins::Repo::El/File[/etc/yum/jenkins-ci.org.key]/ensure: defined content as '{md5}9fa06089848262c5a6383ec27fdd2575'
notice: /Stage[main]/Jenkins::Repo::El/Exec[rpm --import /etc/yum/jenkins-ci.org.key]/returns: executed successfully
notice: /Stage[main]/Jenkins::Package/Package[jenkins]/ensure: created
notice: /Stage[main]/Jenkins::Service/Service[jenkins]/ensure: ensure changed 'stopped' to 'running'
notice: Finished catalog run in 27.46 seconds
Overriding the jenkins package name
possible to specify a different package name to the default `jenkins` if you wish:
class { 'jenkins': package_name => 'jenkins_custom', }
Installing from a hosted RPM
times you don't have an RPM repository available and are not allowed to
ctly install from repositories on the Internet. In this case, you can
l install Jenkins with this module by hosting the jenkins RPM file
where accessible (http server, S3 bucket, etc.) and tell
class { 'jenkins': direct_download => 'http://myserver/rpms/jenkins-x.xxx-1-1.rpm', }