nginx(role): use better naming, wording and file structure

Document the role arguments in the README instead of in the
argument_specs for better discoverability and readability.

roles/nginx/README.md

@@ -4,29 +4,38 @@ Makes sure the `nginx` package is installed from the NGINX repos on the specifie
 Also makes sure a desirable baseline of NGINX configs is deployed on the specified hosts.
 For the NGINX site configurations the config template below can be used.
 
-## Entry Points
-
-The entry points available for external use are:
-
-- `main`
-
 ## Supported Distributions
 
 The following distributions are supported:
 
 - Debian 11
+- Debian 12
 
 ## Required Arguments
 
-For the required arguments look at the [`argument_specs.yaml`](./meta/argument_specs.yaml).
+None.
 
-## Updates
+## Optional Arguments
 
-This role updates NGINX to the latest version covered by the provided version spec., if needed.
-
-## `hosts`
-
-The `hosts` for this role need to be the machines, for which you want to make sure the `nginx` package is installed from the NGINX repos and a desirable baseline of NGINX configs is deployed.
+- `nginx__deploy_redirect_conf`: Whether or not to deploy a config redirecting from HTTP to HTTPS, while still forwarding the `/.well-known/acme-challenge/` to localhost Port 31820 for certificate issuing.  
+  See [`files/redirect.conf`](./files/redirect.conf) for the configuration that would be deployed.  
+  Defaults to `true`.
+- `nginx__deploy_tls_conf`: Whether or not to deploy a config configuring some TLS settings reasonably.  
+  See [`files/tls.conf`](./files/tls.conf) for the configuration that would be deployed.  
+  Defaults to `true`.
+- `nginx__deploy_logging_conf`: Whether or not to deploy a config configuring logging to journald.  
+  See [`files/logging.conf`](./files/logging.conf) for the configuration that would be deployed.  
+  Defaults to `true`.
+- `nginx__configurations`: List of nginx configurations to ensure are deployed.
+- `nginx__configurations.*.name`: This name with `.conf` appended will be used for the configurations file name under `/etc/nginx/conf.d/`.  
+  `tls`, `redirect` and `logging` are reserved names.
+- `nginx__configurations.*.content`: This configurations content.  
+- `nginx__use_custom_nginx_conf`: Whether or not to use a custom `/etc/nginx/nginx.conf`.
+  If set to true, you must provide the content for a custom `nginx.conf` via `nginx__custom_nginx_conf`.  
+  Defaults to `false`.
+- `nginx__custom_nginx_conf`: The content to use for the custom `nginx.conf`.
+  Needs `nginx__use_custom_nginx_conf` to be set to true to work.  
+  You should probably still make sure that your custom `nginx.conf` includes `/etc/nginx/conf.d/*.conf`, so that the other configuration files still work.
 
 ## Config Template
 

roles/nginx/meta/argument_specs.yaml

@@ -1,31 +1,15 @@
 argument_specs:
   main:
     options:
-      nginx__version_spec:
-        description: >-
-          The version specification to use for installing the `nginx` package. The
-          provided version specification will be used like the following: `nginx={{
-          nginx__version_spec }}*`. This makes it possible to e.g. specify
-          until a minor version (like `1.3.`) and then have patch versions be
-          installed automatically (like `1.3.1` and so on).
-        type: str
-        required: true
       nginx__deploy_redirect_conf:
-        description: >-
-          Whether or not to deploy a `redirect.conf` to
-          `/etc/nginx/conf.d/redirect.conf`.
         type: bool
         required: false
         default: true
       nginx__deploy_tls_conf:
-        description: >-
-          Whether or not to deploy a `tls.conf` to `/etc/nginx/conf.d/tls.conf`.
         type: bool
         required: false
         default: true
       nginx__deploy_logging_conf:
-        description: >-
-          Whether or not to deploy a `logging.conf` to `/etc/nginx/conf.d/logging.conf`.
         type: bool
         required: false
         default: true
@@ -37,34 +21,16 @@ argument_specs:
         default: [ ]
         options:
           name:
