Learn Vault - Prerequisites: Skills & Environment Setup

#Introduction

Welcome to the Learn Secret Management with HashiCorp Vault series! This series will take you from zero to production-ready with Vault: starting with the secret sprawl problem, the secret manager ecosystem comparison, Vault's internal architecture, secrets engines (KV, Dynamic DB, Transit, PKI), policies and authentication, all the way to integration with applications, Kubernetes, and CI/CD. But as the saying goes, "a strong house is built on a strong foundation." Before writing your first policy or reading a secret from Vault, there are a few foundational skills and tools you must have and prepare first.

Why are these prerequisites so important? Vault is essentially an API server whose job is to store and share secrets. It is configured through HCL/JSON files, operated via the CLI or HTTP API, and conceptually depends on an understanding of modern cryptography. In other words, if you are not yet familiar with the basics of the Linux CLI, encryption and hashing concepts, and JSON data formats, your learning journey will stall at every step. Imagine wanting to be a great cashier manager without knowing how to count money — no matter how good the system is, it is still hard to trust.

Episode 0 serves as your roadmap to make sure you are all ready. We will cover three fundamental skills (Linux CLI, basic cryptography concepts, and an understanding of REST API & JSON), prepare all the software you need, and finish with installing the Vault CLI, running a Vault server in two modes, and setting up its environment variables. Once this episode is complete, you will be fully ready to move on to episode 1, which covers why Vault is needed.

#Foundational Skills You Must Have

Let's start with skills. Without these, no matter how sophisticated the tools you set up, they will be useless. Here are the three skill pillars you should master at least at a basic level.

#Linux & CLI Basics

Vault was born and grew up in the Linux/Unix ecosystem. The majority of its real-world usage — especially on production servers, CI/CD pipelines, and containers — runs on Linux. That is why the ability to operate Linux through the CLI (Command Line Interface) is a must.

What do you need to master?

1. Navigation & file management. You should be comfortable moving between directories, viewing contents, and creating, copying, and deleting files. This is the most basic ability you will use every day, including when placing your Vault configuration file config.hcl.

Navigation & file management

pwd                        # print current working directory
ls -la                     # list directory contents (including hidden files)
cd ~/lab-vault             # change to project directory
mkdir -p vault/config      # create nested directories
cp config.hcl backup/      # copy a file

2. Reading and processing text. Vault configuration files are plain text, and when debugging we often have to filter long log output. You'll need to know commands like cat, less, grep, sed, and cut.

3. File permissions (chmod & chown). Vault is very sensitive to file permissions. For example, an unseal key file or a config.hcl with overly permissive permissions is a real security risk. Understand the r (read), w (write), and x (execute) concepts for the three groups: owner, group, and others.

4. Package manager. You should be able to install software through your distro's package manager, because it is the easiest way to install the Vault CLI. On Ubuntu/Debian use apt, on Fedora/RHEL use dnf, and on macOS use brew.

#Basic Cryptography Concepts

Vault is a cryptographic tool. To understand how Vault stores, protects, and shares secrets, you must understand the following four cryptographic foundations. This isn't advanced math — just understand the what, why, and when of each one.

Here's an analogy: symmetric encryption is like a padlocked safe — one key to open and close it. Asymmetric encryption is like a public mailbox: anyone can drop in a letter (public key), but only you with your special key can open it (private key). Hashing isn't a key at all — it's like a meat grinder: from meat (input) you always get ground meat (digest), but from ground meat it's impossible to restore the original whole piece.

Why do these concepts matter for Vault?

• Symmetric encryption is used by Vault to encrypt all data before writing it to the storage backend. So Vault storage is like a layered safe: the data is encrypted, and the encryption key itself is also protected.
• SHA-256 hashing is used in Shamir's Secret Sharing to split the master key into unseal keys (we cover this thoroughly in episode 3).
• Key management is Vault's entire raison d'être — "where is the key stored?" is the most expensive security question in modern IT.

#Understanding REST API & JSON

This may be the most underrated skill, yet it is the most decisive. Every interaction with Vault — whether via CLI, Web UI, or SDK — is ultimately an HTTP request to Vault's REST API. The command vault kv get secret/api is nothing more than a GET /v1/secret/data/api call under the hood.

Here's a clear example. These two commands produce identical results:

# The CLI is just a wrapper around the HTTP API
vault kv get secret/api/database

# curl is far more explicit about what's happening
curl \
  --header "X-Vault-Token: hvs.xxx" \
  --request GET \
  "http://127.0.0.1:8200/v1/secret/data/api/database"

