From b27aa8541af3205a41674bf51fd084788389c164 Mon Sep 17 00:00:00 2001
From: Ryan Gniadek <ryan@gniadek.net>
Date: Thu, 19 Sep 2024 16:29:32 -0400
Subject: [PATCH] Added an example credential with HashiCorp Vault source
 (#909)

* Added an example credential with HashiCorp Vault source

* Added additional information on source_credential and metadata fields

* Added HashiCorp Vault example to credentials README
---
 roles/credential_input_sources/README.md | 27 ++++++++++++++++++++++--
 roles/credentials/README.md              |  9 ++++++++
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/roles/credential_input_sources/README.md b/roles/credential_input_sources/README.md
index ad0975121..faf6318a5 100644
--- a/roles/credential_input_sources/README.md
+++ b/roles/credential_input_sources/README.md
@@ -78,12 +78,12 @@ This also speeds up the overall role.
 |:---:|:---:|:---:|:---:|:---:|
 |`target_credential`|""|yes|str|Name of credential to have the input source applied|
 |`input_field_name`|""|yes|str|Name of field which will be written by the input source|
-|`source_credential`|""|no|str|Name of the source credential which points to a credential source|
+|`source_credential`|""|no|str|Name of the source credential which points to an external secret lookup credential |
 |`metadata`|""|no|dict|The metadata applied to the source.|
 |`description`|""|no|str|Description to use for the credential input source.|
 |`state`|`present`|no|str|Desired state of the resource.|
 
-For further details on fields see <https://docs.ansible.com/automation-controller/latest/html/userguide/credential_plugins.html>
+For further details on fields see <https://docs.ansible.com/automation-controller/latest/html/userguide/credential_plugins.html>. The input accepted by the `metadata` field will differ depending on the credential plugin being used.
 
 ### Standard Credential Input Source Data Structure
 
@@ -101,6 +101,19 @@ For further details on fields see <https://docs.ansible.com/automation-controlle
           "object_query_format": "Exact"
         },
         "description": "Fill the gitlab credential from CyberArk"
+      },
+      {
+        "source_credential": "hashivault",
+        "target_credential": "gitlab",
+        "input_field_name": "password",
+        "metadata": {
+          "secret_backend": "mykv",
+          "secret_path": "vault/path/to/gitlab/secret",
+          "auth_path": "approle",
+          "secret_key": "GITLAB_PASSWORD_FROM_HASHI_VAULT",
+          "secret_version": "v2"
+        },
+        "description": "Fill the gitlab credential from HashiCorp Vault"
       }
     ]
 }
@@ -111,6 +124,16 @@ For further details on fields see <https://docs.ansible.com/automation-controlle
 ```yaml
 ---
 controller_credential_input_sources:
+  - source_credential: hashivault
+    target_credential: gitlab
+    input_field_name: password
+    metadata:
+      secret_backend: mykv
+      secret_path: vault/path/to/gitlab/secret
+      auth_path: approle
+      secret_key: GITLAB_PASSWORD_FROM_HASHI_VAULT
+      secret_version
+    description: Fill the gitlab credential from HashiCorp Vault
   - source_credential: cyberark
     target_credential: gitlab
     input_field_name: password
diff --git a/roles/credentials/README.md b/roles/credentials/README.md
index 1972161e3..d315b86dc 100644
--- a/roles/credentials/README.md
+++ b/roles/credentials/README.md
@@ -126,6 +126,15 @@ controller_credentials:
   inputs:
     username: person
     password: password
+- name: hashivault
+  description: HashiCorp Vault Secret Lookup example using token auth
+  organization: Default
+  credential_type: HashiCorp Vault Secret Lookup
+  inputs:
+    url: https://vault.example.com:8243
+    token: token
+    cacert: "{{ lookup('ansible.builtin.file', '/path/to/ca-certificates.crt') }}"
+    api_version: v2
 - name: localuser
   description: Machine Credential example with become_method input
   credential_type: Machine