-            description: >-
-              The name of the configuration file, where the configuration should
-              be deployed to. The file will be placed under `/etc/nginx/conf.d/`
-              and `.conf` will be appended to the given name. So in the end the
-              path will be like this: `/etc/nginx/conf.d/\{\{ name \}\}.conf`.
-              Note that the names `tls` and `redirect` aren't allowed.
             type: str
             required: true
           content:
-            description: The content of the configuration.
             type: str
             required: true
       nginx__use_custom_nginx_conf:
-        description: >-
-          Whether or not to use a custom `/etc/nginx/nginx.conf`. If set to
-          true, you must provide a custom `nginx.conf` via
-          `nginx__custom_nginx_conf`.
         type: bool
         required: false
         default: false
       nginx__custom_nginx_conf:
-        description: >-
-          The value for a `nginx.conf` to be placed at `/etc/nginx/nginx.conf`.
-          You must set `nginx__use_custom_nginx_conf` to true for this value to
-          be used.
-          You should probably make sure that your custom `nginx.conf` still
-          includes `/etc/nginx/conf.d/*.conf` so that the configuration provided
-          using `nginx__configurations` still work.
         type: str
         required: false
         default: ""

roles/nginx/tasks/main.yaml

@@ -1,19 +1,11 @@
-- name: make sure nginx configuration names are valid
-  ansible.builtin.include_role:
-    name: nginx
-    tasks_from: make_sure_nginx_configuration_names_are_valid
+- name: Ensure valid configuration names
+  ansible.builtin.import_tasks:
+    file: main/01_validate_config_names.yaml
 
-- name: make sure NGINX repos are setup
-  ansible.builtin.include_role:
-    name: nginx
-    tasks_from: main/repo_setup
+- name: Ensure nginx is installed
+  ansible.builtin.import_tasks:
+    file: main/02_nginx_install
 
-- name: make sure NGINX is installed
-  ansible.builtin.include_role:
-    name: nginx
-    tasks_from: main/nginx_install
-
-- name: make sure desirable NGINX configs are deployed
-  ansible.builtin.include_role:
-    name: nginx
-    tasks_from: main/config_deploy
+- name: Ensure configuration deployment
+  ansible.builtin.import_tasks:
+    file: main/03_config_deploy

roles/nginx/tasks/main/01_validate_config_names.yaml

@@ -0,0 +1,7 @@
+- name: Ensure that the given configuration names are valid
+  ansible.builtin.fail:
+    msg: "You used one of the reserved configuration names: '{{ item.name }}'."
+  when: item.name == "tls"
+        or item.name == "redirect"
+        or item.name == "logging"
+  loop: "{{ nginx__configurations }}"

roles/nginx/tasks/main/02_nginx_install.yaml

@@ -1,16 +1,10 @@
-- name: gather package facts
-  ansible.builtin.package_facts:
-    manager: apt
-
-- name: make sure `gnupg` package is installed
+- name: Ensure gnupg is installed
   ansible.builtin.apt:
     name: gnupg
     state: present
-    update_cache: true
   become: true
-  when: "'gnupg' not in ansible_facts.packages"
 
-- name: make sure NGINX signing key is added
+- name: Ensure NGINX signing key is added
   ansible.builtin.get_url:
     url: https://nginx.org/keys/nginx_signing.key
     dest: /etc/apt/trusted.gpg.d/nginx.asc
@@ -19,19 +13,19 @@
     group: root
   become: true
 
-- name: make sure NGINX APT repository is added
+- name: Ensure NGINX APT repository is added
   ansible.builtin.apt_repository:
     repo: "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/nginx.asc] https://nginx.org/packages/debian/ {{ ansible_distribution_release }} nginx"
     state: present
   become: true
 
-- name: make sure NGINX APT source repository is added
+- name: Ensure NGINX APT source repository is added
   ansible.builtin.apt_repository:
     repo: "deb-src [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/nginx.asc] https://nginx.org/packages/debian/ {{ ansible_distribution_release }} nginx"
     state: present
   become: true
 
