fix(role): Clarify HashiCorp Vault kv secrets hierarchy example

Automatically generated by python-semantic-release

CHANGELOG.md

@@ -1,9 +1,13 @@
 # Change log
 
-Current version: 0.1.0
+Current version: 0.2.0
 
 <!--next-version-placeholder-->
 
+## v0.2.0 (2022-07-24)
+### Feature
+* **role:** Set and document defaults to make this ready to use out of the box ([`f3042db`](https://quico.space/quico-ansible/role_common_local-os-password/commit/f3042dbf7e69a9009524f2a4f06203a2a5342cf4))
+
 ## v0.1.0 (2022-07-24)
 ### Feature
 * **role:** Introduce Semantic Versioning a changelog ([`a84a113`](https://quico.space/quico-ansible/role_common_local-os-password/commit/a84a113ef749dc7c543f1b3995efe0e4194f7832))

README.md

@@ -1,3 +1,57 @@
 # role_common_local-os-password
 
-An Ansible role to change an operating system's local user password
+An Ansible role to change an operating system's local user password
+
+# Defaults
+
+This role requires variables defined in [defaults/main.yml](defaults/main.yml). Feel free to overwrite them as needed for your HashiCorp Vault setup for example in a `group_vars` or `host_vars` file.
+
+* `fqdn_reverse`: A variable that contains the reversed fully qualified domain name for each host with each dot (`.`) replaced by a slash (`/`). For `fully.qualified.domain.name` this variable will equal `name/domain/qualified/fully`. Consider this a suggestion for how to set up your HashiCorp Vault `kv` secrets hierarchy.
+
+* `local_os_password_vault_vars`: The variables you want extracted from your Vault instance, by default `['password', 'password_salt']` which contain the new password to set for the local account and a salt, respectively.
+
+* `local_os_password_vault_base`: The base path where all of `local_os_password_vault_vars` are located in Vault.
+
+* `local_os_password_vault_paths`: The product of both `local_os_password_vault_base` and `local_os_password_vault_vars` stored in a dictionary. This is what the role uses in its `vault_kv2_get` lookup.
+
+* `reset_password_for_account`: The account for which you'd like to change its local account password, defaults to `root`.
+
+# Use it
+
+In your `playbook.yml` call it like so:
+
+```
+- name: 'Awesome playbook'
+  hosts: all
+  roles:
+    - 'role_common_local-os-password'
+```
+
+# Output
+
+Ansible tasks output is for example:
+
+```
+...
+
+TASK [role_common_local-os-password : Get secrets] *************************************************
+ok: [fully.qualified.domain.name] => (item=None)
+ok: [fully.qualified.domain.name] => (item=None)
+ok: [fully.qualified.domain.name]
+
+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 [role_common_local-os-password : Set fact: New OS local account password] *********************
+ok: [fully.qualified.domain.name]
+
+TASK [role_common_local-os-password : Set local OS account password] *******************************
+ok: [fully.qualified.domain.name]
+
+...
+```

defaults/main.yml

@@ -0,0 +1,6 @@
+# role_common_local-os-password
+fqdn_reverse: '{{ inventory_hostname | split(".") | reverse | join("/") }}'
+local_os_password_vault_vars: ['password', 'password_salt']
+local_os_password_vault_base: '{{ fqdn_reverse }}/os/{{ reset_password_for_account }}'
+local_os_password_vault_paths: '{{ [local_os_password_vault_base + ''/''] | product(local_os_password_vault_vars) | map(''join'') | list }}'
+reset_password_for_account: 'root'