Skip to content
Search

HashiCorp Vault

lastmod 2026-02-19created 2022-03-2329 edits

Vault is a tool for storing and managing secrets, that is, passwords, API keys, tokens, and other information that must not be made public.

Secure, store and tightly control access to tokens, passwords, certificates, encryption keys for protecting secrets and other sensitive data using a UI, CLI, or HTTP API.

Intro

Development involves quite a lot of secrets. Here, a secret means information that an application or similar needs to use but that must not be exposed externally. Typical examples are database account names and passwords (the URL is usually blocked from access, but even that does no good if made public), access tokens if you use external APIs, and SSH private keys for accessing servers. At least in the projects I have experienced, passwords and access tokens were mostly hard-coded into the source code, SSH keys were simply stored on developers' PCs (trusting them to manage them well), and account information needed for development or work was mostly managed in Google Sheets and the like.

Think of it as a tool that manages this kind of information. For account information, there are solutions like 1Password besides Google Sheets, so let's talk only about the development side here. Managing things this way usually isn't a big problem. Hard-coding in code makes it easy to use, and when it changes you just update it, but source code is harder to manage than you'd think. Even setting aside accidental uploads to public repositories such as GitHub, source code is mostly stored on the PCs of the developers involved, and even setting aside malicious leaks, it is hard to control every individual's PC, so it may leak, and because it is hard-coded in the code, changing these secrets is not easy either.

This is fine if the project is simple, but as the number of projects and people grows, the problem gets bigger. Think of Vault as a tool that safely stores and manages this information. Put more simply, it means storing this information in Vault and having applications or servers fetch and use it. In recent work I came to think such a solution was needed, so I started looking into it in earnest.

Docker example 

docker run --rm -it --cap-add=IPC_LOCK -p 8200:8200 -e 'VAULT_DEV_ROOT_TOKEN_ID=myroot' -e 'VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:1234' hashicorp/vault

Among the options, --cap-add=IPC_LOCK is strongly recommended. It locks IPC (Inter Process Communication) memory, protecting against memory swap attacks.

Compose example

docker-compose.yml: 

version: '3.8'

services:
  vault:
    image: hashicorp/vault:latest
    container_name: vault
    restart: unless-stopped
    ports:
      - "8200:8200"
    environment:
      VAULT_ADDR: "http://0.0.0.0:8200"
      VAULT_API_ADDR: "http://0.0.0.0:8200"
    cap_add:
      - IPC_LOCK
    volumes:
      - ./vault/config:/vault/config
      - ./vault/data:/vault/data
      - ./vault/logs:/vault/logs
    command: vault server -config=/vault/config/vault.hcl

vault/config/vault.hcl: 

ui = true

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 1  # 프로덕션에서는 TLS 활성화 권장
}

storage "file" {
  path = "/vault/data"
}

api_addr = "http://0.0.0.0:8200"

Running and initialization: 

# 디렉토리 생성
mkdir -p vault/{config,data,logs}

# 실행
docker compose up -d

# 초기화 (최초 1회)
docker exec -it vault vault operator init

# Key 5개와 Root Token이 출력됨 → 반드시 안전한 곳에 보관!

# Unseal (Key 5개 중 3개 입력 필요)
docker exec -it vault vault operator unseal <key1>
docker exec -it vault vault operator unseal <key2>
docker exec -it vault vault operator unseal <key3>

After that, the Web UI is accessible at http://localhost:8200.

Notes:

  • IPC_LOCK: a required capability that keeps Vault from swapping memory out
  • Unseal: Vault needs to be unsealed every time it restarts. To automate this, you can configure auto-unseal (Transit, AWS KMS, etc.)
  • TLS: in production, set tls_disable = 0; certificate configuration is required
  • Storage backend: Consul, Raft, PostgreSQL, etc. can also be used instead of file. Raft is recommended if you need HA

IPC_LOCK

IPC_LOCK is a capability that allows a container to use the Linux kernel's memory locking (mlock) feature.

Vault keeps sensitive data such as secret keys and tokens in memory, and when memory runs low, the OS may write this data to the swap area (disk). Once written to disk, it may remain unencrypted, which creates a security risk.

Granting IPC_LOCK lets Vault use the mlock() system call to pin its memory pages in RAM so that they never get swapped out.

If this capability is not granted, the server will only start if disable_mlock = true is specified in the Vault configuration. However, this weakens security, so it is not recommended in production.

HCP Vault Tutorials

HCP Vault Secrets

HashiCorp Cloud Platform (HCP) Vault Secrets is a secret lifecycle management solution that centralizes secrets and lets applications access them in their workflows. Clients (systems or users) can interact with HCP Vault Secrets using the command-line interface (CLI), the HCP portal, or the API.

HCP Vault vs. HCP Vault Secrets

