puppet-jenkins

This is intended to be a re-usable Puppet module that you can include in your own tree.

Jenkins 2

This module does not presently support Jenkins 2.x due to incompatible changes with 1.x. Support is planned for a future release.

Experimental Types and Providers

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

Using puppet-jenkins

Getting Started

puppet module install rtyler/jenkins

    node 'hostname.example.com' {
        include jenkins
    }

Then the service should be running at http://hostname.example.com:8080/.

Jenkins' options

Master Executor Threads

class { 'jenkins':
  executors => 0,
}

Managing Jenkins jobs

Build 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

The Jenkins puppet module defines the jenkins::plugin resource which will download and install the plugin "by hand"

The names of the plugins can be found on the update site

Latest

By default, the resource will install the latest plugin, i.e.:

  jenkins::plugin { 'git': }

If you specify version => 'latest' in current releases of the module, the plugin will be downloaded and installed with every run of Puppet. This is a known issue and will be addressed in future releases. For now it is recommended that you pin plugin versions when using the jenkins::plugin type.

By version

If you need to peg a specific version, simply specify that as a string, i.e.:

  jenkins::plugin { 'git':
    version => '1.1.11',
  }

Note that plugin will timeout if it takes longer than 120 seconds to download. You can increase this by specifying a timeout value, i.e: timeout => 240.

Verifying

This module will download the jenkins modules over HTTP, without SSL. In order to add some verification regarding the downloaded file, you can specify a checksum. You can also define a checksum type with 'digest_type' (default to sha1 if unspecified) ie.:

  jenkins::plugin { 'git':
    version       => '2.2.12',
    digest_string => '48141822e0eea1faa1a1a99b35372494e7352c2746ca3aa3a19a07f34b021848d2cd0bffc8959c1b809c5be231c1b49e9ffec0430dd68938197ac0f34588ee25',
    digest_type   => 'sha512',
  }

Direct URL

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.

  jenkins::plugin { 'myplugin':
    source => 'https://example.org/myplugin.hpi',
  }

Note that that when source is specified, the version and plugin_url parameters will have no effect on the plugin retrieval URL.

Plugin dependencies

Dependencies 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

You 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.

Full documentation for the slave code is in jenkins::slave.

It requires 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
    }

Dependencies

The dependencies for this module currently are:

• stdlib module
• apt module (for Debian/Ubuntu users)
• java module
• zypprepo (for SUSE users)
• archive module

Depending on Jenkins

If you have any resource in Puppet that depends on Jenkins being present, add the following require statement:

  exec { 'some-exec':
    require => Class['jenkins::package'],
    # ... etc
  }

Advanced features

1. Plugin Hash - jenkins::plugins
2. Config Hash - jennkins::config
3. Configure Firewall - jenkins (init.pp)
4. Outbound Jenkins Proxy Config - jenkins (init.pp)
5. CLI Helper
   • exec_cli_helper
6. Jenkins Users
7. Credentials
8. Simple security model configuration

API-based Resources and Settings (Users, Credentials, security)

This module includes a groovy-based helper script that uses the Jenkins CLI to interact with the Jenkins API. Users, Credentials, and security model configuration are all driven through this script.

When an API-based resource is defined, the Jenkins' CLI is installed and run against the local system (127.0.0.1). Jenkins is assumed to be listening on port 8080, but the module is smart enough to notice if you've configured an alternate port using jenkins::config_hash['HTTP_PORT'].

Users and credentials are Puppet-managed, meaning that changes made to them from outside Puppet will be reset at the next puppet run. In this way, you can ensure that certain accounts are present and have the appropriate login credentials.

CLI Helper

The CLI helper assumes unauthenticated access unless configured otherwise. You can configure jenkins::cli_helper to use an SSH key on the managed system by passing 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"

Direct including of the jenkins::cli_helper class into the manifest is deprecated.

There's an open bug in Jenkins (JENKINS-22346) that causes authentication to fail when a key is used but authentication is disabled. Until the bug is fixed, you may need to bootstrap jenkins out-of-band to ensure that resources and security 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

The defined type jenkins::cli::exec may be used to execute arbitrary CLI helper commands.

Arguments to the CLI helper script may be specified as the resource's title.

  jenkins::cli::exec { 'set_num_executors 0': }

Or passed as an array to the command parameter. This example is semantically equivalent to the first.

  jenkins::cli::exec { 'set_num_executors 0':
    command => ['set_num_executors', '0'],
  }

which is also equivalent to:

  jenkins::cli::exec { 'set_num_executors 0':
    command => 'set_num_executors 0',
  }

