Policies

Vault Policies define who can access what secrets and with which operations. Policies are written in HashiCorp Configuration Language (HCL) and provide fine-grained access control over Vault paths.

Key Concepts

Path-Based Rules

Policies grant capabilities on specific paths. Use wildcards to match multiple paths.

Capabilities

Define allowed operations: create, read, update, delete, list, sudo, deny.

Deny by Default

Users have no access unless explicitly granted by a policy.

Multiple Policies

Users can have multiple policies. Permissions are additive (union of all policies).

Required Permissions

Action	Permission
View policies	`iam:project:cicd:vault:read`
Create/Update policies	`iam:project:cicd:vault:write`
Delete policies	`iam:project:cicd:vault:delete`

Capabilities Reference

Capability	Description	Use Case
`create`	Create new data at a path	Writing new secrets
`read`	Read data from a path	Viewing secret values
`update`	Modify existing data	Changing secret values
`delete`	Remove data from a path	Deleting secrets
`list`	List keys at a path	Browsing folders
`sudo`	Access root-protected paths	Admin operations
`deny`	Explicitly deny access	Override inherited permissions

How to Create a Policy

Select Vault Instance

Choose the target Vault instance from the dropdown if you have multiple.

Click Create Policy

Click the Create Policy button.

Enter Policy Name

Provide a unique, descriptive name:

Use lowercase with hyphens (e.g., app-read-only)
Only alphanumeric, hyphens, and underscores allowed

Write Policy Rules

Define access rules in HCL format. Click Insert Example to start with a template.

Create

Click Create Policy to save.

Policy Syntax

Policies use HCL (HashiCorp Configuration Language) syntax:

# Grant full access to app secrets
path "secret/data/app/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# Read-only access to shared config
path "secret/data/shared/config" {
  capabilities = ["read"]
}

# List folders only (no secret access)
path "secret/metadata/*" {
  capabilities = ["list"]
}

Path Patterns

Pattern	Matches
`secret/data/app`	Exact path only
`secret/data/app/*`	All direct children
`secret/data/app/+/config`	Single-level wildcard
`secret/+/*`	Combination patterns

