feat(jenkins_inbound_agent): add ansible role for deployment with docker

README.md

@@ -9,6 +9,7 @@ proxies and artifact registries.
 ## Roles
 
 - [`jenkins`](roles/jenkins/README.md): Deploy [jenkins](https://jenkins.io), the self-proclaimed 'leading open source automation server'.
+- [`jenkins_inbound_agent`](roles/jenkins_inbound_agent/README.md): Deploy Jenkins 'inbound agent', formerly known as 'JNLP agent'.
 
 ## License
 

roles/jenkins_inbound_agent/README.md

@@ -0,0 +1,11 @@
+# `finallycoffee.cicd.jenkins_inbound_agent` ansible role
+
+## Overview
+
+Deploy Jenkins inbound agents using docker.
+
+## Required configuration
+
+- `jenkins_agent_server_url` - URL of the jenkins control node, including protocol and port, i.e.: http://jenkins-server:port
+- `jenkins_agent_secret` - Secret for this jenkins agent generated by the jenkins control node
+- `jenkins_agent_name` - Name of this (inbound) agent, must match agent name in jenkins control node

roles/jenkins_inbound_agent/defaults/main/container.yml

@@ -0,0 +1,79 @@
+---
+jenkins_agent_container_name: "jenkins-inbound-agent-{{ jenkins_agent_name }}"
+jenkins_agent_container_image: >-2
+  {{
+    [
+      jenkins_agent_container_image_repository,
+      jenkins_agent_container_image_tag
+        | default(
+          jenkins_agent_version + jenkins_agent_container_suffix,
+          true
+        )
+    ] | join(':')
+  }}
+jenkins_agent_container_image_registry: docker.io
+jenkins_agent_container_image_namespace: jenkins
+jenkins_agent_container_image_name: inbound-agent
+jenkins_agent_container_image_repository: >-2
+  {{
+    [
+      jenkins_agent_container_image_registry | default([], true),
+      jenkins_agent_container_image_namespace | default([], true),
+      jenkins_agent_container_image_name
+    ] | flatten | join('/')
+  }}
+jenkins_agent_container_image_source: "pull"
+jenkins_agent_container_image_force_source: >-2
+  {{ jenkins_agent_container_image_tag | default(true, true) }}
+jenkins_agent_container_image_tag: ~
+jenkins_agent_container_image_jdk_version: "jdk17"
+jenkins_agent_container_image_distribution: "alpine"
+
+jenkins_agent_container_suffix: >-2
+  {{
+    (
+      ((jenkins_agent_container_image_distribution is string)
+        and (jenkins_agent_container_image_distribution | length > 0))
+      | ternary(
+        '-' + jenkins_agent_container_image_distribution | default('', true),
+        ''
+      )
+    )
+    +
+    (
+      ((jenkins_agent_container_image_jdk_version is string)
+        and (jenkins_agent_container_image_jdk_version | length > 0))
+      | ternary(
+        '-' + jenkins_agent_container_image_jdk_version | default('', true),
+        ''
+      )
+    )
+  }}
+
+jenkins_agent_container_env: ~
+jenkins_agent_container_base_env:
+  JENKINS_URL: "{{ jenkins_agent_server_url | ansible.builtin.mandatory }}"
+  JENKINS_AGENT_NAME: "{{ jenkins_agent_name | ansible.builtin.mandatory }}"
+  JENKINS_AGENT_WORKDIR: "{{ jenkins_agent_work_dir | default('/home/jenkins/agent') }}"
+  JENKINS_WEB_SOCKET: "true"
+  JENKINS_SECRET: "@{{ jenkins_agent_secret_file }}"
+jenkins_agent_container_all_env: >-2
+  {{ jenkins_agent_container_base_env
+    | combine(jenkins_agent_container_env | default({}, true)) }}
+jenkins_agent_container_user: >-2
+  {{ jenkins_agent_user_uid }}:{{ jenkins_agent_user_gid }}
+jenkins_agent_container_ports: ~
+jenkins_agent_container_state: >-2
+  {{ (jenkins_agent_state == 'present') | ternary('started', 'absent') }}
+jenkins_agent_container_labels:
+  version: "{{ jenkins_agent_container_image_tag | default(jenkins_agent_version, true) }}"
+jenkins_agent_container_networks: ~
+jenkins_agent_container_etc_hosts: ~
+jenkins_agent_container_base_volumes:
+  - "{{ jenkins_agent_passwd_shim_file }}:/etc/passwd:ro"
+  - "{{ jenkins_agent_secret_file }}:{{ jenkins_agent_secret_file }}:ro"
+jenkins_agent_container_volumes: ~
+jenkins_agent_container_all_volumes: >-2
+  {{ jenkins_agent_container_base_volumes | default([], true)
+     + jenkins_agent_container_volumes | default([], true) }}
+jenkins_agent_container_restart_policy: "on-failure"

roles/jenkins_inbound_agent/defaults/main/main.yml

@@ -0,0 +1,18 @@
+---
+jenkins_agent_user: "jenkins-agent"
+jenkins_agent_user_create_home: false
+jenkins_agent_user_is_system: false
+jenkins_agent_user_uid: "{{ jenkins_agent_user_info.uid }}"
+jenkins_agent_user_gid: "{{ jenkins_agent_user_info.group }}"
+
+jenkins_agent_version: "3283.v92c105e0f819-8"
+
+jenkins_agent_state: "present"
+jenkins_agent_deployment_method: "docker"
+
+jenkins_agent_name: ~
+jenkins_agent_secret: ~
+jenkins_agent_server_url: ~
+
+jenkins_agent_secret_file: "/etc/jenkins/agent/{{ jenkins_agent_name }}.secret"
+jenkins_agent_passwd_shim_file: "/etc/jenkins/agent/{{ jenkins_agent_name }}-passwd"

roles/jenkins_inbound_agent/handlers/main.yml

@@ -0,0 +1,13 @@
+---
+- name: Restart jenkins agent container '{{ jenkins_agent_container_name }}'
+  community.docker.docker_container:
+    name: "{{ jenkins_agent_container_name }}"
+    state: "started"
+    restart: true
+    comparisons:
+      '*': "ignore"
+  listen: jenkins_agent_restart
+  when:
+    - jenkins_deployment_method == 'docker'
+    - jenkins_agent_container_state == 'started'
+  ignore_errors: "{{ ansible_check_mode }}"

roles/jenkins_inbound_agent/tasks/check.yml

@@ -0,0 +1,38 @@
+---
+- name: Ensure 'jenkins_agent_state' is valid
+  ansible.builtin.fail:
+    msg: >-2
+      Unsupported jenkins_agent_state '{{ jenkins_agent_state }}'.
+      Supported values are: {{ jenkins_agent_states | join(', ') }}
+  when: jenkins_agent_state not in jenkins_agent_states
+
+- name: Ensure 'jenkins_agent_deployment_method' is valid
+  ansible.builtin.fail:
+    msg: >-2
+      Unsupported jenkins_agent_deployment_method '{{ jenkins_agent_deployment_method }}'.
+      Supported values are: {{ jenkins_agent_deployment_methods | join(', ') }}
+  when: jenkins_agent_deployment_method not in jenkins_agent_deployment_methods
+
+- name: Ensure Jenkins agent JDK version is valid if specified
+  ansible.builtin.fail:
+    msg: >-2
+      Unsupported jenkins_agent_container_image_jdk_version
+      '{{ jenkins_agent_container_image_jdk_version }}' specified!
+      Supported JDK versions are:
+      {{ jenkins_agent_container_image_jdk_versions | join(', ') }}
+  when:
+    - jenkins_agent_container_image_jdk_version is string
+    - jenkins_agent_container_image_jdk_version | length > 0
+    - jenkins_agent_container_image_jdk_version not in jenkins_agent_container_image_jdk_versions
+
+- name: Ensure Jenkins agent distribution is valid if specified
+  ansible.builtin.fail:
+    msg: >-2
+      Unsupported jenkins_agent_container_image_distribution
+      '{{ jenkins_agent_container_image_distribution }}' specified!
+      Supported JDK versions are:
+      {{ jenkins_agent_container_image_distibrutions | join(', ') }}
+  when:
+    - jenkins_agent_container_image_distribution is string
+    - jenkins_agent_container_image_distribution | length > 0
+    - jenkins_agent_container_image_distribution not in jenkins_agent_container_image_distributions

roles/jenkins_inbound_agent/tasks/deploy-docker.yml

@@ -0,0 +1,58 @@
+---
+- name: Ensure container image '{{ jenkins_agent_container_image }}' is {{ jenkins_agent_state }}
+  community.docker.docker_image:
+    name: "{{ jenkins_agent_container_image }}"
+    state: "{{ jenkins_agent_state }}"
+    source: "{{ jenkins_agent_container_image_source }}"
+    force_source: "{{ jenkins_agent_container_image_force_source }}"
+
+- name: Ensure jenkins configuration directory exists
+  ansible.builtin.file:
+    path: "{{ jenkins_agent_secret_file | dirname }}"
+    state: directory
+    mode: "0755"
+    recurse: true
+  when: jenkins_agent_state == 'present'
+
+- name: Ensure jenkins agent secret is persisted
+  ansible.builtin.copy:
+    dest: "{{ jenkins_agent_secret_file }}"
+    content: "{{ jenkins_agent_secret }}"
+    mode: "0400"
+    owner: "{{ jenkins_agent_user_uid | default(jenkins_agent_user) }}"
+    group: "{{ jenkins_agent_user_gid | default(jenkins_agent_user) }}"
+  when: jenkins_agent_state == 'present'
+  notify:
+    - jenkins_agent_restart
+
+- name: Ensure jenkins agent fake '/etc/passwd' is templated
+  ansible.builtin.template:
+    src: "docker-passwd.j2"
+    dest: "{{ jenkins_agent_passwd_shim_file }}"
+    mode: "0644"
+    owner: "root"
+    group: "root"
+
+- name: Ensure jenkins configuration is removed
+  ansible.builtin.file:
+    path: "{{ jenkins_agent_secret_file | dirname }}"
+    state: absent
+    recurse: true
+  when: jenkins_agent_state == 'absent'
+
+- name: Ensure jenkins-agent container '{{ jenkins_agent_container_name }}' is {{ jenkins_agent_container_state }}
+  community.docker.docker_container:
+    name: "{{ jenkins_agent_container_name }}"
+    image: "{{ jenkins_agent_container_image }}"
+    env: "{{ jenkins_agent_container_all_env | default(omit, true) }}"
+    init: "{{ jenkins_agent_container_init | default(true, true) }}"
+    user: "{{ jenkins_agent_container_user | default(omit, true) }}"
+    ports: "{{ jenkins_agent_container_ports | default(omit, true) }}"
+    labels: "{{ jenkins_agent_container_labels | default(omit, true) }}"
+    volumes: "{{ jenkins_agent_container_all_volumes }}"
+    networks: "{{ jenkins_agent_container_networks | default(omit, true) }}"
+    etc_hosts: "{{ jenkins_agent_container_etc_hosts | default(omit, true) }}"
+    restart_policy: "{{ jenkins_agent_container_restart_policy }}"
+    state: "{{ jenkins_agent_container_state }}"
+    comparisons:
+      "env": "strict"

roles/jenkins_inbound_agent/tasks/main.yml

@@ -0,0 +1,16 @@
+---
+- name: Ensure required variables are populated (correctly)
+  ansible.builtin.include_tasks:
+    file: "check.yml"
+
+- name: Ensure jenkins-agent user '{{ jenkins_agent_user }}' is {{ jenkins_agent_state }}
+  ansible.builtin.user:
+    name: "{{ jenkins_agent_user }}"
+    state: "{{ jenkins_agent_state }}"
+    system: "{{ jenkins_agent_user_is_system }}"
+    create_home: "{{ jenkins_agent_user_create_home }}"
+  register: jenkins_agent_user_info
+
+- name: Ensure jenkins-agent '{{ jenkins_agent_name }}' is deployed using {{ jenkins_agent_deployment_method }}
+  ansible.builtin.include_tasks:
+    file: "deploy-{{ jenkins_agent_deployment_method }}.yml"

roles/jenkins_inbound_agent/templates/docker-passwd.j2

@@ -0,0 +1,18 @@
+root:x:0:0:root:/root:/bin/sh
+bin:x:1:1:bin:/bin:/sbin/nologin
+daemon:x:2:2:daemon:/sbin:/sbin/nologin
+lp:x:4:7:lp:/var/spool/lpd:/sbin/nologin
+sync:x:5:0:sync:/sbin:/bin/sync
+shutdown:x:6:0:shutdown:/sbin:/sbin/shutdown
+halt:x:7:0:halt:/sbin:/sbin/halt
+mail:x:8:12:mail:/var/mail:/sbin/nologin
+news:x:9:13:news:/usr/lib/news:/sbin/nologin
+uucp:x:10:14:uucp:/var/spool/uucppublic:/sbin/nologin
+cron:x:16:16:cron:/var/spool/cron:/sbin/nologin
+ftp:x:21:21::/var/lib/ftp:/sbin/nologin
+sshd:x:22:22:sshd:/dev/null:/sbin/nologin
+games:x:35:35:games:/usr/games:/sbin/nologin
+ntp:x:123:123:NTP:/var/empty:/sbin/nologin
+guest:x:405:100:guest:/dev/null:/sbin/nologin
+nobody:x:65534:65534:nobody:/:/sbin/nologin
+jenkins:x:1000:1000:Linux User,,,:/home/jenkins:/bin/sh

roles/jenkins_inbound_agent/vars/main.yml

@@ -0,0 +1,13 @@
+---
+jenkins_agent_states:
+  - "present"
+  - "absent"
+jenkins_agent_deployment_methods:
+  - "docker"
+jenkins_agent_container_image_jdk_versions:
+  - "jdk17"
+  - "jdk21"
+jenkins_agent_container_image_distributions:
+  - "alpine"
+  - "alpine3.21"
+  - "rhel-ubi9"