docs(role): Give example how to define defaults to make this role easier to use

Automatically generated by python-semantic-release

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Change log
+
+Current version: 0.1.1
+
+<!--next-version-placeholder-->
+
+## v0.1.1 (2022-07-24)
+### Fix
+* **galaxy:** Quote YAML values ([`cbe8d70`](https://quico.space/quico-ansible/role_include_vault-check/commit/cbe8d7094b1fd62d88a8b55b2331278b9cc97ac5))
+* **galaxy:** Add sensible content to 'meta/main.yml' ([`e223330`](https://quico.space/quico-ansible/role_include_vault-check/commit/e2233308c73b6e35a59a77197b9b61ea802ea59e))
+* **galaxy:** Add empty 'meta/main.yml', see if that's good enough to import via ansible-galaxy ([`9801af2`](https://quico.space/quico-ansible/role_include_vault-check/commit/9801af2c789a24f2bbdd5263a4f82116985bfbfa))
+
+### Documentation
+* **meta:** Prepare changelog file ([`2a49cdc`](https://quico.space/quico-ansible/role_include_vault-check/commit/2a49cdca39a1b7dd56585bdefacbdfecee915f1d))
+* **role:** Use example FQDN ([`e027a5e`](https://quico.space/quico-ansible/role_include_vault-check/commit/e027a5ef54e2737c40a958821545271478a9f774))
+* **role:** Add example Ansible task output ([`8691e6a`](https://quico.space/quico-ansible/role_include_vault-check/commit/8691e6a6a63db3b4332b6b26f911d244561f4747))
+* **role:** Bring tasks YAML file name in line with role name ([`a87b75f`](https://quico.space/quico-ansible/role_include_vault-check/commit/a87b75f2f0fc08636656bf26bce54d4852088ba8))
+* **role:** Bring tasks YAML file name in line with role name ([`8245542`](https://quico.space/quico-ansible/role_include_vault-check/commit/8245542ac032688ef75bde52c976df896bd4c4b3))
+* **role:** Consistently single-quote variables ([`dbe3c66`](https://quico.space/quico-ansible/role_include_vault-check/commit/dbe3c66a133381cb1c52dc3f1ace836d9c1f814e))
+* **role:** Prefix vars with role name ([`26cee49`](https://quico.space/quico-ansible/role_include_vault-check/commit/26cee49e98f01bf6bae790562b3308631438e04e))

README.md

@@ -23,7 +23,7 @@ In `requirements.yml` add:
   version: 'master'
 ```
 
-Now whenver you import `role` for example via `ansible-galaxy install ...` you'll automatically get this one downloaded as well. You can optionally leave out `version: 'master'` since this is the default version anyways, meaning the `role_include_vault-check` newest master commit. The `version:` attribute helps you pin a version, for example as `version: 'v1.0.0'` which will instead pull `role_include_vault-check` Git tag `v1.0.0`. Side note, this role follows the [Semantic Versioning](https://semver.org/) standard. A Git tag name `v1.0.0` refers to Semantic Version `1.0.0`.
+Now whenever you import `role` for example via `ansible-galaxy install ...` you'll automatically get this one downloaded as well. You can optionally leave out `version: 'master'` since this is the default version anyways, meaning the `role_include_vault-check` newest master commit. The `version:` attribute helps you pin a version, for example as `version: 'v1.0.0'` which will instead pull `role_include_vault-check` Git tag `v1.0.0`. Side note, this role follows the [Semantic Versioning](https://semver.org/) standard. A Git tag name `v1.0.0` refers to Semantic Version `1.0.0`.
 
 # Use it
 
@@ -79,6 +79,20 @@ In a real-world use case you'll likely first query HashiCorp Vault for key-value
 
 The `vault_kv2_get` lookup plug-in (see [vault_kv2_get lookup documentation](https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/vault_kv2_get_lookup.html)) iterates over variables you want loaded from Vault. For each iteration it stores the iteration's output in `loop_var: 'server'`. From that output we only really care about the `server.secret` dictionary. We append that to a `vault_data` dictionary which is first initialized as an empty dictionary and then expanded per iteration. When done `vault_data` contains key-values pair for all Vault variables.
 
+## Defining defaults
+
+Whereever you import this role you're most likely going to want to define the following variables in your role's `defaults/main.yml` file or at a similar location. Here `<role>` is a string you'll replace with the name of the role that imports `role_include_vault-check`.
+
+```
+<role>_vault_vars: ['password', 'password_salt']
+<role>_vault_base: '{{ fqdn_reverse }}/os/{{ reset_password_for_account }}'
+<role>_vault_paths: '{{ [<role>_vault_base + ''/''] | product(<role>_vault_vars) | map(''join'') | list }}'
+```
+
+Check out [Git repo quico.space/quico-ansible/role_common_local-os-password](https://quico.space/quico-ansible/role_common_local-os-password) for a reference of how to define `defaults/main.yml` and then to import this role.
+
+## Vault check
+
 The next step can be this `role_include_vault-check` to hard-fail in case a key turned out to have an empty value.
 
 ```
@@ -92,3 +106,22 @@ The next step can be this `role_include_vault-check` to hard-fail in case a key
 ```
 
 ## Output
+
+Ansible's task output will be for example:
+
+```
+TASK [...] ****************************************************************************************
+ok: ...
+
+TASK [role_include_vault-check : If a secret is missing: Fail progress] ***************************
+ok: [fully.qualified.domain.name] => (item=password) => {
+    "msg": "Vault has secret 'password' at 'name/domain/qualified/fully/os/root'"
+}
+ok: [fully.qualified.domain.name] => (item=password_salt) => {
+    "msg": "Vault has secret 'password_salt' at 'name/domain/qualified/fully/os/root'"
+}
+
+TASK [...] ****************************************************************************************
+ok: ...
+
+```

tasks/main.yml

@@ -1 +1 @@
-- import_tasks: '40-check-vault-var.yml'
+- import_tasks: '40-check-vault.yml'