vault policy write: Define Access Policies
vault policy write NAME FILE creates or updates a named policy from an HCL file that grants capabilities on paths.
Policies are how Vault scopes access. For CI you write a tight policy granting read on just the paths a job needs, then attach it to the auth role. KV v2 path rules are the usual stumbling block.
What it does
vault policy write uploads an HCL (or JSON) policy under a name. Each path block lists capabilities: create, read, update, patch, delete, list, sudo, deny. The policy is then referenced by token roles and auth-method roles.
Common usage
cat > ci-policy.hcl <<'EOF'
path "secret/data/ci/*" {
capabilities = ["read"]
}
path "secret/metadata/ci/*" {
capabilities = ["list"]
}
EOF
vault policy write ci ci-policy.hcl
# read policy from stdin
vault policy write ci - < ci-policy.hclOptions
| Item | What it does |
|---|---|
| NAME | Policy name to create or overwrite |
| FILE or - | HCL/JSON policy file, or - for stdin |
| capabilities | create, read, update, patch, delete, list, sudo, deny |
In CI
On KV v2 the read/write capability applies to secret/data/<path> and list applies to secret/metadata/<path>. A policy that grants read on secret/ci/* (the logical path) will silently fail to authorize a vault kv get, because the API path is secret/data/ci/*. Always write policies against the data/ and metadata/ API paths.
Common errors in CI
"permission denied" applying a policy means the token cannot write sys/policies/acl. After applying, a read that still returns 403 almost always means the policy targets the logical KV path instead of secret/data/.... "error parsing policy" points at malformed HCL, often a missing = or unquoted capability.