Desired state in the role skeleton.

Signed-off-by: Bas Meijer <[email protected]>

README.md

@@ -1,17 +1,65 @@
-# ansible_skeleton
+# Ansible role skeleton
 Skeleton for `ansible-galaxy role init`
 
+# Using the template
+This template is designed for desired_state convergence with molecule.
+
+`desired_state` is a variable that drives the role.
+`present` is the default, and absent is the alterative for `desired_state`.
+
+The template is very generic for a systemd service installed from a corresponding package.
+Note that the tasks are split by state, for convergence, and that verify always runs.
+
+These 2 files control most of the play:
+- `tasks/main.yml`
+- `handlers/main.yml`
+
+
+To try it:
+
+```sh
+ansible-galaxy role init httpd
+cd httpd
+molecule converge
+molecule converge -- -e desired_state=absent
+```
+
+The same thing works for Nginx:
+```sh
+ansible-galaxy role init nginx
+molecule test
+```
+
+# Configure first!
+
 ```sh
-pip install --user pre-commit tox
 mkdir -p $HOME/git ~/.ansible/roles
 cd $HOME/git
-git clone https://github.com/playingfield/ansible_skeleton.git
-cd ansible_skeleton
-mv ansible.cfg $HOME/.ansible.cfg
-cd ~/.ansible/roles
-ansible-galaxy role init my_role
+git clone https://github.com/playingfield/role_skeleton.git
+```
+Add these lines to your ~/.ansible.cfg
+```ini
+[galaxy]
+role_skeleton = ~/git/role_skeleton
+role_skeleton_ignore = ^.git$,^.*/.git_keep$,README.md
+```
+
+## matrix testing in a generated role
+
+```sh
+pip install --user tox
+# edit tox.ini for a relevant setup
 tox
-cd my_role && git init && git add .
+```
+
+## pre-commit hooks in a generated role
+
+```sh
+pip install --user pre-commit tox
+# edit .pre-commit-config.yaml for a relevant setup
+git init
 pre-commit install
+git add .
+commit -m "initial commit"
 pre-commit run --all-files
 ```

ansible.cfg

@@ -1,7 +1,6 @@
+; https://docs.ansible.com/ansible/latest/installation_guide/intro_configuration.html
 [defaults]
 host_key_checking = False
-inventory = ~/.ansible_hosts.yml
-
 [galaxy]
 role_skeleton = ~/git/ansible_skeleton/role
 role_skeleton_ignore = ^.git$,^.*/.git_keep$

role/.ansible-lint

@@ -1,5 +1,5 @@
 ---
-#
+# https://ansible-lint.readthedocs.io/en/latest/default_rules/
 exclude_paths:
   - ./.tox
 skip_list:

role/.gitattributes

@@ -1,3 +1,4 @@
+# https://docs.github.com/en/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github
 # Default behaviour
 * text=auto
 

role/.pre-commit-config.yaml

@@ -1,4 +1,5 @@
 ---
+# https://pre-commit.com/hooks.html
 default_language_version:
   python: python3.8
 exclude: .venv
@@ -23,12 +24,6 @@ repos:
       - id: yamllint
         args: [-c=.yamllint]
 
-  - repo: https://github.com/ansible-community/ansible-lint.git
-    rev: v6.4.0
-    hooks:
-      - id: ansible-lint
-        files: \.yml$
-
   - repo: https://github.com/robertdebock/pre-commit
     rev: v1.2.2
     hooks:

role/.yamllint

@@ -1,4 +1,5 @@
 ---
+# https://yamllint.readthedocs.io/en/stable/rules.html
 extends: default
 ignore: |
   .tox/

role/defaults/main.yml.j2

@@ -1,3 +1,4 @@
----
 # defaults file for {{ role_name }}
+---
 desired_state: present
+package: {{ role_name }}

role/handlers/main.yml

@@ -0,0 +1,8 @@
+---
+# https://docs.ansible.com/ansible/latest/user_guide/playbooks_handlers.html
+- name: Control service
+  ansible.builtin.systemd:
+    name: "{{ service }}"
+    state: "{{ systemd_state }}"
+    enabled: "{{ systemd_enabled }}"
+    daemon_reload: true

role/meta/main.yml.j2

@@ -1,7 +1,8 @@
 ---
