Why use HashiCorp Validated Designs?
HashiCorp Validated Designs (HVD) offer practitioners opinionated guidance for achieving production-grade deployments of Vault Enterprise. These designs are purpose-built for delivering foundational Vault use cases, with a baseline level of architectural and operational maturity. They draw on the field experiences of Solutions Engineers and Solutions Architects working with Vault Enterprise customers.
This Solution Design Guide provides customers with access to an opinionated reference architecture, including key design decisions and the rationale behind them. Where applicable, the guide identifies modular design components that customers can adjust to align with organizational and/or regulatory requirements without compromising the overall integrity of the implementation. For customers deploying Vault to the cloud, Terraform modules are also included, which can automate large portions of the infrastructure provisioning and software installation process.
Audience
This document is intended primarily for practitioners (including platform, networking, identity, and Infosec teams) who want to deploy Vault Enterprise clusters on-premises or on cloud infrastructure.
After using the Solution Design Guide to successfully deploy your Vault Enterprise infrastructure, Vault operators should refer to Vault: Operating Guide for Adoption. Using the Operating Guide, Vault operators can learn how to integrate application platforms, configure machine and user access, centralize secrets, perform upgrades, and more.
Document structure
| Document section | Purpose |
|---|---|
| Architecture | Describes the components that make up this Validated Design for Vault Enterprise. For each component we will discuss their purpose within the architecture and detail low-level requirements and recommendations (configurations, sizing, etc.). |
| Detailed design | Expands on the architecture to provide more detail on each component of the architecture. Carefully review this section to identify all technical and personnel requirements before moving on to implementation. |
| Deploying Vault using Terraform | Installation of Vault Enterprise using our validated Terraform modules. |
| Deploying Vault Enterprise in a private datacenter | Describes more general steps to install Vault Enterprise as well as the supporting infrastructure detailed in the previous sections. |
Supported platforms and versions
As of HVD Document Version 1.0, the Solution Design Guide supports deploying Vault Enterprise on the following compute platforms:
- AWS on EC2 instances
- Azure on VM instances
- GCP on GCE
- Bare-metal or VM-based servers in a private datacenter
This guide applies to Vault Enterprise versions vault_1.17.3+ent and later, and can be downloaded from HashiCorp Releases(opens in new tab) or the HashiCorp Developer page(opens in new tab).
While Vault Enterprise is officially supported for a number of different operating systems and processor architectures, this guide primarily uses linux/amd64 within its examples, unless otherwise specified. Please note that HSM support(opens in new tab) is currently only available for linux/amd64 platforms.
Definitions and concepts
This documentation intentionally uses technology agnostic terminology. However, there are some terms which do not translate perfectly between providers. The following are the definitions of terms this document uses:
| Term | Definition |
|---|---|
| Availability zone | An availability zone (or AZ) is a single network failure domain that hosts part or all of a Vault cluster. Examples of availability zones include: - an individual datacenter. - an air-gapped rack in a datacenter. - an availability zone in AWS or Azure. - a zone in GCP. |
| Region | A physical location in a distinct geographic area containing one or more availability zones. |
| Active node | The node in a Vault cluster that services write requests. |
| Standby node | Nodes that forward write requests to the active node. They also service read requests in high availability mode. Standby nodes vote to elect a new active node if the current one is unavailable after an interval threshold. |
| Quorum | Quorum consists of a majority of voting nodes in a Vault cluster: (N+1)/2, where N = the total number of voting nodes. For example, if there are 3 voting nodes, we would need 2 nodes to form a quorum.Quorum ensures the integrity and consistency of secrets data. If a quorum of nodes is unavailable for any reason, the cluster becomes unavailable, meaning no client requests can be processed until quorum is once again achieved. |
| Redundancy zone (RZ) | Redundancy zones(opens in new tab) are a feature of integrated storage Autopilot. A redundancy zone consists of non-voting standby nodes deployed alongside voting nodes in a Vault cluster on a per-availability zone basis. This provides additional horizontal read scalability as well as increased fault tolerance for the Vault cluster. If a voting node fails, the non-voting node will be automatically promoted to a voter to preserve quorum. |
| Disaster Recovery (DR) Replication | An advanced topology in which a secondary Vault Enterprise cluster replicates all data from its DR primary cluster. The DR secondary cluster does not service any requests from clients, but can be quickly promoted to an active cluster during a service interruption to the primary. They are warm standby clusters. |
| Cluster | Multiple Vault servers (nodes) operating together in a high-availability mode. Each node contains an identical set of replicated data storage. |
| Seal (mechanism) | The seal is a way of protecting the cryptographic material that Vault uses to encrypt and decrypt data. Depending on the mechanism for sealing Vault, the service returns an unseal key or recovery key to the operator. These keys are sharded by Shamir's secret sharing algorithm to ensure no single actor has access to all of the unseal or recovery material. The unseal or recovery key is reconstituted by entering a minimum threshold of key shares. Although the behavior of unseal keys and recovery keys differ, they both service the same ultimate goal: regaining access to the Vault cluster. |
| Unsealing/Sealing (process) | Unsealing: Vault's storage is encrypted. The ability of the service to decrypt its secrets data is based on having the encryption key in memory. Vault is able to read the encryption key into memory indirectly by reconstituting the unseal/recovery key from key shares. The unseal key decrypts the encryption key. Sealing: When Vault deletes the encryption key from memory, the service is incapable of reading the encrypted storage. Vault will be unable to read it until a threshold of key shares reconstitutes the unseal/recovery key to decrypt the encryption key. |
| Tokens | Tokens are the core method for authentication within Vault. |
| Leases | An object in Vault containing metadata about a token's time duration and renewability. Vault creates leases for service tokens and dynamic secrets. Once the lease expires, Vault automatically revokes the data, and the consumer of the secret can no longer be certain that it is valid. For more information, see the HashiCorp Documentation on Leases(opens in new tab). |
Organizational requirements
Most tasks within this guide will be owned by a single team, which is responsible for deploying shared infrastructure services. This is sometimes referred to as a platform team. However, a successful deployment of Vault Enterprise requires collaboration across various functions within the organization. The platform team may interface with various other teams, such as networking, information security, or identity teams, to perform tasks such as allocating IP space, managing certificates, defining identity roles and permissions, or overseeing DNS hosted zones and records. In cases where the infrastructure resides on a public cloud, these functions might converge under a unified cloud team.
The primary platform team should thoroughly review this Solutions Design Guide in order to identify any teams they may be dependent on or may require approval from for the tasks required as part of the deployment. The platform team should appoint a project lead to oversee the deployment process and ensure effective communication with dependent teams and functions.