Installs and configures Jenkins CI controller & agents. Resource providers to support automation via jenkins-cli, including job create/update.
This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit sous-chefs.org or come chat with us on the Chef Community Slack in #sous-chefs.
- Amazon Linux 2023
- Debian 12+
- Ubuntu 20.04+
- RHEL/CentOS Stream 9+
- AlmaLinux 8+
- Rocky Linux 8+
- Chef Infra Client 13.0+
This cookbook does not install, manage, or manipulate a JDK, as that is outside of the scope of Jenkins. The package installation method will automatically pull in a valid Java if one does not exist on Debian. RHEL jenkins packages do not depend on java as there are far too many options for a package to do the right thing. We recommend including the java cookbook on your system which allows for either openJDK or Oracle JDK installations.
In order to keep the README manageable and in sync with the attributes, this cookbook documents attributes inline. The usage instructions and default values for attributes can be found in the individual attribute files.
Documentation and examples are provided inline using YARD. The tests and fixture cookbooks in test and test/fixtures are intended to be a further source of examples.
The controller recipe will create the required directory structure and install Jenkins. There are two installation methods, controlled by the node['jenkins']['controller']['install_method'] attribute:
package- Install Jenkins from the official jenkins-ci.org packageswar- Download the latest version of the WAR file and configure a systemd service
- jenkins_credentials
- jenkins_file_credentials
- jenkins_githubapp_credentials
- jenkins_password_credentials
- jenkins_private_key_credentials
- jenkins_secret_text_credentials
If you use or plan to use authentication for your Jenkins cluster (which we highly recommend), you will need to configure CLI authentication. Jenkins 2.332.1+ requires authentication for CLI commands by default.
For modern Jenkins installations, the recommended approach is to use username/password authentication via the -auth flag. This can be configured using node attributes:
node.normal['jenkins']['executor']['cli_username'] = 'admin'
node.normal['jenkins']['executor']['cli_password'] = 'admin_api_token_or_password'Or via run_state (useful when credentials come from encrypted data bags):
node.run_state[:jenkins_username] = 'admin'
node.run_state[:jenkins_password] = 'admin_api_token_or_password'You can also use a credentials file:
node.normal['jenkins']['executor']['cli_credential_file'] = '/path/to/credentials_file'Or via run_state:
node.run_state[:jenkins_cli_credential_file] = '/path/to/credentials_file'The credentials file should contain username:password or username:api_token.
Note: Using an API token instead of a password is recommended for security. You can generate an API token from the Jenkins user configuration page.
For older Jenkins installations or when SSH-based authentication is preferred, you can set a private key in the run_state:
node.run_state[:jenkins_private_key]The underlying executor class (which all custom resources use) intelligently adds authentication information to the Jenkins CLI commands if this value is set. The method used to generate and populate this key-pair is left to the user:
# Using search
master = search(:node, 'fqdn:master.ci.example.com').first
node.run_state[:jenkins_private_key] = master['jenkins']['private_key']
# Using encrypted data bags and chef-sugar
private_key = encrypted_data_bag_item('jenkins', 'keys')['private_key']
node.run_state[:jenkins_private_key] = private_keyThe associated public key must be set on a Jenkins user. You can use the jenkins_user resource to create this pairing. Here's an example that loads a keypair and assigns it appropriately:
jenkins_keys = encrypted_data_bag_item('jenkins', 'keys')
require 'openssl'
require 'net/ssh'
key = OpenSSL::PKey::RSA.new(jenkins_keys['private_key'])
private_key = key.to_pem
public_key = "#{key.ssh_type} #{[key.to_blob].pack('m0')}"
# Create the Jenkins user with the public key
jenkins_user 'chef' do
public_keys [public_key]
end
# Set the private key on the Jenkins executor
node.run_state[:jenkins_private_key] = private_keyPlease note that older versions of Jenkins (< 1.555) permitted login via CLI for a user defined in Jenkins configuration with an SSH public key but not present in the actual SecurityRealm, and this is no longer permitted. If an operation requires any special permission at all, you must authenticate as a real user. This means that if you have LDAP or GitHub OAuth based authn/authz enabled the user you are using for configuration tasks must have an associated account in the external services. Please see JENKINS-22346 for more details.
Jenkins 2 enables an install wizard by default. To make sure you can manipulate the jenkins instance, you need to disable the wizard. You can do this by setting an attribute:
default['jenkins']['controller']['jvm_options'] = '-Djenkins.install.runSetupWizard=false'This is done by default, but must be kept when overriding the jvm_options!
If you need to pass through a proxy to communicate between your controllers and agents, you will need to set a special node attribute:
node['jenkins']['executor']['proxy']The underlying executor class (which all HWRPs use) intelligently passes proxy information to the Jenkins CLI commands if this attribute is set. It should be set in the form HOST:PORT:
node.normal['jenkins']['executor']['proxy'] = '1.2.3.4:5678'Please see the Contributing and Testing Guidelines.
This project exists thanks to all the people who contribute.
Thank you to all our backers!
Support this project by becoming a sponsor. Your logo will show up here with a link to your website.