-- name: set up repository pinning to make sure nginx package gets installed from NGINX repositories
+- name: Ensure repository pinning to make sure nginx package gets installed from NGINX repositories is set up
   ansible.builtin.copy:
     content: |
       Package: *
@@ -43,3 +37,10 @@
     group: root
     mode: "0644"
   become: true
+
+- name: Ensure nginx is installed
+  ansible.builtin.apt:
+    name: nginx
+    state: present
+    update_cache: true
+  become: true

roles/nginx/tasks/main/03_config_deploy.yaml

@@ -1,13 +1,13 @@
-- name: check, if a save of a previous `nginx.conf` is present
+- name: Check, if a save of a previous `nginx.conf` is present
   ansible.builtin.stat:
     path: /etc/nginx/nginx.conf.ansiblesave
-  register: nginx__nginx_conf_ansiblesave_stat_result
+  register: nginx__nginx_conf_ansiblesave_stat
 
-- name: handle the case, where a custom `nginx.conf` is to be used
+- name: Handle the case, where a custom `nginx.conf` is to be used
   when: nginx__use_custom_nginx_conf
   block:
-    - name: when no `nginx.conf.ansiblesave` is present, save the current `nginx.conf`
-      when: not nginx__nginx_conf_ansiblesave_stat_result.stat.exists
+    - name: When no `nginx.conf.ansiblesave` is present, save the current `nginx.conf`
+      when: not nginx__nginx_conf_ansiblesave_stat.stat.exists
       ansible.builtin.copy:
         force: true
         dest: /etc/nginx/nginx.conf.ansiblesave
@@ -18,7 +18,7 @@
         src: /etc/nginx/nginx.conf
       become: true
 
-    - name: deploy the custom `nginx.conf`
+    - name: Ensure the custom `nginx.conf` is deployed
       ansible.builtin.copy:
         content: "{{ nginx__custom_nginx_conf }}"
         dest: "/etc/nginx/nginx.conf"
@@ -28,11 +28,11 @@
       become: true
       notify: Restart `nginx.service`
 
-- name: handle the case, where no custom `nginx.conf` is to be used
+- name: Handle the case, where no custom `nginx.conf` is to be used
   when: not nginx__use_custom_nginx_conf
   block:
-    - name: when a `nginx.conf.ansiblesave` is present, copy it to `nginx.conf`
-      when: nginx__nginx_conf_ansiblesave_stat_result.stat.exists
+    - name: When a `nginx.conf.ansiblesave` is present, copy it to `nginx.conf`
+      when: nginx__nginx_conf_ansiblesave_stat.stat.exists
       ansible.builtin.copy:
         force: true
         dest: /etc/nginx/nginx.conf
@@ -44,14 +44,14 @@
       become: true
       notify: Restart `nginx.service`
 
-    - name: delete the `nginx.conf.ansiblesave`, if it is present
-      when: nginx__nginx_conf_ansiblesave_stat_result.stat.exists
+    - name: Ensure no `nginx.conf.ansiblesave` is present
+      when: nginx__nginx_conf_ansiblesave_stat.stat.exists
       ansible.builtin.file:
         path: /etc/nginx/nginx.conf.ansiblesave
         state: absent
       become: true
 
-- name: make sure mozilla dhparam is deployed
+- name: Ensure mozilla dhparam is deployed
   ansible.builtin.get_url:
     force: true
     dest: /etc/nginx-mozilla-dhparam
@@ -60,14 +60,14 @@
   become: true
   notify: Restart `nginx.service`
 
-- name: set `nginx__config_files_to_exist` fact initially to an empty list
+- name: Set `nginx__config_files_to_exist` fact initially to an empty list
   ansible.builtin.set_fact:
     nginx__config_files_to_exist: [ ]
 
-- name: handle the case, where tls.conf should be deployed
+- name: Handle the case, where tls.conf should be deployed
   when: nginx__deploy_tls_conf
   block:
