nginx(role): document arguments in README for better discoverability

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

roles/nginx/README.md

@@ -18,11 +18,29 @@ The following distributions are supported:
 
 ## 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.
+- `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` and `redirect` 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.
 
 ## `hosts`
 

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

@@ -3,12 +3,7 @@
     name: nginx
     tasks_from: make_sure_nginx_configuration_names_are_valid
 
-- name: make sure NGINX repos are setup
-  ansible.builtin.include_role:
-    name: nginx
-    tasks_from: main/repo_setup
-
-- name: make sure NGINX is installed
+- name: ensure NGINX is installed
   ansible.builtin.include_role:
     name: nginx
     tasks_from: main/nginx_install

roles/nginx/tasks/main/nginx_install.yaml

@@ -1,13 +1,47 @@
-- name: make sure the `nginx` package is installed
+- name: Ensure gnupg is installed
   ansible.builtin.apt:
-    name: nginx={{ nginx__version_spec }}*
+    name: gnupg
+    state: present
+  become: true
+
+- name: make sure 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
+    mode: "0644"
+    owner: root
+    group: root
+  become: true
+
+- name: make sure 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
+  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
+  ansible.builtin.copy:
+    content: |
+      Package: *
+      Pin: origin nginx.org
+      Pin: release o=nginx
+      Pin-Priority: 900
+    dest: /etc/apt/preferences.d/99nginx
+    owner: root
+    group: root
+    mode: "0644"
+  become: true
+
+- name: Ensure nginx is installed
+  ansible.builtin.apt:
+    name: nginx
     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/main/repo_setup.yaml

@@ -1,45 +0,0 @@
-- name: gather package facts
-  ansible.builtin.package_facts:
-    manager: apt
-
-- name: make sure `gnupg` package 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
-  ansible.builtin.get_url:
-    url: https://nginx.org/keys/nginx_signing.key
-    dest: /etc/apt/trusted.gpg.d/nginx.asc
-    mode: "0644"
-    owner: root
-    group: root
-  become: true
-
-- name: make sure 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
-  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
-  ansible.builtin.copy:
-    content: |
-      Package: *
-      Pin: origin nginx.org
-      Pin: release o=nginx
-      Pin-Priority: 900
-    dest: /etc/apt/preferences.d/99nginx
-    owner: root
-    group: root
-    mode: "0644"
-  become: true