Add support for HTTPS, improve handling of Jenkins URL (#48)

* Move duplicated tasks to common file

* Set the jenkins_url fact based on protocol

This change un-defines jenkins_url in the default's main.yml file, and
instead allows users to define jenkins_hostname instead. The rationale
for this is:

- Previously jenkins_url was not a true URL as it did not include the
  port. This was added by the role as necessary.
- It required the user to specify the protocol, which became a bit
  awkward when adding support for HTTPS.

This change includes backwards-compatibility support for playbooks
which define jenkins_url by re-defining it to the new value with a
port, and displaying a debug warning message to the user.

* Add support for HTTPS

* Improve "Role Variables" section of readme

This section originally copy/pasted the defaults/main.yml file, which
is not very sustainable since changes in that file were not always
propagated to the README. Instead, this section now includes
documentation on the most relevant options and links to the actual
file for everything else.

Author: nre-ableton

README.md

@@ -39,91 +39,35 @@ $ ansible-galaxy install emmetog.jenkins
 Role Variables
 --------------
 
-```yml
-jenkins_version: "2.73.1" # The exact version of jenkins to deploy
-
-jenkins_url: "http://127.0.0.1" # The url that Jenkins will be accessible on
-jenkins_port: "8080" # The port that Jenkins will listen on
-jenkins_home: /data/jenkins # The directory on the server where the Jenkins configs will live
-jenkins_admin: "admin@example.com" # The admininstrator email address for the Jenkins server
-
-# If you need to override any java options then do that here.
-jenkins_java_opts: "-Djenkins.install.runSetupWizard=false"
-
-# Install Jenkins by means of a Docker container
-jenkins_install_via: "docker"
-
-# Install Jenkins directly on Ubuntu/Debian Linux systems
-jenkins_install_via: "apt"
-
-# Install Jenkins directly on RedHat/CentOS Linux systems
-jenkins_install_via: "yum"
-
-# Configuration files owner and group
-jenkins_config_owner: "ubuntu"
-jenkins_config_group: "ubuntu"
-
-# The locations of the configuration files for jenkins
-jenkins_source_dir_configs: "{{ playbook_dir }}/jenkins-configs"
-jenkins_source_dir_jobs: "{{ jenkins_source_dir_configs }}/jobs"
-
-# config.xml template source
-jenkins_source_config_xml: "{{ jenkins_source_dir_configs }}/config.xml"
+The following variables influence how Jenkins is installed:
 
-# Include custom files for jenkins installation
-jenkins_include_custom_files: false
-jenkins_custom_files: {}
+- `jenkins_install_via`: Controls how Jenkins is installed. **Important**: This
+  variable must be defined to one of the following values:
+  - `docker`: Install in a Docker container
+  - `apt`: Install Jenkins directly on Ubuntu/Debian Linux systems
+  - `yum`: Install Jenkins directly on RedHat/CentOS Linux systems
+- `jenkins_version`: The exact version of jenkins to install
 
-# Include secrets directory during installation
-jenkins_include_secrets: false
-jenkins_source_secrets: "{{ jenkins_source_dir_configs }}/secrets/"
+The following variables influence how Jenkins is configured:
 
-# The names of the jobs (config.xml must exist under jenkins_source_dir_jobs/job_name/)
-jenkins_jobs: []
+- `jenkins_url`: The URL that Jenkins will be accessible on
+- `jenkins_port`: The port that Jenkins will listen on
+- `jenkins_home`: The directory on the server where the Jenkins configs will
+  live
+- `jenkins_admin`: The administrator's email address for the Jenkins server
+- `jenkins_java_opts`: Options passed to the Java executable
+- `jenkins_config_owner`: Owner of Jenkins configuration files
+- `jenkins_config_group`: Group of Jenkins configuration files
 
-# These plugins will be installed in the jenkins instance
-jenkins_plugins:
-  - git
-  - log-parser
-  - copyartifact
-  - workflow-aggregator
-  - workflow-multibranch
-  - docker-workflow
-  - template-project
-  - ec2
+The following list variables influence the jobs/plugins that will be installed
+in Jenkins:
 
-# List of sources of custom jenkins plugins to install
-jenkins_custom_plugins: []
+- `jenkins_jobs`: List of names of the jobs to copy to Jenkins. The `config.xml`
+  file must exist under `jenkins_source_dir_jobs/<job_name>`
+- `jenkins_plugins`: List of plugin IDs to install on Jenkins.
+- `jenkins_custom_plugins`: List of custom plugins to install on Jenkins.
 
-###################################################
-# Docker vars: apply to deploying via docker only #
-###################################################
-
-# The docker hub image name
-jenkins_docker_image: "jenkins/jenkins"
-
-# Configs specific to the "docker" method of running jenkins
-# The name of the jenkins container
-jenkins_docker_container_name: jenkins
-
-# Default, if true, the port will be exposed on the host (using "port")
-# If set to false, the port will only be exposed to other containers (using "expose")
-jenkins_docker_expose_port: true
-
-
-#############################################
-# Apt vars: apply to deploying via apt only #
-#############################################
-
-# Packages which are to be installed on the jenkins instance
-jenkins_apt_packages:
-  - openjdk-8-jdk
-
-# Java version to use. Note that JDK 8 is required for Jenkins
-# 2.54 or greater.
-jenkins_java_version: "java-1.8.0-openjdk-amd64"
-
-```
+For a complete list of variables, see [`defaults/main.yml`](defaults/main.yml).
 
 Example Playbook
 ----------------
@@ -133,7 +77,7 @@ Example Playbook
 
   vars:
     jenkins_version: "2.73.1"
-    jenkins_url: http://jenkins.example.com
+    jenkins_hostname: "jenkins.example.com"
     jenkins_port: 80
     jenkins_install_via: "docker"
     jenkins_jobs:
@@ -154,18 +98,33 @@ Example Playbook
 HTTPS
 -----
 
-If you want to enable HTTPS on jenkins we recommend that you use a
-reverse proxy like [jwilder/nginx-proxy](https://github.com/jwilder/nginx-proxy)
-or [traefik](https://github.com/containous/traefik) and configure it
-as the HTTPS endpoint instead of configuring jenkins itself with HTTPS.
-This gives you more flexibility and better separation of concerns. See
-the documentation in those projects for more details on how to deploy
-the proxies and configure HTTPS.
-
-If using a reverse proxy in front of the jenkins
-instance and deploying using docker you probably
-want to set the `jenkins_docker_expose_port` var to false so that the
-port is not exposed on the host, only to the reverse proxy.
+If you want to enable HTTPS on Jenkins, this can be done as follows:
+
+- Define `jenkins_port_https` to the port that Jenkins should listen on
+- Define variables *either* for the JKS keystore or the CA signed certificate:
+  * For JKS keystore, you'll need to define:
+    - `jenkins_https_keystore`: Path to the keystore file on the control host,
+      which will be copied to the Jenkins server by this role.
+    - `jenkins_https_keystore_password`: Password for said JKS keystore. Use of
+      the Ansible vault is recommended for this.
+  * For a CA signed certificate file, you'll need to define:
+    - `jenkins_https_certificate`: Path to the certificate file, which will be
+      copied to the Jenkins server by this role.
+    - `jenkins_https_private_key`: Private key for said CA signed certificate.
+      Use of the Ansible vault is recommended for this.
+- Optionally, `jenkins_https_validate_certs` should be defined to `false` if
+  you are using a self-signed certificate.
+
+If you are deploying Jenkins with Docker, then using a reverse proxy such as
+[jwilder/nginx-proxy](https://github.com/jwilder/nginx-proxy) or
+[traefik](https://github.com/containous/traefik) is recommended instead of
+configuring Jenkins itself. This gives a bit more flexibility and allows for
+separation of responsibilities. See the documentation in those projects for
+more details on how to deploy the proxies and configure HTTPS.
+
+If using a reverse proxy in front of the Jenkins instance and deploying using
+Docker you probably want to set the `jenkins_docker_expose_port` variable to
+false so that the port is not exposed on the host, only to the reverse proxy.
 
 Authentication and Security
 ---------------------------

defaults/main.yml

@@ -1,8 +1,13 @@
 ---
 jenkins_version: "2.73.1"  # The exact version of jenkins to deploy
 
-jenkins_url: "http://127.0.0.1"  # The url that Jenkins will be accessible on
-jenkins_port: "8080"  # The port that Jenkins will listen on
+jenkins_hostname: "127.0.0.1"  # The hostname that Jenkins will be accessible on
+# The port that Jenkins will listen on for unsecured (HTTP) requests. Define to -1 to
+# disable HTTP.
+jenkins_port: "8080"
+# The port that Jenkins will listen on for secured (HTTPS) requests. Define to -1 to
+# disable HTTPS. Enabling this option requires a SSL certificate (see below).
+jenkins_port_https: "-1"
 jenkins_home: /data/jenkins  # The directory on the server where the Jenkins configs live
 jenkins_admin: "admin@example.com"  # The administrator email address for the server
 
@@ -72,6 +77,26 @@ jenkins_api_token: ""
 # Username which owns the above API token.
 jenkins_api_username: ""
 
+#########################################
+# SSL vars: apply to Jenkins HTTPS only #
+#########################################
+
+# See https://wiki.jenkins.io/display/JENKINS/Starting+and+Accessing+Jenkins for more info
+
+# Jenkins JKS keystore file. Mutually exclusive with the certificate/private key options.
+jenkins_https_keystore: ""
+# Jenkins JKS keystore password.
+jenkins_https_keystore_password: ""
+
+# Jenkins CA signed certificate file. Mutually exclusive with the keystore options.
+jenkins_https_certificate: ""
+# Jenkins CA signed certificate private key.
+jenkins_https_private_key: ""
+
+# Set to false if you are using a self-signed certificate and wish to ignore any
+# certificate verification errors from Ansible.
+jenkins_https_validate_certs: true
+
 ###################################################
 # Docker vars: apply to deploying via docker only #
 ###################################################

files/jenkins.model.JenkinsLocationConfiguration.xml.j2

@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='UTF-8'?>
 <jenkins.model.JenkinsLocationConfiguration>
   <adminAddress>{{ jenkins_admin }}</adminAddress>
-  <jenkinsUrl>{{ jenkins_url }}:{{ jenkins_port }}</jenkinsUrl>
+  <jenkinsUrl>{{ jenkins_url }}</jenkinsUrl>
 </jenkins.model.JenkinsLocationConfiguration>

tasks/apt/install.yml

@@ -63,21 +63,3 @@
     name: "jenkins={{ jenkins_version }}"
     force: true
     update_cache: true
-
-- name: Set JENKINS_HOME
-  lineinfile:
-    dest: /etc/default/jenkins
-    line: "JENKINS_HOME={{ jenkins_home }}"
-    regexp: '^JENKINS_HOME='
-
-- name: Set Jenkins port
-  lineinfile:
-    dest: /etc/default/jenkins
-    regexp: '^HTTP_PORT='
-    line: "HTTP_PORT={{ jenkins_port }}"
-
-- name: Set Jenkins command line options
-  lineinfile:
-    dest: /etc/default/jenkins
-    regexp: '^JAVA_ARGS='
-    line: "JAVA_ARGS=\"{{ jenkins_java_opts }}\""

tasks/cancel-quiet-mode.yml

@@ -1,7 +1,7 @@
 ---
 - name: Cancel quiet mode with API token
   uri:
-    url: "{{ jenkins_url }}:{{ jenkins_port }}/cancelQuietDown"
+    url: "{{ jenkins_url }}/cancelQuietDown"
     method: POST
     headers:
       Content-Type: "text/xml"
@@ -16,7 +16,7 @@
 
 - name: Cancel quiet mode with crumb
   uri:
-    url: "{{ jenkins_url }}:{{ jenkins_port }}/cancelQuietDown"
+    url: "{{ jenkins_url }}/cancelQuietDown"
     method: POST
     headers:
       Content-Type: "text/xml"
@@ -27,9 +27,10 @@
 
 - name: Cancel quiet mode with no security
   uri:
-    url: "{{ jenkins_url }}:{{ jenkins_port }}/cancelQuietDown"
+    url: "{{ jenkins_url }}/cancelQuietDown"
     method: POST
     headers:
       Content-Type: "text/xml"
     status_code: 200,302
+    validate_certs: "{{ jenkins_https_validate_certs }}"
   when: jenkins_auth == "none"

tasks/configure-config.yml

@@ -0,0 +1,57 @@
+---
+- name: Set JENKINS_HOME
+  lineinfile:
+    create: true
+    dest: "/etc/default/jenkins"
+    line: "JENKINS_HOME={{ jenkins_home }}"
+    regexp: '^JENKINS_HOME='
+    state: present
+
+- name: Set Jenkins port
+  lineinfile:
+    dest: /etc/default/jenkins
+    regexp: '^HTTP_PORT='
+    line: "HTTP_PORT={{ jenkins_port }}"
+
+- name: Set Jenkins Java command line options
+  lineinfile:
+    dest: /etc/default/jenkins
+    regexp: '^JAVA_ARGS='
+    line: "JAVA_ARGS=\"{{ jenkins_java_opts }}\""
+
+- name: Copy JKS keystore credentials
+  copy:
+    src: "{{ jenkins_https_keystore }}"
+    dest: "{{ jenkins_home }}"
+  when: jenkins_https_keystore and jenkins_https_keystore_password
+
+- name: Copy CA signed certificate
+  copy:
+    src: "{{ jenkins_https_certificate }}"
+    dest: "{{ jenkins_home }}"
+  when: jenkins_https_certificate and jenkins_https_private_key
+
+- name: Initialize HTTPS credentials fact
+  set_fact:
+    jenkins_https_creds: ""
+
+- name: Set JKS keystore credentials
+  set_fact:
+    jenkins_https_creds: >
+      --httpsKeyStore='{{ jenkins_home }}/{{ jenkins_https_keystore }}' \
+      --httpsKeyStorePassword='{{ jenkins_https_keystore_password }}'
+  when: jenkins_https_keystore and jenkins_https_keystore_password
+
+- name: Set CA signed certificate credentials
+  set_fact:
+    jenkins_https_creds: >
+      --httpsCertificate='{{ jenkins_home }}/{{ jenkins_https_certificate }}' \
+      --httpsPrivateKey='{{ jenkins_https_private_key }}'
+  when: jenkins_https_certificate and jenkins_https_private_key
+
+- name: Set Jenkins command line options
+  lineinfile:
+    dest: /etc/default/jenkins
+    regexp: '^JENKINS_ARGS='
+    line: "JENKINS_ARGS=\"--webroot=/var/cache/$NAME/war --httpPort={{ jenkins_port }} \
+      --httpsPort={{ jenkins_port_https }} {{ jenkins_https_creds }}\""

tasks/configure-plugins.yml

@@ -21,11 +21,12 @@
     jenkins_home: "{{ jenkins_home }}"
     owner: "{{ jenkins_config_owner }}"
     group: "{{ jenkins_config_group }}"
-    url: "{{ jenkins_url }}:{{ jenkins_port }}"
+    url: "{{ jenkins_url }}"
     timeout: "{{ jenkins_plugin_timeout }}"
     url_username: "{{ jenkins_api_username }}"
     url_password: "{{ jenkins_api_token }}"
     force_basic_auth: true
+    validate_certs: "{{ jenkins_https_validate_certs }}"
   with_items: "{{ jenkins_plugins }}"
   when: jenkins_auth == "api"
 
@@ -39,7 +40,7 @@
     jenkins_home: "{{ jenkins_home }}"
     owner: "{{ jenkins_config_owner }}"
     group: "{{ jenkins_config_group }}"
-    url: "{{ jenkins_url }}:{{ jenkins_port }}"
+    url: "{{ jenkins_url }}"
     timeout: "{{ jenkins_plugin_timeout }}"
   with_items: "{{ jenkins_plugins }}"
   when: jenkins_auth == "crumb" or jenkins_auth == "none"

tasks/get-crumb.yml

@@ -1,10 +1,11 @@
 ---
 - name: Get crumb for Jenkins API
   uri:
-    url: '{{ jenkins_url }}:{{ jenkins_port }}
+    url: '{{ jenkins_url }}
       /crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)'
     return_content: true
     status_code: 200,404
+    validate_certs: "{{ jenkins_https_validate_certs }}"
   register: jenkins_crumb
   until: jenkins_crumb.status == 200 or jenkins_crumb.status == 404
   retries: 5

tasks/main.yml

@@ -1,8 +1,30 @@
 ---
 - include: "sanity-checks.yml"
 
+# Previous versions of this role defined jenkins_url as a default variable, but this URL
+# did not include the port, and required the user to hard-code the protocol.
+- name: Set jenkins_url fact for backwards-compatibility installations
+  set_fact:
+    jenkins_url: "{{ jenkins_url }}:{{ jenkins_port }}"
+  when: jenkins_url is defined
+
+- name: Set jenkins_url fact for HTTP
+  set_fact:
+    jenkins_url: "http://{{ jenkins_hostname }}:{{ jenkins_port }}"
+  when: jenkins_port != "-1" and jenkins_url is not defined
+
+# Note that this task will overwrite jenkins_url if both HTTP and HTTPS ports are defined.
+# This is by intention.
+- name: Set jenkins_url fact for HTTPS
+  set_fact:
+    jenkins_url: "https://{{ jenkins_hostname }}:{{ jenkins_port_https }}"
+  when: jenkins_port_https != "-1" and jenkins_url is not defined
+
 - include: "{{ jenkins_install_via }}/install.yml"
 
+- include: "configure-config.yml"
+  when: jenkins_install_via != "docker"
+
 - include: "configure-jenkins.yml"
 
 - include: "configure-files.yml"