Vault Policies Part 1

Welcome to Vault Policies Part 1. Whether you’re a Vault operator or preparing for the Certified Vault Operations Professional exam, mastering policies is essential. In this guide, you’ll learn how Vault policies define which clients—CI/CD pipelines, auditors, Terraform, DevOps engineers, admins, Packer, web apps, and more—can access specific secrets and paths.

What Are Vault Policies?

Vault policies are declarative rules (in HCL or JSON) that grant or deny capabilities on Vault paths. They provide fine-grained, RBAC-style access control. Most operators prefer HCL for readability.

By default, Vault enforces an implicit deny: if no policy grants access to a path, the request is denied. You can also add explicit deny rules to override grants. Policies are attached to tokens and other auth entities; multiple policies on a token combine their permissions cumulatively.

Built-In (Out-of-the-Box) Policies

Immediately after deployment, Vault includes two default policies:

To list and inspect these policies:

vault policy list
# -> default
vault policy read default
# Allow tokens to look up their own properties
path "auth/token/lookup-self" {
  capabilities = ["read"]
}
# ... other default rules

Reading the root policy returns an error (no readable rules):

vault policy read root
# No policy named: root

Internally, the root policy is equivalent to:

path "*" {
  capabilities = ["create","read","update","delete","list","sudo"]
}

Managing Policies with the CLI

Vault’s CLI offers vault policy subcommands: list, read, write, delete, and fmt.

List all policies:

vault policy list
# -> admin-policy
#    default
#    root

Create or update a policy from an HCL file:

vault policy write admin-policy /tmp/admin.hcl
# Success! Uploaded policy: admin-policy

Inline policy definition via heredoc:

vault policy write webapp -<< 'EOF'
path "kv/data/apps/*" {
  capabilities = ["read","create","update","delete"]
}
path "kv/metadata/*" {
  capabilities = ["read","create","update","list"]
}
EOF

Managing Policies in the UI

In the Vault web UI, go to Policies to view ACLs. The root policy appears grayed out (non-editable). Use the three-dot menu on any other policy to edit or delete it, or click Create ACL Policy to add a new one.

Managing Policies via the HTTP API

Vault’s HTTP API exposes policy management endpoints. To write a policy:

curl --header "X-Vault-Token: s.EXAMPLETOKEN" \
     --request PUT \
     --data @payload.json \
     https://vault.example.com:8200/v1/sys/policy/webapp

• Header: X-Vault-Token for auth
• Method: PUT to create or update
• URL: /v1/sys/policy/<policy-name>
• Body (payload.json): JSON with a "policy" field containing HCL or JSON rules

Example payload.json:

{
  "policy": "path \"kv/apps/webapp\" { capabilities = [\"read\",\"list\"] }"
}

For details, see the Vault HTTP API docs.

Anatomy of a Vault Policy

Each policy consists of one or more path blocks:

path "<resource-path>" {
  capabilities = ["<create|read|update|delete|list|sudo>"]
}

Combine blocks to cover multiple resources:

path "kv/data/apps/jenkins" {
  capabilities = ["read","update","delete"]
}

path "sys/policies/*" {
  capabilities = ["create","update","list","delete"]
}

path "aws/creds/web-app" {
  capabilities = ["read"]
}

Understanding Vault Paths

Every Vault feature—secret engines, auth methods, KV data—is namespaced under a path. Examples:

• sys/policy: Manage Vault’s own ACLs
• kv/app1/app01/web: KV v1 secrets
• database/creds/my-role: Dynamic DB credentials
• auth/token/renew-self: Token renewal endpoint

For KV v2 mounts (e.g., at secrets), include the data prefix:

vault kv get secrets/data/platform/aws/tools/ansible

Here, secrets = mount point, data = v2 API prefix.

Root-Protected Paths

Certain operations require a root token or sudo capability. Examples:

• auth/token/create-orphan: Create orphan tokens
• pki/root/sign-self-issued: Sign certificates
• sys/rotate: Rotate encryption keys
• sys/seal: Seal the Vault
• sys/step-down: Force leader step-down

Example policy granting sudo:

path "sys/rotate" {
  capabilities = ["sudo"]
}
path "sys/seal" {
  capabilities = ["sudo"]
}
path "sys/step-down" {
  capabilities = ["sudo"]
}

Links and References

• Vault HTTP API Documentation
• HashiCorp Vault Concepts
• Terraform Registry
• Packer Documentation