That is why you need to understand a few basics:

• HTTP Methods: GET to read, POST/PUT to write, DELETE to delete, LIST to list.
• Status codes: 200 OK success, 403 forbidden (policy denied), 404 not found, 429 rate limited.
• JSON structure: Vault returns nested responses wrapped in an envelope { "data": { ... } }. You should be comfortable reading and manipulating JSON, for example with jq.

{
  "request_id": "3f4a5b6c-7d8e-4f90-a1b2-c3d4e5f60718",
  "lease_id": "",
  "renewable": false,
  "data": {
    "data": {
      "password": "S3cret!Passw0rd"
    },
    "metadata": {
      "created_time": "2026-08-02T10:00:00Z",
      "version": 1
    }
  }
}

#Software & Tools to Prepare

Now that the skills are covered, it's time to prepare the tools. Here's the full list:

#Installing the Vault CLI

Vault is a single binary — no special runtime, no extra dependencies. This is one reason Vault is so easy to distribute. HashiCorp provides official repos for nearly every Linux distro, macOS, and Windows.

# Ubuntu / Debian
sudo apt-get update && sudo apt-get install -y gnupg software-properties-common
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install vault

# RHEL / Fedora / Rocky
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
sudo dnf -y install vault

# macOS (Homebrew)
brew tap hashicorp/tap
brew install hashicorp/tap/vault

# Alternative: no binary install, just use the official image
docker pull hashicorp/vault:latest

For Windows users, the most recommended option if you're learning DevOps is to use WSL2 — because every command in this series is written in Linux style. Alternative: download the binary from releases.hashicorp.com and extract it into PATH.

#Verifying the Installation

Once installed, verify with vault --version. The correct output should show the Vault version and its build architecture.

vault --version
Vault v1.18.3 (0b7b0a3a5fca62b0f1f2d6f77fca2a94fae1f4f4), built 2024-12-12T14:06:36Z

#Setting Up the HCL Extension in VS Code

Vault uses the HCL format for configuration files (config.hcl) and policies. Installing the HashiCorp HCL extension in VS Code gives you syntax highlighting and early error detection. Just open the Extensions tab (Ctrl+Shift+X / Cmd+Shift+X), search for HashiCorp HCL, and install.

#Running a Vault Server

Now that the CLI is installed, we need to run a Vault server so we have something to "talk to." There are two ways we'll practice in this episode: dev mode for quick experimentation, and production-like via Docker as an early preview of the real mode.

#Dev Mode (vault server -dev)

Dev mode is Vault's built-in experimental mode. One command and Vault is up: in-memory storage (everything is lost on shutdown), unsealed (ready to use immediately), and the root token is already authenticated in the CLI.

vault server -dev
==> Vault server configuration:
 
             Api Address: http://127.0.0.1:8200
                     Cgo: disabled
         Cluster Address: https://127.0.0.1:8201
                  Listener 1: tcp (addr: "127.0.0.1:8200", tls: "disabled")
               Log Level: info
                   Mlock: supported: true, enabled: false
                 Storage: inmem
                 Version: Vault v1.18.3
 
WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
and starts unsealed with a single unseal key. The root token is already
authenticated to the CLI, so you can immediately begin using Vault.
 
You may need to set the following environment variable:
 
    $ export VAULT_ADDR='http://127.0.0.1:8200'
 
Unseal Key: eyJhbGciOiJIUzI1NiIs...
Root Token: hvs.rVN8j5dLp7X3nL2F8sB0vQ9cH

Pay attention to three important things in the output above:

1. Api Address: http://127.0.0.1:8200 — this is the endpoint the CLI must target. Without telling it via VAULT_ADDR, the CLI won't know where to talk to.
2. Unseal Key and Root Token — the two most sensitive secrets in Vault. In dev mode both are printed directly to the screen for the sake of experimentation.
3. The big warning: dev mode must NEVER be used in production. Data is in memory, there's no TLS, and there's no seal/unseal.

#Production-Like via Docker

To get a feel for how Vault "really" works (initialization, sealing, unsealing — which we'll dissect in episode 3), we'll start with Vault via Docker. First, prepare a minimal configuration file:

storage "file" {
  path = "/vault/file"
}
 
listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}
 
api_addr     = "http://127.0.0.1:8200"
disable_mlock = true

