Hey everyone. I'm relatively new to managing secrets in our data pipelines, and we've been evaluating HashiCorp Vault for storing things like BigQuery service account keys, database passwords, and Airflow connection strings.
I've been trying to set up a simple key-value engine and configure AppRole authentication for our ETL workers, but I'm finding the current docs really hard to follow. It feels like they assume you already know the whole system. For example, the jump from the basic "getting started" to the actual API structure for the KV engine leaves out a lot. I spent hours figuring out the difference between `v1` and `v2` mount paths in API calls just by trial and error.
```bash
# The tutorial shows this:
vault kv put secret/my-app my-key=my-value
# But when I tried to read it from a Python script, I had to use the full v1 path, and it wasn't clear:
# Should it be 'secret/data/my-app' or just 'secret/my-app'? The API docs list both.
```
Has anyone else felt this way lately? I'm nervous about misconfiguring something and breaking access for our production pipelines. Are there any safer, more beginner-friendly guides or patterns you'd recommend outside the official docs? Maybe a specific blog post or a known-good Terraform module for setting up a simple staging Vault?
I've also found the Vault API path distinction poorly documented, especially for developers writing automation. The issue stems from the CLI's `vault kv` helper abstracting the underlying API structure. The `vault kv put secret/my-app` command is actually writing to a v2 key-value mount (which has versioning and delete retention). The full API path for a v2 KV engine is indeed `/v1/secret/data/my-app`, while `/v1/secret/my-app` would be for a legacy v1 mount.
For your Python scripts, you should be using the full `/v1/secret/data/` path if you mounted the engine as version 2 (the default now). You can verify this with `vault secrets list -detailed`. The safe pattern is to always use the client library's `kv-v2` methods if available, which handle the path mapping internally.
Regarding broader documentation quality, I've observed a shift towards more fragmented, reference-style pages post their website redesign. The learning path isn't linear anymore. For AppRole specifically, I'd recommend the archived "Vault Best Practices" PDF from HashiCorp's older workshop materials, as it provides clearer workflow diagrams than the current web docs.
Test it yourself.