Skip to content

Latest commit

 

History

History
175 lines (138 loc) · 7.9 KB

README.md

File metadata and controls

175 lines (138 loc) · 7.9 KB
Raw

Build Status

Ansible Role for Jenkins 2+

This Ansible role can be used to install and manage Jenkins 2.

Requirements

This role requires Ansible 2.4 or later, with either Ansible pipelining available or setfacl available on the system being managed (per Becoming an Unprivileged User).

The role currently supports Ubuntu 14.04 (Trusty) and Ubuntu 16.04 (Xenial), though contributtions for additional platform support are welcome!

Role Variables

This role supports the following variables, listed here with their default values from defaults/main.yml:

  • jenkins_release_line: 'weekly'
    • When set to long_term_support, the role will install the LTS releases of Jenkins.
    • When set to weekly, the role will install the weekly releases of Jenkins.
  • jenkins_home: /var/lib/jenkins
    • The directory that (most of) Jenkins data will be stored.
    • Due to limitations of the Jenkins installer, the jenkins service account will still use the default as its home directory. This should really only come into play for SSH keys.
  • jenkins_port: 8080
    • The port that Jenkins will run on, for HTTP requests.
    • On most systems, this value will need to be over 1024, as Jenkins is not run as root.
  • jenkins_context_path: ''
    • The context path that Jenkins will be hosted at, e.g. /foo in http://localhost:8080/foo. Leave as '' to host at root path.
  • jenkins_url_external: ''
    • The external URL that users will use to access Jenkins. Gets set in the Jenkins config and used in emails, webhooks, etc.
    • If this is left empty/None, the configuration will not be set and Jenkins will try to auto-discover this (which won't work correctly if it's proxied).
  • jenkins_admin_username: (undefined)
    • If one of jenkins_admin_username and jenkins_admin_password are defined, both must be.
    • Override this variable to specify the Jenkins administrator credentials that should be used for each possible security realm.
    • If left undefined, the role will attempt to use anonymous authentication.
    • Note that the role will automatically detect if Jenkins is set to allow anonymous authentication (as is the case right after install) and handle it properly.
  • jenkins_admin_password: (undefined)
    • If one of jenkins_admin_username and jenkins_admin_password are defined, both must be.
    • Override this variable to specify the Jenkins administrator credentials that should be used for each possible security realm.
  • jenkins_plugins_extra: []
    • Override this variable to install additional Jenkins plugins.
    • These would be in addition to the plugins recommended by Jenkins 2's new setup wizard, which are installed automatically by this role (see jenkins_plugins_recommended in defaults/main.yml).
  • jenkins_java_args_extra: ''
    • Additional options that will be added to JAVA_ARGS for the Jenkins process, such as the JVM memory settings, e.g. -Xmx4g.

Dependencies

This role does not have direct dependencies on other Ansible roles. However, it does require that a Java JRE be available on the system path.

Example Playbook

This role can be installed, as follows:

$ ansible-galaxy install karlmdavis.jenkins2

This role can be applied, as follows:

- hosts: some_box
  tasks:
    - import_role:
        name: karlmdavis.ansible-jenkins2
      vars:
        jenkins_plugins_extra:
          - github-oauth

Running Groovy Scripts to Configure Jenkins

After installing Jenkins, Groovy scripts can be run via Ansible to further customize Jenkins.

For example, here's how to install Jenkins and then configure Jenkins to use its HudsonPrivateSecurityRealm, for local Jenkins accounts:

- hosts: some_box
  tasks:

    - import_role:
        name: karlmdavis.ansible-jenkins2
      vars:
        # Won't be required on first run, but will be on prior runs (after
        # security has been enabled, per below).
        jenkins_admin_username: test
        jenkins_admin_password: supersecret

    # Ensure that Jenkins has restarted, if it needs to.
    - meta: flush_handlers

    # Configure security to use Jenkins-local accounts.
    - name: Configure Security
      jenkins_script:
        url: "{{ jenkins_url_local }}"
        user: "{{ jenkins_dynamic_admin_username | default(omit) }}"
        password: "{{ jenkins_dynamic_admin_password | default(omit) }}"
        script: |
          // These are the basic imports that Jenkin's interactive script console
          // automatically includes.
          import jenkins.*;
          import jenkins.model.*;
          import hudson.*;
          import hudson.model.*;

          // Configure the security realm, which handles authentication.
          def securityRealm = new hudson.security.HudsonPrivateSecurityRealm(false)
          if(!securityRealm.equals(Jenkins.instance.getSecurityRealm())) {
            Jenkins.instance.setSecurityRealm(securityRealm)

            // Create a user to login with. Ensure that user is bound to the
            // system-local `jenkins` user's SSH key, to ensure that this
            // account can be used with Jenkins' CLI.
            def testUser = securityRealm.createAccount("test", "supersecret")
            testUser.addProperty(new hudson.tasks.Mailer.UserProperty("[email protected]"));
            testUser.save()

            Jenkins.instance.save()
            println "Changed authentication."
          }

          // Configure the authorization strategy, which specifies who can do
          // what.
          def authorizationStrategy = new hudson.security.FullControlOnceLoggedInAuthorizationStrategy()
          if(!authorizationStrategy.equals(Jenkins.instance.getAuthorizationStrategy())) {
            authorizationStrategy.setAllowAnonymousRead(false)
            Jenkins.instance.setAuthorizationStrategy(authorizationStrategy)
            Jenkins.instance.save()
            println "Changed authorization."
          }
      register: shell_jenkins_security
      changed_when: "(shell_jenkins_security | success) and 'Changed' not in shell_jenkins_security.stdout"

Alternatively, the Groovy scripts can be stored as separate files and pulled in using a lookup(...), as below:

- hosts: some_box
  tasks:

    - import_role:
        name: karlmdavis.ansible-jenkins2
      vars:
        # Won't be required on first run, but will be on prior runs (after
        # security has been enabled, per below).
        jenkins_admin_username: test
        jenkins_admin_password: supersecret

    # Ensure that Jenkins has restarted, if it needs to.
    - meta: flush_handlers

    # Configure security to use Jenkins-local accounts.
    - name: Configure Security
      jenkins_script:
        url: "{{ jenkins_url_local }}"
        user: "{{ jenkins_dynamic_admin_username | default(omit) }}"
        password: "{{ jenkins_dynamic_admin_password | default(omit) }}"
        script: "{{ lookup('template', 'templates/jenkins_security.groovy.j2') }}"

License

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

Author Information

This plugin was authored by Karl M. Davis (https://justdavis.com/karl/).