docker run --cap-add=IPC_LOCK \
  -e 'VAULT_DEV_ROOT_TOKEN_ID=dev-only-token' \
  -p 8200:8200 \
  -v "$(pwd)/config.hcl:/vault/config/config.hcl" \
  -v "$(pwd)/vault-data:/vault/file" \
  hashicorp/vault:latest server -config=/vault/config/config.hcl

In this mode, Vault runs just like on a production server: file storage, and not yet initialized. We'll learn how to initialize and unseal it in detail in episode 3.

#CLI Environment Configuration

For the Vault CLI to connect to the server, we need to set the two most important environment variables: VAULT_ADDR (server address) and VAULT_TOKEN (our identity).

export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_TOKEN='hvs.rVN8j5dLp7X3nL2F8sB0vQ9cH'
 
# Verify the connection
vault status

In dev mode, VAULT_TOKEN can be omitted because the CLI is already authenticated automatically — but outside dev mode, without VAULT_TOKEN you'll be rejected with a permission denied or missing client token error. Make it a habit to always set both.

For convenience, you can put these variables in the project's .env.local file (which is already ignored by Git) or in ~/.bashrc:

VAULT_ADDR=http://127.0.0.1:8200
VAULT_TOKEN=hvs.rVN8j5dLp7X3nL2F8sB0vQ9cH

set -a && source .env.local && set +a
vault status

#Verify: Your First vault status

With the environment set, this is the first moment you "talk" to Vault. The output below is from dev mode (not initialized — meaning the status would be the opposite in production mode):

vault status
Key             Value
---             -----
Seal Type       shamir
Initialized     true
Sealed          false
Total Shares    1
Threshold       1
Version         1.18.3
Build Date      2024-12-12 14:06:36Z
Storage Type    inmem
Cluster Name    vault-cluster-6e4b2c9a
Cluster ID      3f4a5b6c-7d8e-4f90-a1b2
HA Enabled      false

Don't worry if terms like Seal Type, Shares, and Threshold aren't clear yet — all of them will be dissected thoroughly in episode 3 about initialization & unsealing. For now, what matters is: Initialized: true and Sealed: false mean Vault is ready to use.

#First Demo: Writing & Reading a Secret

Now it's time for the most satisfying experiment — writing your first secret and reading it back:

vault kv put secret/api/database username="admin" password="S3cret!Passw0rd"
Success! Data written to: secret/api/database

vault kv get secret/api/database
====== Data ======
Key         Value
---         -----
username    admin
password    S3cret!Passw0rd

Congratulations, you just used the KV Secrets Engine — one of the most fundamental secrets engines in Vault, which we'll cover thoroughly in episode 4.

#Accessing the Web UI

Vault also provides a web interface. Once the server is running, open your browser and navigate to:

http://127.0.0.1:8200/ui
 
# Log in with the root token shown earlier
# or set via VAULT_DEV_ROOT_TOKEN_ID

The Web UI is useful for visualization: viewing the list of secrets, editing policies, and monitoring audit logs. In dev mode, use the root token to log in. In later episodes, the Web UI will help you verify what we're configuring via the CLI.

#Common Setup Mistakes

Based on experience, these are the three mistakes that happen most often when playing with Vault for the first time:

There's one more that often tricks people: copying a token from an old log when the Vault dev mode server has already been restarted (a new token is issued on every restart). Always grab the token from the currently running server session.

#Conclusion

In episode 0 we've laid a solid foundation: mastering three fundamental skills (Linux CLI, basic cryptography concepts, and an understanding of REST API & JSON), preparing the required hardware and tools, installing the Vault CLI, running a Vault server in dev mode and production-like via Docker, setting VAULT_ADDR and VAULT_TOKEN, doing our first vault kv put/get demo, and getting familiar with the Web UI.

Key takeaways to remember:

• Vault lives at the intersection of Linux CLI, modern cryptography, and HTTP APIs — master all three.
• Understand the difference between symmetric encryption, asymmetric encryption, and hashing — they are Vault's native language.
• The Vault CLI is a single binary — install it, verify with vault --version, and it's ready to use.
• Always set VAULT_ADDR and VAULT_TOKEN before interacting with the server.
• Dev mode is for learning, not production — in-memory storage, no sealing, token in the logs.

Make sure all the skills and tools above are ready, because the next episode goes deeper into the concepts. In episode 1, we'll cover the problem statement behind secret management: secret sprawl and why the modern world needs Vault — from the danger of API keys hard-coded in source code, .env files leaking into Git, static credentials that are rarely rotated, to the taxonomy of secret types you should know. Keep your enthusiasm up, because your Vault learning journey has only just begun!