If the unless parameter is specified, an environment variable named $HELPER_CMD is declared which contains the complete string needed to execute the CLI helper script (minus arguments). This may be useful in constructing idempotent exec statements.

  $num_executors = 0
  jenkins::cli::exec { "set_num_executors ${num_executors}":
    unless => "[ \$(\$HELPER_CMD get_num_executors) -eq ${num_executors} ]"
  }

Users

Email and password are required.

Create a johndoe user account whose full name is "Managed by Puppet":

  jenkins::user { 'johndoe':
    email    => 'jdoe@example.com',
    password => 'changeme',
  }

Credentials

Password is required. For ssh credentials, password is the key passphrase (or '' if there is none). private_key_or_path is the text of key itself or an absolute path to a key file on the managed system.

Create ssh credentials named 'github-deploy-key', providing an unencrypted private key:

    jenkins::credentials { 'github-deploy-key':
      password            => '',
      private_key_or_path => hiera('::github_deploy_key'),
    }

Setting a UUID:

You can also specify a UUID to use with the credentials, which will be used to identify the credentials from within the job config. This is necessary when setting credentials for use with the git plugin, for example.

You can either manually generate a UUID from a site like https://www.uuidgenerator.net, or use the UUID from an existing user, which is accessible within the URL of the Jenkins 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

The Jenkins security model can be set to one of two modes:

• full_control - Users have full control after login. Authentication uses Jenkins' built-in user database.
• unsecured - Authentication is not required.

Jenkins security is not managed by puppet unless jenkins::security is defined.

Using from Github / source

With librarian

If you use librarian-puppet, add the following to your Puppetfile:

mod "rtyler/jenkins"

With the "puppet module" tool

This module is compatible with the puppet module tool. Appropriately this module has been released to the Puppet Forge, allowing you to easily install the released version of the module

To quickly 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

It's 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

Sometimes you don't have an RPM repository available and are not allowed to directly install from repositories on the Internet. In this case, you can still install Jenkins with this module by hosting the jenkins RPM file somewhere accessible (http server, S3 bucket, etc.) and tell

class { 'jenkins':
  direct_download => 'http://myserver/rpms/jenkins-x.xxx-1-1.rpm',
}

Changelog

This is a manually kept file, and may not entirely reflect reality

v1.6.0 - Kato

• #219 - Plugins are installed each time and restarting service
• #314 - Update jenkins-slave.RedHat init.d script work bash < 4.0
• #362 - Error on updating existing job
• #365 - jenkins user and jenkins_home directory not configurable
• #367 - [puppet-jenkins#366] Replace -toolLocations with --toolLocation
• #371 - slave: INFO: Failure authenticating with BASIC 'Jenkins' 401
• #372 - Slave: swarm-client requires a cashe directory /home/jenkins-slave/.jenkins/
• #374 - add single quotes for credentials
• #376 - Add template in the jenkins::job
• #377 - Making the management of the daemon package optional
• #378 - fix rspec-puppet raise_error warning
• #382 - (RFC) native types and providers
• #383 - fix acceptance test path prefix for jenkins-cli.jar
• #385 - WIP: completely rework the way imports work for the native types
• #386 - set_security() does not save jenkins state
• #387 - Avoid referring to class objects directly in the Groovy helper
• #388 - Fix relationship for pinned files
• #389 - remove seperate resources for handling plugin extension
• #390 - Adds Examples for various platforms for Jenkins
• #391 - use ensure_packages() to manage the daemon package
• #395 - Fix username quoting
• #396 - add user/group mgt. + localstatedir params to jenkins class
• #398 - client_url is hardcoded in slave.pp
• #399 - document types and providers puppetserver known issues

v1.5.0 - Jennings

• #227 - Add parameter to set user uuid in jenkins::credentials define
• #288 - add source parameter to jenkins::plugin define
• #289 - set user on exec resources in jenkins::plugin define
• #290 - Support getting external .xml job descriptions
• #292 - Feature/puppet helper util
• #295 - Use jenkins::cli::exec in security.pp
• #296 - should be jenkins::cli::exec
• #297 - Add jenkins::users class to declare all users
• #298 - Maint/fix resource relationships
• #301 - Apt upgrade
• #302 - Package name no longer hardcoded
• #303 - Puppet helper slaveagentport
• #319 - Adding optional description to slave
• #320 - Forge Project URL link broken
• #323 - Upgraded apt module dependency to support v2
• #325 - add puppet ~> 3.8 & ~> 4.1 to travis matrix
• #326 - Fixed project_page in metadata.json
• #328 - Support configuring a yum proxy server
• #331 - Set retries in job configuration to global parameters
• #335 - Fix jenkins::plugin with create_user false
• #336 - Features/9618 stronger plugin verification
• #347 - Fix require paths
• #351 - add darwin/osx support to slave class
• #352 - Adding cli_ssh_keyfile parameter to specify the location of a private key
• #353 - Class cannot find exec in jenkins::cli::reload.
• #357 - CLI classes unaware of Jenkins' --prefix
• #358 - Added jenkins_prefix function to retrieve configured prefix