+# https://docs.ansible.com/ansible/latest/galaxy/dev_guide.html
 galaxy_info:
-  author: Name
-  description: Description
+  author: {{ lookup('env','USER') }}
+  description: Ansible role {{ role_name }}
   company: Company (optional)
   role_name: {{ role_name }}
   namespace: your_namespace

role/molecule/default/cleanup.yml.j2

@@ -3,8 +3,9 @@
 - name: Cleanup
   hosts: all
   gather_facts: false
+  vars:
+    desired_state: "absent"
   tasks:
     - name: "Include {{ role_name }}"
       ansible.builtin.include_role:
         name: "{{ role_name }}"
-        tasks_from: absent

role/molecule/default/molecule.yml.j2

@@ -20,11 +20,7 @@ dependency:
     role-file: requirements.yml
 
 driver:
-{% if lookup('pipe','uname') == 'Darwin' %}
-  name: docker
-{% else %}
   name: podman
-{% endif %}
 
 platforms:
   - name: ubi8

role/tasks/absent.yml

@@ -0,0 +1,9 @@
+# Tasks to converge to state absent
+---
+- name: flush handlers
+  ansible.builtin.meta: flush_handlers
+
+- name: Remove package
+  ansible.builtin.package:
+    name: "{{ package }}"
+    state: absent

role/tasks/main.yml

@@ -1,7 +1,13 @@
 ---
-# main tasks file for role
+# Main tasks entry point for the role
+- name: "State variables - {{ desired_state }}"
+  ansible.builtin.include_vars: "{{ desired_state }}.yml"
+
 - name: "Converge state - {{ desired_state }}"
-  include_tasks: "{{ desired_state }}.yml"
+  ansible.builtin.include_tasks: "{{ desired_state }}.yml"
+
+- name: Flush handlers
+  ansible.builtin.meta: flush_handlers
 
 - name: "Verify state - {{ desired_state }}"
-  include_tasks: verify.yml
+  ansible.builtin.include_tasks: verify.yml

role/tasks/prepare.yml.j2

@@ -1,2 +1,2 @@
 ---
-# tasks file for {{ role_name }}
+# prepare tasks file for {{ role_name }}

role/tasks/present.yml

@@ -0,0 +1,15 @@
+# Tasks to reach desired state present
+---
+- name: Manage package
+  ansible.builtin.package:
+    name: "{{ package }}"
+    state: "{{ desired_state }}"
+    update_cache: true
+  notify: Control service
+
+- name: Enable service
+  ansible.builtin.systemd:
+    name: "{{ service }}"
+    enabled: true
+    daemon_reload: true
+  notify: Control service

role/tasks/verify.yml

@@ -0,0 +1,36 @@
+# Verify desired state, both absent and present can be verified.
+---
+- name: Gather package facts
+  ansible.builtin.package_facts:
+
+- name: Assert package is installed
+  ansible.builtin.assert:
+    quiet: true
+    that:
+      - "'{{ package }}' {{ package_clause }} ansible_facts.packages"
+
+- name: Gather service facts
+  ansible.builtin.service_facts:
+
+- name: Assert service absence
+  when: desired_state == 'absent'
+  ansible.builtin.assert:
+    quiet: true
+    that:
+      - ansible_facts.services['{{ service }}'] is not defined
+
+- name: Test the service
+  when: desired_state == 'present'
+  block:
+    - name: Assert that service is OK
+      ansible.builtin.assert:
+        quiet: true
+        that:
+          - ansible_facts.services['{{ service~'.service' }}'].status == 'enabled'
+          - ansible_facts.services['{{ service~'.service' }}'].state == 'running'
+
+    - name: Verify service_port is listening
+      ansible.builtin.wait_for:
+        port: "{{ service_port }}"
+        state: started
+        timeout: 10

role/vars/absent.yml

@@ -0,0 +1,7 @@
+# Variable values for desired_state: absent
+---
+package_clause: "not in"
+service_state: stopped
+systemd_state: stopped
+systemd_enabled: false
+...

role/vars/main.yml

@@ -0,0 +1,4 @@
+# vars file for
+---
+service: "{{ package }}"
+service_port: 80

role/vars/present.yml

@@ -0,0 +1,7 @@
+# Variable values for desired_state: present
+---
+package_clause: "in"
+service_state: running
+systemd_state: started
+systemd_enabled: true
+...