Having spent considerable time implementing Vault in production environments, I've noticed a persistent point of confusion for newcomers: the conceptual model of the 'path'. It's a critical abstraction, and misunderstanding it leads to misconfigured policies and security gaps. It is not a filesystem directory, though the hierarchical syntax is deliberately evocative of one. It is, more accurately, a unified namespace for addressing all of Vault's secrets, authentication methods, and configuration—a key organizational and security primitive.
Think of a Vault path as a unique address or endpoint within Vault's internal API. Every operation in Vault—reading a secret, enabling an auth method, configuring a database connection—happens at a specific path. The structure `engine_type/optional_subpath/secret_name` is a convention for organizing these endpoints, not for storing files. For instance, when you enable the Key/Value v2 secrets engine at the mount point `secret/`, the path `secret/data/myapp/database` does not correspond to a folder `myapp` containing a file `database`. Instead, it is the API endpoint where the *data* for that specific secret is stored and accessed. The `data` component is itself a part of the v2 API path structure, not a directory.
This abstraction is fundamental to Vault's security model because policies grant or deny permissions based on path patterns. You cannot understand policy writing without internalizing this. Consider the following policy snippet:
```hcl
path "secret/data/myapp/*" {
capabilities = ["read", "list"]
}
path "secret/metadata/myapp/*" {
capabilities = ["list"]
}
path "aws/creds/deploy-role" {
capabilities = ["read"]
}
```
Here, we are not granting access to "files under a folder." We are granting the `read` capability for the API endpoint that generates dynamic AWS credentials via the `aws` secrets engine mounted at `aws/`, and `read` on the API endpoint for secrets stored under the `myapp` namespace within the `secret/` KV v2 engine. The `metadata` path is a separate API endpoint for managing secret metadata, further illustrating that these are distinct operational interfaces.
The practical implications are significant. If you mount the same KV v2 secrets engine at two different mount points, like `team-a/` and `team-b/`, the paths `team-a/data/config` and `team-b/data/config` are completely isolated API endpoints with their own data and potentially different policies governing access. This path-based namespace is what allows Vault to cleanly unify disparate backends (PKI, databases, SSH, transit) under a single policy and authentication framework. You manage access to the *function* (e.g., `pki/issue/domain`) via its path, not to a backend directly.
To solidify the distinction, remember: you interact with paths via the Vault CLI or API (`vault read`, `vault write`), not a filesystem driver. The hierarchy is logical, for organization and policy targeting. The next conceptual hurdle is often understanding how this path model interacts with the actual storage backend (Consul, Raft, etc.), but that's a topic for another post. Start by mapping every Vault operation you perform to its API path, and the model will quickly become clear.
-- alex