v1.4.0 - Smithers

• #222 - Add retry to credentials execs
• #229 - Jenkins slave defaults bugfix
• #233 - fixes timeouts on restart
• #235 - Make creation of user optional
• #236 - Cleanup metadata.json for better mechanical score
• #237 - Update the README with a few puppet-lint things and puppet highlighting.
• #238 - Fix Bracket issue
• #239 - Refactor acceptance tests to use beaker-rspec
• #244 - Add instructions for acceptance tests
• #245 - Added support for the 'toolLocations' parameter.
• #256 - Direct package
• #260 - Feature/puppet helper num executors
• #261 - Escape job names for shell commands
• #262 - Change apt key to full fingerprint
• #264 - Broken link on puppetlabs.com page
• #266 - pin puppetlabs-apt fixtures version to 1.8.0
• #268 - Improvements on job import via cli
• #270 - remove rspec gem ~> 2.99.0 constraint
• #271 - fix rspec > 3 compatiblity
• #272 - use mainline puppetlabs_spec_helper gem
• #273 - update spec_helper_acceptance boiler plate
• #274 - remove puppet module versions constraints from beaker setup
• #275 - add .bundle to .gitignore
• #276 - add log/ to .gitignore
• #277 - add puppet 3.7.0 to travis matrix
• #278 - remove unnecessary whitespace from $::jenkins::cli_helper::helper_cmd
• #279 - add metadata-json-lint to Gemfile & enable rake validate target
• #280 - change puppetlabs/stdlib version dep to >= 4.6.0
• #282 - Feature/puppet 4
• #285 - convert raw execs of puppet_helper.groovy to jenkins::cli::exec define

v1.3.0 - Barnard

• #134 - Added in ability for user to redefine update center plugin URL
• #139 - document additional class params
• #169 - Allow build jobs to be configured and managed by puppet. Includes #163 a...
• #174 - setting configure_firewall true returns error, port is undefined
• #177 - switch to metadata.json
• #188 - Fix installation of core plugins
• #189 - Fix test.
• #191 - set default port for firewall
• #195 - Bump up swarm version to 1.17
• #198 - Relationship error when testing Jenkins::jobs
• #199 - missing include causes issuse #198
• #202 - Proxy work
• #203 - Fix typo in job/present.pp
• #204 - Fix for #174 allows setting $jenkins::port
• #206 - Refactor some of the firewall port configuration
• #207 - Introduce the jenkins_port function

v1.2.0 - Nestor

• #117 - Add feature to disable SSL verification on Swarm clients
• #131 - Support updates for core jenkins modules
• #135 - cli option broken w/ jenkins 1.563 on ubuntu precise
• #137 - repos should be enabled if repo=true on RedHat
• #140 - Packaging Cruft in 1.1.0
• #144 - Update init.pp - correct plugins example syntax
• #149 - Do not ensure plugin_parent_dir to be a directory (#148)
• #150 - Add ensure parameter to jenkins::slave
• #151 - Unsupported OSFamily RedHat on node
• #152 - Jenkins-slave on Centos: killproc and checkpid commands not found
• #153 - Fixes to Jenkins slave init and class
• #154 - slave_mode doesn't apply on debian distros.
• #155 - Add defined check for plugin_parent_dir resource
• #157 - Add missing slave mode to Debian defaults file
• #160 - User and credentials creation, simple security management
• #166 - Error loading fact /var/lib/puppet/lib/facter/jenkins.rb no such file to load -- json
• #171 - A bit of RedHat and Debian slave initd script merging
• #176 - no such file to load -- json
• #180 - Replace use of unzip with jar for unpacking jenkins CLI
• #182 - Include the apt module when installing an apt repository
• #183 - Rely on the jar command instead of unzip to unpack the cli.jar
• #185 - Allow setting the slave name, default to the fqdn at runtime
• #186 - Puppet Forge module
• #187 - Jenkins slave on RedHat - jenkins-slave.erb

v1.1.0 - Duckworth

Features

• #86, #122 - Add support for disabling SSL verification on slaves
• #116 - Add support for setting the -fsroot option for slaves
• init script for Debian-family slaves added
• Initial code for a jpm based Package provider merged

Bug fixes

• #107 - Private/internal classes made truly private
• #109 - Fix for dependency issue between repo and package installation.
• $jenkins_plugins fact refactored and RSpec tests added
• #121 - daemon package installed to make Debian slave installs functional
• #126 - Facter exception bug fixed