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

.gitignore

@@ -1 +1,3 @@
-.idea
+# ---> Ansible
+*.retry
+

CHANGELOG.md

@@ -0,0 +1,17 @@
+# Change log
+
+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))
+* **role:** Initial commit ([`dc9b87b`](https://quico.space/quico-ansible/role_common_local-os-password/commit/dc9b87ba880b58004201199f559b950ada939555))
+
+### Fix
+* **role:** Import dependency via 'git+https' protocol ([`8a1aa01`](https://quico.space/quico-ansible/role_common_local-os-password/commit/8a1aa0175efa6acf40f2c85dac45375adf0e92e1))

README.md

@@ -1,33 +1,22 @@
-[//]: # (SPDX-License-Identifier: MIT)
+# role_common_local-os-password
-# Role Name
 
-role-common-local_os_password
+An Ansible role to change an operating system's local user password
 
-# Description
+# Defaults
-
-Change an operating system's local user password.
-
-# Requirements
-
-Your target machines must be Linux.
-
-# Role Variables
 
 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. For `fully.qualified.domain.name` this variable will equal `name/domain/qualified/fully` which we then use in our HashiCorp Vault path to retrieve a password and password salt per host and per user.
+* `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.
-- `reset_password_for_account`: A list of usernames whose password we want changed. This defaults to:
-    ```
-    reset_password_for_account:
-      - 'build'
-      - 'root'
-    ```
 
-# Dependencies
+* `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.
 
-None.
+* `local_os_password_vault_base`: The base path where all of `local_os_password_vault_vars` are located in Vault.
 
-# Example Playbook
+* `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:
 
@@ -35,9 +24,34 @@ In your `playbook.yml` call it like so:
 - name: 'Awesome playbook'
   hosts: all
   roles:
-    - 'role-common-local_os_password'
+    - 'role_common_local-os-password'
 ```
 
-# License
+# Output
 
-MIT
+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

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

meta/main.yml

@@ -1,10 +1,14 @@
-# SPDX-License-Identifier: MIT
 galaxy_info:
   author: 'hygienic-books'
-  description: 'Change an operating system''s local user password'
+  description: 'An Ansible role to change an operating system''s local user password'
-  license: MIT
+  issue_tracker_url: 'https://quico.space/quico-ansible/role_common_local-os-password/issues'
-  min_ansible_version: 2.18.1
+  license: 'MIT'
+  min_ansible_version: '2.12.6'
+  platforms:
+    - name: 'EL'
+      versions:
+      - '7'
+      - '8'
   galaxy_tags:
-    - 'os'
     - 'password'
 dependencies: []

meta/requirements.yml

@@ -0,0 +1,2 @@
+- src: 'git+https://quico.space/quico-ansible/role_include_vault-check.git'
+  version: 'master'

tasks/40-local-os-password.yml

@@ -1,11 +1,33 @@
-# SPDX-License-Identifier: MIT
+- name: 'Get secrets'
-- name: 'Set local OS account password'
+  no_log: 'true'
   loop_control:
-    loop_var: 'account'
+    loop_var: 'server'
-    index_var: 'i'
+  with_community.hashi_vault.vault_kv2_get: '{{ local_os_password_vault_paths }}'
-    label: 'Set password for local account ''{{ account }}'''
+  ansible.builtin.set_fact:
-  loop: '{{ reset_password_for_account }}'
+    vault_data: '{{ vault_data | default({}) | combine (server.secret) }}'
+
+
+
+- name: 'If a secret is missing: Fail progress'
+  import_role:
+    name: 'role_include_vault-check'
+  vars:
+    - vault_check_base_path: '{{ local_os_password_vault_base }}'
+    - vault_check_inc_vault_data: '{{ vault_data }}'
+    - vault_check_fail_checks: '{{ local_os_password_vault_vars }}'
+
+
+
+- name: 'Set fact: New OS local account password'
+  no_log: 'true'
+  ansible.builtin.set_fact:
+    os_acc_pwd: '{{ vault_data.password }}'
+    os_acc_salt: '{{ vault_data.password_salt }}'
+
+
+
+- name: 'Set local OS account password'
   ansible.builtin.user:
-    name: '{{ account }}'
+    name: '{{ reset_password_for_account }}'
-    password: '{{ lookup(''hashi_vault'', ''secret=kv/data/settings/machines/'' + fqdn_reverse + ''/os/user/'' + account + '':password'') | string | password_hash(''sha512'', lookup(''hashi_vault'', ''secret=kv/data/settings/machines/'' + fqdn_reverse + ''/os/user/'' + account + '':password_salt'')) }}'
+    password: '{{ os_acc_pwd | string | password_hash(''sha512'', os_acc_salt) }}'
     update_password: 'always'

tasks/main.yml

@@ -1,2 +1 @@
-# SPDX-License-Identifier: MIT
 - import_tasks: '40-local-os-password.yml'