HashiCorp Vault: Secrets Management for Infrastructure Teams

What HashiCorp Vault solves, and for whom

The README frames the problem plainly: a modern system needs database credentials, API keys for external services and credentials for service-to-service communication, and tracking who reads what is already difficult and platform-specific. Adding key rolling, secure storage and audit logging on top of that is described as almost impossible without a custom solution. Vault is that custom solution, packaged.

The project is aimed at platform and security engineers, not at application developers who just want a config value at startup. The README lists five capabilities: secure secret storage, dynamic secrets, data encryption without storing the data, leasing and renewal, and revocation. Dynamic secrets are the distinguishing one. Instead of handing out a long-lived database password, Vault generates credentials on demand for systems such as AWS or SQL databases, and revokes them when the lease expires. The README's own example is an application asking Vault for S3 access and receiving an AWS keypair with valid permissions, generated at that moment.

That model only pays off when the consuming systems can tolerate short-lived credentials and re-fetch them. A cron job that reads a password once and runs for a week gets much less from Vault than a service that authenticates on each deployment.

How the Vault architecture actually moves a secret

The repository layout shows the shape of the system. The vault/ directory holds the core, physical/ holds storage backends, builtin/ holds the secret engines and auth methods, api/ and sdk/ are the two libraries the README says are published for import by other projects, and shamir/ holds the secret sharing implementation used for the unseal process.

The data flow for a stored secret runs like this: a client authenticates against an auth method, receives a token, and uses that token against a secret engine mounted at a path. The engine writes the value through the barrier, which encrypts it before it reaches the physical storage backend. The README notes Vault can write to disk or Consul, among others. Because encryption happens above the storage layer, reading the raw backend files is not enough to read the secrets.

For dynamic secrets the flow inverts. The client asks the engine for credentials, the engine talks to the target system using its own configured credentials, creates a user or key, returns it with a lease attached, and revokes it when the lease ends. Revocation is described as working on trees as well as single secrets, so you can revoke everything a particular user read, or every secret of a given type. That is the mechanism that makes key rolling and intrusion lockdown tractable rather than manual.

Installing Vault and reading your first secret

The README points to developer.hashicorp.com/vault/docs for documentation and the Getting Started guides for first steps, and it does not give a package installation command. What it does give is the developer build path from source. Vault needs Go installed, with GOPATH and GOBIN set, and the repository should be cloned outside the GOPATH because the project uses Go modules. The go.mod file in the repository declares go 1.26.4.

Bootstrap the build tools, then compile a development binary:

make bootstrap
make dev
bin/vault

The README states that make dev puts the Vault binary in both bin/ and $GOPATH/bin. To build with the web UI included, the documented target is make static-dist dev-ui, which places the binary in the same two locations.

Running the test suite takes one command, and the README notes it requires Docker to be installed. A zero exit status means everything is working:

make test

To run tests for a single package rather than the whole tree, pass the TEST variable. The README gives the vault package as the example:

make test TEST=./vault

There is a documented troubleshooting case. If the build fails with could not read Username for 'https://github.com', the README says to rewrite the URL so git uses SSH instead:

git config --global --add url."[email protected]:".insteadOf "https://github.com/"

Note the scope of what is documented here. The README covers building and testing Vault from source. It does not describe initialising a server, unsealing it, or writing a secret, and it does not cover installing a released binary. Those steps live on the documentation site, not in this file. Anyone expecting a single install command in the repository will not find one.

Where Vault is the wrong tool

The operational weight is the first limitation, and it is structural rather than a bug. The shamir/ directory exists because a Vault server starts sealed and needs a quorum of key holders to unseal it. That is a deliberate design choice, and it means a restart of the Vault process is not a routine event unless you have automated unsealing. Teams that treat Vault like a stateless service tend to discover this at the worst possible moment.

Vault is also a poor fit when the secret does not change and nobody needs to audit the read. If a single application reads one API key from an environment variable at boot, introducing Vault adds a network dependency, an auth method to configure, a token lifecycle to manage and a service that must be available before the application can start. The README's own justification is about many secrets, many consumers and the difficulty of knowing who accessed what. Remove those conditions and the case weakens considerably.

There is a dependency wrinkle visible in go.mod that is worth knowing about before you build. The file carries replace directives, including one that swaps 99designs/keyring for a fork because of a bug that leaves zombie dbus-daemon processes, and another that substitutes a fork of triton-go to drop a jackc/pgx/v3 dependency the comment says has CVEs that will never be fixed. These are pragmatic choices, but they mean the dependency graph is not the plain upstream one, and a build from source inherits them.

Vault compared with a Kubernetes-native secrets store

The nearest alternative for many teams is Kubernetes Secrets combined with a controller that syncs from an external store, or a cloud provider's managed secrets service. The difference in approach is where the credential comes from. A Kubernetes Secret is a stored object: someone or something puts a value in, and it stays there until it is replaced. Vault's dynamic secrets are generated per request with a lease, and the README states Vault revokes them automatically when the lease is up.

That distinction has consequences. With stored secrets, rotation is a job you schedule and a failure you debug when a consumer keeps the old value. With leases, rotation is the default and the failure mode is a consumer that cannot renew. Vault also covers encryption as a service, so an application can send plaintext to Vault and get ciphertext back without Vault storing it, which a Kubernetes Secret cannot do at all.

The cost side runs the other way. A Kubernetes Secret has no separate control plane to run, no unseal ceremony and no upgrade path of its own. If your workloads all live in one cluster and your secrets are few, the managed or native option is less machinery for the same outcome. Vault earns its place when credentials span clouds, databases and legacy systems that Kubernetes does not manage.

Upgrades, licensing and what to check before adopting

The repository ships CHANGELOG.md alongside CHANGELOG-pre-v1.10.md, CHANGELOG-v0.md and CHANGELOG-v1.10-v1.15.md, which tells you the changelog is split by version range rather than kept in one file. When you plan an upgrade, read the file covering your current range and the current CHANGELOG.md, not just the newest entries. Recent releases listed for the repository are v2.0.2, v2.0.3 and v2.0.4, the last pushed on 2026-08-04.

Licensing needs attention rather than assumption. The repository's licence field is reported as NOASSERTION, which means the automated classification did not resolve it to a standard identifier. The Dockerfile in the repository carries the header Copyright IBM Corp. 2016, 2026 with SPDX-License-Identifier: BUSL-1.1, while the README links to a Vault Enterprise product page. The practical point is that the source tree is not uniformly under one permissive licence, and the terms that apply to a given build can differ. Read the LICENSE file and the headers on the components you intend to use, and get your own legal review. Nothing here is legal advice.

Upgrade cost is dominated by the storage and unseal path. Because secrets are encrypted above the physical backend, a storage migration is not a file copy. Because the server seals on restart, an upgrade is not a rolling deploy unless unsealing is automated. Budget for both before you pick a release.

Editorial conclusion

Adopt Vault if you already run infrastructure that needs centrally issued and revoked credentials, and you can staff the operational work of unsealing, upgrading and backing up the storage backend. Do not adopt it for a single application's config file, or if nobody owns the upgrade path between releases. Before committing, verify the licence terms for the exact build you intend to run, confirm which storage backend you will use, and read the upgrade notes for the release you are moving to, since the repository ships several changelog files split by version range.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes