Ansible Role for Jenkins

This Ansible role installs and sets up Jenkins completely.

Use this role if you want to keep your Jenkins setup version-controlled. This way, you can deploy Jenkins consistently and treat it like infrastructure instead of a pet.

If you just need to install Jenkins and prefer to use the web interface for configuration without needing to repeat the deployment, then this role isn’t for you. You can check out geerlingguy/ansible-role-jenkins.

Requirements

For Docker deployment, you need Docker installed on your server. Currently, Docker, apt-get, and yum are the only supported methods, but more can be added.

Installation

To install, use Ansible Galaxy:

$ ansible-galaxy install emmetog.jenkins

Role Variables

Here are the important variables for installing Jenkins:

• jenkins_install_via: Specifies the installation method (must be one of the following):
  • docker: Install in a Docker container
  • apt: Install on Ubuntu/Debian
  • yum: Install on RedHat/CentOS
• jenkins_version: The exact Jenkins version to install

And here are the variables for configuration:

• jenkins_url: The URL to access Jenkins
• jenkins_port: The port Jenkins listens on
• jenkins_home: Directory for Jenkins configuration files
• jenkins_admin: Admin email for Jenkins
• jenkins_java_opts: Options for the Java process
• jenkins_config_owner: Owner of configuration files
• jenkins_config_group: Group for configuration files
• jenkins_auth: How Ansible should authenticate with Jenkins
• jenkins_url_health_check: URL for checking Jenkins' health after startup
• jenkins_health_check_user: Username for health check authentication
• jenkins_health_check_password: Password for health check authentication

To customize jobs and plugins:

• jenkins_jobs: List of job names to include in Jenkins
• jenkins_plugins: List of plugin IDs to install
• jenkins_custom_plugins: List of custom plugins to install

For more variables, check defaults/main.yml.

Example Playbook

- hosts: jenkins

  vars:
    jenkins_version: "2.73.1"
    jenkins_hostname: "jenkins.example.com"
    jenkins_port: 8080
    jenkins_install_via: "docker"
    jenkins_jobs:
      - "my-first-job"
      - "another-awesome-job"
    jenkins_include_secrets: true
    jenkins_include_custom_files: true
    jenkins_custom_files:
      - src: "jenkins.plugins.openstack.compute.UserDataConfig.xml"
        dest: "jenkins.plugins.openstack.compute.UserDataConfig.xml"
    jenkins_plugins:
      - git
      - blueocean
    jenkins_custom_plugins:
      - "openstack-cloud-plugin/openstack-cloud.jpi"

  roles:
    - emmetog.jenkins

Managing Configuration Files

For job configuration, the role looks for files in: {{ playbook_dir }}/jenkins-configs/jobs/my-first-job/config.xml and {{ playbook_dir }}/jenkins-configs/jobs/another-awesome-job/config.xml.

You can customize the directories using jenkins_source_dir_configs and jenkins_source_dir_jobs.

The role will also seek a config.xml file in {{ playbook_dir }}/jenkins-configs/config.xml to serve as the job configuration template.

If you update a configuration file or add new jobs/plugins, the workflow is:

1. Change the configuration in the Jenkins UI.
2. Save the resulting XML files to your version control system (VCS).
3. Add new files to their respective lists:
   • For new jobs: jenkins_jobs
   • For custom files: jenkins_include_custom_files
   • For custom plugins: jenkins_custom_plugins

Example Jenkins Configuration File

In {{ jenkins_source_dir_configs }}/config.xml, you can set up global Jenkins configuration, like this:

<?xml version='1.1' encoding='UTF-8'?>
<hudson>
  ...
</hudson>

Example Job Configuration File

For {{ playbook_dir }}/jenkins-configs/jobs/my-first-job/config.xml, you could use:

<?xml version='1.0' encoding='UTF-8'?>
<project>
  <description>My first job, it says "hello world"</description>
  <builders>
    <hudson.tasks.Shell>
      <command>echo "Hello World!"</command>
    </hudson.tasks.Shell>
  </builders>
</project>

Authentication and Security

To secure Jenkins, you can use:

1. API token-based authentication (recommended).
2. Crumb-based authentication (for added CSRF protection).
3. No security (not recommended).

API token-based authentication

This is recommended for easy revocation and tracking. Here’s how to create one:

1. Create a special user or log in as an admin.
2. In the user settings, add a new API token.
3. Save the token value, preferably in an Ansible vault.
4. Define necessary variables in your playbook.

Crumb-based authentication

To prevent CSRF attacks, set this up if API tokens aren't practical. Note that it works with the "Anyone can do anything" access control.

You’ll need to install the Strict Crumb Issuer plugin if using Jenkins 2.176.2+.

HTTPS

To enable HTTPS in Jenkins:

• Define jenkins_port_https for the HTTPS port.
• Set up either JKS keystore or CA signed certificate details.
• Use a reverse proxy for Docker deployments for easier management.

License

MIT

Author Information

Created with care by Emmet O'Grady, founder of NimbleCI, which builds Docker containers for GitHub projects.

You can follow my insights on my personal blog and Docker topics on the NimbleCI blog.