For KV v2 secrets engine, use secret/data/* for reading/writing secrets and secret/metadata/* for listing and metadata operations.

Common Policy Examples

Read-Only Policy

# Read and list secrets, no modifications
path "secret/data/*" {
  capabilities = ["read", "list"]
}

path "secret/metadata/*" {
  capabilities = ["list", "read"]
}

Application-Specific Policy

# Full access to app's own secrets
path "secret/data/myapp/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

path "secret/metadata/myapp/*" {
  capabilities = ["list", "read", "delete"]
}

# Read shared configuration
path "secret/data/shared/*" {
  capabilities = ["read"]
}

Team Lead Policy

# Manage team secrets
path "secret/data/team-alpha/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# Read other teams' public configs
path "secret/data/+/public/*" {
  capabilities = ["read"]
}

Deny Specific Paths

# Grant broad access
path "secret/data/app/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# But deny access to production credentials
path "secret/data/app/production/credentials" {
  capabilities = ["deny"]
}

How to Edit a Policy

Find the Policy

Use the search bar to locate the policy by name.

Click Edit

Click the edit (pencil) icon on the policy row.

Modify Rules

Update the HCL content in the editor.

Save

Click Update Policy to apply changes.

Policy changes take effect immediately. Users with active sessions may need to re-authenticate to see updated permissions.

How to Delete a Policy

Find the Policy

Locate the policy in the list.

Click Delete

Click the trash icon on the policy row.

Confirm

Confirm the deletion. This action cannot be undone.

Deleting a policy immediately revokes access for all users who depend on it. Ensure no critical workflows rely on this policy before deletion.

Best Practices

Naming Conventions

{app}-{access-level}          # myapp-read-only
{team}-{resource}-{access}    # platform-secrets-admin
{environment}-{role}          # production-deployer

Principle of Least Privilege

Grant minimum necessary permissions:

# Bad: Too broad
path "secret/*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

# Good: Specific and minimal
path "secret/data/myapp/config" {
  capabilities = ["read"]
}

Use Comments

Document the purpose of each rule:

# Allow CI/CD pipeline to read deployment secrets
path "secret/data/deploy/*" {
  capabilities = ["read"]
}

# Allow rotation of API keys only
path "secret/data/api-keys/*" {
  capabilities = ["read", "update"]
}

Separate by Environment

Create environment-specific policies:

# production-app policy
path "secret/data/production/app/*" {
  capabilities = ["read"]
}

# staging-app policy
path "secret/data/staging/app/*" {
  capabilities = ["create", "read", "update", "delete"]
}

Troubleshooting

Policy not taking effect

Users may need to log out and back in
Token may be cached with old permissions
Verify the policy is attached to the user/group

Permission denied errors

Check the exact path being accessed matches policy
For KV v2, ensure using secret/data/ prefix
Verify required capability is included
Check for explicit deny rules that may override

Cannot list secrets but can read

list capability must be on the metadata path
Add: path "secret/metadata/*" { capabilities = ["list"] }

Syntax error when saving

Check for missing closing braces }
Ensure capabilities are in array format ["read", "list"]
Verify no trailing commas in capability arrays
Use the Insert Example button to compare syntax

Cannot delete policy

You need delete permission for Vault policies
Built-in policies (root, default) cannot be deleted
Check with administrator for policy management permissions

FAQ

What happens when a user has multiple policies?

Permissions are additive. If policy A grants read and policy B grants write, the user has both read and write access. However, explicit deny always wins.

Can I test a policy before applying?

Use the Vault CLI vault token capabilities command to test what operations are allowed for a token on a specific path.

What's the difference between secret/data and secret/metadata?

For KV v2 secrets engine:

secret/data/* - Read/write actual secret values
secret/metadata/* - List paths, read/write metadata, delete versions

Can policies reference environment variables?

No. Policies are static HCL documents. Use templated policies with Vault Enterprise, or create separate policies per environment.

How do I grant admin access?

For full administrative access, attach the root policy. Use sparingly and prefer scoped policies for day-to-day operations.

Are policy names case-sensitive?

Yes. MyPolicy and mypolicy are different policies. Use consistent lowercase naming.

Getting Started

Infrastructure

Platform Services

CI/CD & Deployments

Pipeline & Helm

Performance Testing

Security

Mesh Networking

Access Management

Audit & Compliance

Settings

Key Concepts

Path-Based Rules

Capabilities

Deny by Default

Multiple Policies

Required Permissions

Capabilities Reference

How to Create a Policy

Policy Syntax

Path Patterns

Common Policy Examples

Read-Only Policy

Application-Specific Policy

Team Lead Policy

Deny Specific Paths

How to Edit a Policy

How to Delete a Policy

Best Practices

Naming Conventions

Principle of Least Privilege

Use Comments

Separate by Environment

Troubleshooting

FAQ

​Key Concepts

Path-Based Rules

Capabilities

Deny by Default

Multiple Policies

​Required Permissions

​Capabilities Reference

​How to Create a Policy

​Policy Syntax

​Path Patterns

​Common Policy Examples

​Read-Only Policy

​Application-Specific Policy

​Team Lead Policy

​Deny Specific Paths

​How to Edit a Policy

​How to Delete a Policy

​Best Practices

​Naming Conventions

​Principle of Least Privilege

​Use Comments

​Separate by Environment

​Troubleshooting

​FAQ

Key Concepts

Required Permissions

Capabilities Reference

How to Create a Policy

Policy Syntax

Path Patterns

Common Policy Examples

Read-Only Policy

Application-Specific Policy

Team Lead Policy

Deny Specific Paths

How to Edit a Policy

How to Delete a Policy

Best Practices

Naming Conventions

Principle of Least Privilege

Use Comments

Separate by Environment

Troubleshooting

FAQ