Add hashivault option as docker-compose optional container (#14161)

Co-authored-by: Sarabraj Singh <singh.sarabraj@gmail.com>

1 files changed, 44 insertions, 1 deletions

diff --git a/tools/docker-compose/README.md b/tools/docker-compose/README.md
index e071f33923..4670690672 100644
--- a/tools/docker-compose/README.md
+++ b/tools/docker-compose/README.md
@@ -303,7 +303,7 @@ To bring up a 1 node AWX + minikube that is accessible from AWX run the followin
 Start minikube
 
 ```bash
-(host)$minikube start --cpus=4  --memory=8g --addons=ingress`
+(host)$minikube start --cpus=4  --memory=8g --addons=ingress
 ```
 
 Start AWX
@@ -497,6 +497,49 @@ ansible-playbook tools/docker-compose/ansible/plumb_tacacs.yml
 
 Once the playbook is done running tacacs+ should now be setup in your development environment. This server has the accounts listed on https://hub.docker.com/r/dchidell/docker-tacacs
 
+### HashiVault Integration
+
+Run a HashiVault container alongside of AWX.
+
+```bash
+VAULT=true make docker-compose
+```
+
+Go to `http://localhost:1234` sign in with method "Token".
+
+You can find the generated token at `tools/docker-compose/_sources/secrets/vault_password.yml`,
+this is a root token, and it should not need a corresponding username.
+Note that the token will be different on each restart, as it is re-generated by the playbook,
+and the container does not use a persistent volume.
+
+As a demo, click "Enable new engine +", click "KV" and Next.
+In the "Path" enter "my_engine" and click "Enable Engine".
+Click on the name of the engine and then "Create secret +".
+In the "Path for this secret" enter "my_root/my_folder" and in the "Secret Data" put "my_key" for key and **"my_value"** for value.
+
+Then go to AWX and create a new HashiVault credential with the generated token.
+Then go to any other arbitrary credential and click the key icon on an input to use a credential lookup plugin.
+In the "External Secret Management System" menu, first select the already-created HashiVault credential.
+
+Then in the "Metadata" menu, put in this data which is important for the integration:
+ - Name of Secret Backend: "my_engine"
+ - Path to Secret: "data/my_root/my_folder"
+ - Key Name: "my_key"
+
+After this, apply the credential to a job template that writes the data in a debug task.
+In the job output, you should see **my_value**.
+
+(NOTE: the "arbitrary credential" could be a new custom credential type that injects to extra vars
+which is used in corresponding playbook that prints hostvars, but this doc assumes you know how to do that)
+
+The extremely non-obvious input is the fact that the fact prefixes "data/" unexpectedly.
+This was discovered by inspecting the secret with the vault CLI, which may help with future troubleshooting.
+
+```
+docker exec -it -e VAULT_TOKEN=<token> tools_vault_1 vault kv get --address=http://127.0.0.1:1234 my_engine/my_root/my_folder
+```
+
+
 ### Prometheus and Grafana integration
 
 See docs at https://github.com/ansible/awx/blob/devel/tools/grafana/README.md