-    - name: make sure tls.conf is deployed
+    - name: Ensure tls.conf is deployed
       ansible.builtin.copy:
         force: true
         dest: /etc/nginx/conf.d/tls.conf
@@ -78,14 +78,14 @@
       become: true
       notify: Restart `nginx.service`
 
-    - name: add tls.conf to nginx__config_files_to_exist
+    - name: Add tls.conf to nginx__config_files_to_exist
       ansible.builtin.set_fact:
         nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ 'tls.conf' ] }}"  # noqa: jinja[spacing]
 
-- name: handle the case, where redirect.conf should be deployed
+- name: Handle the case, where redirect.conf should be deployed
   when: nginx__deploy_redirect_conf
   block:
-    - name: make sure redirect.conf is deployed
+    - name: Ensure redirect.conf is deployed
       ansible.builtin.copy:
         force: true
         dest: /etc/nginx/conf.d/redirect.conf
@@ -96,14 +96,14 @@
       become: true
       notify: Restart `nginx.service`
 
-    - name: add redirect.conf to nginx__config_files_to_exist
+    - name: Add redirect.conf to nginx__config_files_to_exist
       ansible.builtin.set_fact:
         nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ 'redirect.conf' ] }}"  # noqa: jinja[spacing]
 
-- name: handle the case, where logging.conf should be deployed
+- name: Handle the case, where logging.conf should be deployed
   when: nginx__deploy_logging_conf
   block:
-    - name: make sure logging.conf is deployed
+    - name: Ensure logging.conf is deployed
       ansible.builtin.copy:
         force: true
         dest: /etc/nginx/conf.d/logging.conf
@@ -114,11 +114,11 @@
       become: true
       notify: Restart `nginx.service`
 
-    - name: add logging.conf to nginx__config_files_to_exist
+    - name: Add logging.conf to nginx__config_files_to_exist
       ansible.builtin.set_fact:
         nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ 'logging.conf' ] }}"  # noqa: jinja[spacing]
 
-- name: make sure all given configuration files are deployed
+- name: Ensure all given configuration files are deployed
   ansible.builtin.copy:
     content: "{{ item.content }}"
     dest: "/etc/nginx/conf.d/{{ item.name }}.conf"
@@ -129,19 +129,19 @@
   loop: "{{ nginx__configurations }}"
   notify: Restart `nginx.service`
 
-- name: add names plus suffix from `nginx__configurations` to `nginx__config_files_to_exist` fact
+- name: Add names with suffixes from `nginx__configurations` to `nginx__config_files_to_exist` fact
   ansible.builtin.set_fact:
     nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ item.name + '.conf' ] }}"  # noqa: jinja[spacing]
   loop: "{{ nginx__configurations }}"
 
-- name: find configuration files to remove
+- name: Find configuration files to remove
   ansible.builtin.find:
     paths: /etc/nginx/conf.d/
     recurse: false
     excludes: "{{ nginx__config_files_to_exist }}"
   register: nginx__config_files_to_remove
 
-- name: remove all configuration file, which should be removed
+- name: Remove all configuration file, which should be removed
   ansible.builtin.file:
     path: "{{ item.path }}"
     state: absent

roles/nginx/tasks/main/nginx_install.yaml

@@ -1,13 +0,0 @@
-- name: make sure the `nginx` package is installed
-  ansible.builtin.apt:
-    name: nginx={{ nginx__version_spec }}*
-    state: present
-    allow_change_held_packages: true
-    update_cache: true
-  become: true
-
-- name: apt-mark hold `nginx`
-  ansible.builtin.dpkg_selections:
-    name: nginx
-    selection: hold
-  become: true

roles/nginx/tasks/make_sure_nginx_configuration_names_are_valid.yaml

@@ -1,6 +0,0 @@
-- name: make sure nginx configuration names are valid
-  ansible.builtin.fail:
-    msg: "You used the following name: `{{ item.name }}`. Please make sure to not use the following names: `tls`, `redirect`."
-  when: item.name == "tls"
-        or item.name == "redirect"
-  loop: "{{ nginx__configurations }}"