HCP Vault
Provides single-tenant, dedicated Vault Enterprise clusters that can be deployed across various public cloud providers and regions. HCP manages provisioning, operation, and maintenance of the clusters, giving organizations the flexibility to establish consistent identity-based access workflows for their secret access and data protection needs.
HCP Vault Secrets
A multi-tenant SaaS platform that gives teams a secure, simplified workflow for secret lifecycle management. Easily manage and integrate secrets wherever they are needed across applications and infrastructure.

CURL Example

Generate Service Principal key

The Client_ID and Client_Secret associated with an HCP service principal are used for human access to the HCP API from computers, applications, or system services. The service principal was created successfully! Copy the client secret. You won't be able to retrieve it later. 

export HCP_CLIENT_ID=...
export HCP_CLIENT_SECRET=...

Generate the API Token

The HCP API requires a valid access token. After authenticating to HCP as a user or a service principal, you can retrieve a short-lived Access Token to call the HCP API. 

HCP_API_TOKEN=$(curl --location "https://auth.idp.hashicorp.com/oauth2/token" \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "client_id=$HCP_CLIENT_ID" \
    --data-urlencode "client_secret=$HCP_CLIENT_SECRET" \
    --data-urlencode "grant_type=client_credentials" \
    --data-urlencode "audience=https://api.hashicorp.cloud" | jq -r .access_token)

When sending the content as JSON: 

HCP_API_TOKEN=$(curl --location 'https://auth.hashicorp.com/oauth/token' \
  --header 'content-type: application/json' \
  --data '{
  "audience": "https://api.hashicorp.cloud",
  "grant_type": "client_credentials",
  "client_id": "'$HCP_CLIENT_ID'",
  "client_secret": "'$HCP_CLIENT_SECRET'"
  }' | jq -r .access_token)

Read your secrets 

export HCP_ORG_ID=...
export HCP_PROJ_ID=...
export HCP_APP_NAME=...

API_PREFIX="https://api.cloud.hashicorp.com/secrets/2023-06-13/organizations"

curl \
--location "$API_PREFIX/$HCP_ORG_ID/projects/$HCP_PROJ_ID/apps/$HCP_APP_NAME/open" \
--request GET \
--header "Authorization: Bearer $HCP_API_TOKEN" | jq

vlt client in docker 

FROM ubuntu
RUN apt update && apt install -y --no-install-recommends gpg curl lsb-release ca-certificates openssl
RUN curl -fsSL https://apt.releases.hashicorp.com/gpg | gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
RUN echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/hashicorp.list
RUN apt update && apt install vlt -y --no-install-recommends
RUN apt clean && rm -rf /var/lib/apt/lists/*

Build: 

docker build --tag ubuntu-with-vlt .

Run: 

docker run --rm -it ubuntu-with-vlt ...

Initializing via the WebUI

The first screen you see when accessing the API after starting the server: 

Let's set up the initial set of root keys that you will need in case of an emergency.

Key shares
[ ]
The number of key shares to split the root key into

Key threshold
[ ]
The number of key shares required to reconstruct the root key
Vault initialization - Shamir's Secret Sharing
Vault does not store the master key whole; it splits it into multiple pieces using the Shamir's Secret Sharing algorithm.
Key shares
How many pieces to split the master key into
Key threshold
How many of those pieces must be gathered to unseal Vault

For example, with shares=5 and threshold=3, five key pieces are generated, and any three of them are enough to open Vault.

Scenario

Key shares

Key threshold

Personal/testing

1

1

Small team

3

2

Production (default)

5

3

Why do it this way

The key point is eliminating a single point of failure. If one person holds all the keys and that person leaves the company or loses the keys, it's over. Conversely, if the keys are distributed among several people, recovery is possible even if some are lost as long as the threshold number are gathered, and no single person can maliciously open Vault alone.

Practical advice

For personal self-hosting, 1 / 1 is fine. You manage it alone anyway.

Be sure to back up the Unseal Key and Root Token shown after initialization somewhere safe. If you lose them, there is no way to access Vault's data.

Vault enters the sealed state every time it restarts, so you have to enter the unseal key each time. If this is tedious, you can later consider configuring Auto Unseal (Transit, AWS KMS, etc.).

Initializing via the CLI

Connect to the container in question and use the following commands: 

# 초기화 (최초 1회)
docker exec -it vault vault operator init

# Key 5개와 Root Token이 출력됨 → 반드시 안전한 곳에 보관!

# Unseal (Key 5개 중 3개 입력 필요)
docker exec -it vault vault operator unseal <key1>
docker exec -it vault vault operator unseal <key2>
docker exec -it vault vault operator unseal <key3>

Troubleshooting

Cannot delete service principal 

You cannot delete service principal Desktop since it has 1 key(s) active within it. Please delete the active keys in this service principal to proceed with deletion.

It's hard to spot, but follow these steps.

  1. Log in at https://portal.cloud.hashicorp.com/sign-in
  2. Click 'Access control (IAM)' in the left menu
  3. Click 'Service principals' in the left menu
  4. Select the Service principals you want to remove
  5. Click 'Keys' in the left menu
  6. Remove all existing keys, then remove the Service principals.

See also

Favorite site

author Zer0 sitemap