{"id":1006,"date":"2026-05-23T08:40:30","date_gmt":"2026-05-23T08:40:30","guid":{"rendered":"https:\/\/www.devopsschool.com\/tutorials\/?p=1006"},"modified":"2026-05-23T08:40:31","modified_gmt":"2026-05-23T08:40:31","slug":"hashicorp-vault-step-by-step-tutorial-vault-cli-on-linux-kv-secrets-userpass-auth-policy-and-crud","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/tutorials\/hashicorp-vault-step-by-step-tutorial-vault-cli-on-linux-kv-secrets-userpass-auth-policy-and-crud\/","title":{"rendered":"HashiCorp Vault: Step-by-Step Tutorial: Vault CLI on Linux \u2014 KV Secrets, Userpass Auth, Policy, and CRUD"},"content":{"rendered":"\n

This lab uses Vault CLI on Linux<\/strong> and demonstrates the full flow:<\/p>\n\n\n\n

    \n
  1. Start Vault<\/li>\n\n\n\n
  2. Enable KV secrets engine<\/li>\n\n\n\n
  3. Enable userpass<\/code> auth<\/li>\n\n\n\n
  4. Create a user without policy<\/li>\n\n\n\n
  5. Login as the user and fail to CRUD secrets<\/li>\n\n\n\n
  6. Create a policy<\/li>\n\n\n\n
  7. Attach policy to user<\/li>\n\n\n\n
  8. Login again and perform CRUD successfully<\/li>\n<\/ol>\n\n\n\n

    Vault\u2019s kv<\/code> command works with both KV v1 and KV v2, but for KV v2 the CLI path and policy path are different. HashiCorp recommends using the -mount<\/code> flag to avoid confusion with KV v2 paths. (HashiCorp Developer<\/a>)<\/p>\n\n\n\n

    \n\n\n\n

    1. Prerequisites<\/h2>\n\n\n\n

    You need a Linux machine with Vault installed. Vault is available as a precompiled binary and through Linux package managers such as apt<\/code> and yum<\/code>. (HashiCorp Developer<\/a>)<\/p>\n\n\n\n

    For Ubuntu\/Debian:<\/p>\n\n\n\n

    sudo apt update\nsudo apt install -y gpg wget\n\nwget -O- https:\/\/apt.releases.hashicorp.com\/gpg | \\\n  sudo gpg --dearmor -o \/usr\/share\/keyrings\/hashicorp-archive-keyring.gpg\n\necho \"deb [arch=$(dpkg --print-architecture) signed-by=\/usr\/share\/keyrings\/hashicorp-archive-keyring.gpg] https:\/\/apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' \/etc\/os-release || lsb_release -cs) main\" | \\\n  sudo tee \/etc\/apt\/sources.list.d\/hashicorp.list\n\nsudo apt update\nsudo apt install -y vault\n<\/code><\/pre>\n\n\n\n
    Verify:<\/p>\n\n\n\n
    vault version\nvault -help\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    2. Start Vault Dev Server<\/h2>\n\n\n\n
    For this lab, use Vault dev mode. This is only for learning, not production.<\/p>\n\n\n\n
    Open Terminal 1<\/strong>:<\/p>\n\n\n\n
    vault server -dev -dev-root-token-id=root\n<\/code><\/pre>\n\n\n\n
    Keep this terminal running.<\/p>\n\n\n\n
    Open Terminal 2<\/strong> and export Vault address and root token:<\/p>\n\n\n\n
    export VAULT_ADDR='http:\/\/127.0.0.1:8200'\nexport VAULT_TOKEN='root'\n<\/code><\/pre>\n\n\n\n
    Verify Vault status:<\/p>\n\n\n\n
    vault status\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    Sealed      false\n<\/code><\/pre>\n\n\n\n
    Login with root token:<\/p>\n\n\n\n
    vault login root\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    3. Enable KV Secrets Engine<\/h2>\n\n\n\n
    We will enable KV v2 at path devops<\/code>.<\/p>\n\n\n\n
    vault secrets enable -path=devops kv-v2\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    Success! Enabled the kv-v2 secrets engine at: devops\/\n<\/code><\/pre>\n\n\n\n
    Check enabled secrets engines:<\/p>\n\n\n\n
    vault secrets list\n<\/code><\/pre>\n\n\n\n
    Expected output should include:<\/p>\n\n\n\n
    devops\/    kv\n<\/code><\/pre>\n\n\n\n
    KV v2 stores versioned secrets and uses special API paths such as devops\/data\/...<\/code> for secret data and devops\/metadata\/...<\/code> for listing\/metadata operations. (HashiCorp Developer<\/a>)<\/p>\n\n\n\n
    \n\n\n\n
    4. Enable Userpass Auth Method<\/h2>\n\n\n\n
    Enable the userpass<\/code> authentication method:<\/p>\n\n\n\n
    vault auth enable userpass\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    Success! Enabled the userpass auth method at: userpass\/\n<\/code><\/pre>\n\n\n\n
    The userpass<\/code> auth method allows users to authenticate with a username and password stored directly in Vault under the users\/<\/code> path. (HashiCorp Developer<\/a>)<\/p>\n\n\n\n
    Verify auth methods:<\/p>\n\n\n\n
    vault auth list\n<\/code><\/pre>\n\n\n\n
    Expected output should include:<\/p>\n\n\n\n
    userpass\/    userpass\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    5. Create a User Without Policy<\/h2>\n\n\n\n
    Create a user called devuser<\/code>, but do not<\/strong> attach any custom policy yet.<\/p>\n\n\n\n
    vault write auth\/userpass\/users\/devuser \\\n  password='DevUser@123'\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    Success! Data written to: auth\/userpass\/users\/devuser\n<\/code><\/pre>\n\n\n\n
    At this point, the user can login, but cannot access the devops<\/code> secrets engine because Vault policies are deny-by-default unless access is explicitly granted. (HashiCorp Developer<\/a>)<\/p>\n\n\n\n
    \n\n\n\n
    6. Login as the User<\/h2>\n\n\n\n
    Login as devuser<\/code>:<\/p>\n\n\n\n
    vault login -method=userpass \\\n  username=devuser \\\n  password='DevUser@123'\n<\/code><\/pre>\n\n\n\n
    Expected output:<\/p>\n\n\n\n
    Success! You are now authenticated.\ntoken_policies    [\"default\"]\n<\/code><\/pre>\n\n\n\n
    Check current token:<\/p>\n\n\n\n
    vault token lookup\n<\/code><\/pre>\n\n\n\n
    You should see only the default<\/code> policy.<\/p>\n\n\n\n
    \n\n\n\n
    7. Try CRUD Secret as User \u2014 It Should Fail<\/h2>\n\n\n\n
    Try to Create Secret<\/h3>\n\n\n\n
    vault kv put -mount=devops app1\/db \\\n  username='admin' \\\n  password='secret123'\n<\/code><\/pre>\n\n\n\n
    Expected failure:<\/p>\n\n\n\n
    Error writing data to devops\/data\/app1\/db: Error making API request.\n\nCode: 403. Errors:\n\n* permission denied\n<\/code><\/pre>\n\n\n\n
    Try to Read Secret<\/h3>\n\n\n\n
    vault kv get -mount=devops app1\/db\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    permission denied\n<\/code><\/pre>\n\n\n\n
    This failure is correct. The user authenticated successfully, but authorization failed because no policy allows access to devops\/data\/*<\/code>.<\/p>\n\n\n\n
    \n\n\n\n
    8. Login Back as Root Admin<\/h2>\n\n\n\n
    Now switch back to root token so we can create a policy.<\/p>\n\n\n\n
    vault login root\n<\/code><\/pre>\n\n\n\n
    Or:<\/p>\n\n\n\n
    export VAULT_TOKEN='root'\n<\/code><\/pre>\n\n\n\n
    Confirm:<\/p>\n\n\n\n
    vault token lookup\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    policies    [root]\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    9. Create a Policy to Allow CRUD on KV Secrets<\/h2>\n\n\n\n
    Create a policy file:<\/p>\n\n\n\n
    cat > devops-crud-policy.hcl <<'EOF'\n# Allow create, read, update, and delete secret data in KV v2\npath \"devops\/data\/*\" {\n  capabilities = [\"create\", \"read\", \"update\", \"delete\"]\n}\n\n# Allow listing secrets and reading metadata in KV v2\npath \"devops\/metadata\" {\n  capabilities = [\"list\"]\n}\n\npath \"devops\/metadata\/*\" {\n  capabilities = [\"read\", \"list\", \"delete\"]\n}\nEOF\n<\/code><\/pre>\n\n\n\n
    Important: for KV v2, vault kv put\/get\/delete<\/code> uses the user-friendly command path, but the policy must target devops\/data\/*<\/code>. Listing uses devops\/metadata\/*<\/code>. HashiCorp\u2019s KV docs show that KV v2 maps kv get<\/code>, kv put<\/code>, and kv delete<\/code> to secret\/data\/<key_path><\/code>, while kv list<\/code> maps to secret\/metadata\/<key_path><\/code>. (HashiCorp Developer<\/a>)<\/p>\n\n\n\n
    Upload the policy:<\/p>\n\n\n\n
    vault policy write devops-crud devops-crud-policy.hcl\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    Success! Uploaded policy: devops-crud\n<\/code><\/pre>\n\n\n\n
    Verify policy:<\/p>\n\n\n\n
    vault policy read devops-crud\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    10. Attach Policy to Userpass User<\/h2>\n\n\n\n
    Update the existing devuser<\/code> and attach the devops-crud<\/code> policy:<\/p>\n\n\n\n
    vault write auth\/userpass\/users\/devuser \\\n  password='DevUser@123' \\\n  policies='devops-crud'\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    Success! Data written to: auth\/userpass\/users\/devuser\n<\/code><\/pre>\n\n\n\n
    In userpass<\/code>, users are configured under auth\/userpass\/users\/<username><\/code>, and policies can be associated during user creation or update. (HashiCorp Developer<\/a>)<\/p>\n\n\n\n
    \n\n\n\n
    11. Login Again as User<\/h2>\n\n\n\n
    vault login -method=userpass \\\n  username=devuser \\\n  password='DevUser@123'\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    Success! You are now authenticated.\ntoken_policies    [\"default\" \"devops-crud\"]\n<\/code><\/pre>\n\n\n\n
    Confirm:<\/p>\n\n\n\n
    vault token lookup\n<\/code><\/pre>\n\n\n\n
    You should now see:<\/p>\n\n\n\n
    policies    [default devops-crud]\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    12. Perform CRUD Secret Using User<\/h1>\n\n\n\n
    Now the same user should be able to create, read, update, and delete secrets.<\/p>\n\n\n\n
    \n\n\n\n
    C \u2014 Create Secret<\/h2>\n\n\n\n
    vault kv put -mount=devops app1\/db \\\n  username='admin' \\\n  password='secret123'\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    == Secret Path ==\ndevops\/data\/app1\/db\n\n======= Metadata =======\nversion    1\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    R \u2014 Read Secret<\/h2>\n\n\n\n
    vault kv get -mount=devops app1\/db\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    == Secret Path ==\ndevops\/data\/app1\/db\n\n====== Data ======\nKey         Value\n---         -----\npassword    secret123\nusername    admin\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    U \u2014 Update Secret<\/h2>\n\n\n\n
    vault kv put -mount=devops app1\/db \\\n  username='admin' \\\n  password='newSecret456'\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    == Secret Path ==\ndevops\/data\/app1\/db\n\n======= Metadata =======\nversion    2\n<\/code><\/pre>\n\n\n\n
    Read again:<\/p>\n\n\n\n
    vault kv get -mount=devops app1\/db\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    password    newSecret456\nusername    admin\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    L \u2014 List Secrets<\/h2>\n\n\n\n
    vault kv list -mount=devops app1\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    Keys\n----\ndb\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    D \u2014 Delete Secret<\/h2>\n\n\n\n
    vault kv delete -mount=devops app1\/db\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    Success! Data deleted, if it existed, at: devops\/data\/app1\/db\n<\/code><\/pre>\n\n\n\n
    Try to read again:<\/p>\n\n\n\n
    vault kv get -mount=devops app1\/db\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    No value found at devops\/data\/app1\/db\n<\/code><\/pre>\n\n\n\n
    In KV v2, kv delete<\/code> marks a version as deleted; it does not permanently destroy the underlying version data. Permanent removal uses vault kv destroy<\/code>, and full metadata removal uses vault kv metadata delete<\/code>. (HashiCorp Developer<\/a>)<\/p>\n\n\n\n
    \n\n\n\n
    13. Optional: Permanently Remove Secret Metadata<\/h1>\n\n\n\n
    Because KV v2 keeps metadata and versions, you may still see the path in metadata unless you delete it.<\/p>\n\n\n\n
    vault kv metadata delete -mount=devops app1\/db\n<\/code><\/pre>\n\n\n\n
    Expected:<\/p>\n\n\n\n
    Success! Data deleted, if it existed, at: devops\/metadata\/app1\/db\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    14. Useful Verification Commands<\/h1>\n\n\n\n
    Check secrets engines:<\/p>\n\n\n\n
    vault secrets list\n<\/code><\/pre>\n\n\n\n
    Check auth methods:<\/p>\n\n\n\n
    vault auth list\n<\/code><\/pre>\n\n\n\n
    Check current login token:<\/p>\n\n\n\n
    vault token lookup\n<\/code><\/pre>\n\n\n\n
    Check policies:<\/p>\n\n\n\n
    vault policy list\nvault policy read devops-crud\n<\/code><\/pre>\n\n\n\n
    Check user by reading config as root:<\/p>\n\n\n\n
    vault read auth\/userpass\/users\/devuser\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    15. Cleanup Lab<\/h1>\n\n\n\n
    Login as root:<\/p>\n\n\n\n
    vault login root\n<\/code><\/pre>\n\n\n\n
    Delete user:<\/p>\n\n\n\n
    vault delete auth\/userpass\/users\/devuser\n<\/code><\/pre>\n\n\n\n
    Delete policy:<\/p>\n\n\n\n
    vault policy delete devops-crud\n<\/code><\/pre>\n\n\n\n
    Disable auth method:<\/p>\n\n\n\n
    vault auth disable userpass\n<\/code><\/pre>\n\n\n\n
    Disable secrets engine:<\/p>\n\n\n\n
    vault secrets disable devops\n<\/code><\/pre>\n\n\n\n
    Stop Vault dev server by pressing:<\/p>\n\n\n\n
    CTRL + C\n<\/code><\/pre>\n\n\n\n
    \n\n\n\n
    Final Flow Summary<\/h1>\n\n\n\n
    Step<\/th>Command Area<\/th>Purpose<\/th><\/tr><\/thead>
    1<\/td>vault server -dev<\/code><\/td>Start lab Vault server<\/td><\/tr>
    2<\/td>vault secrets enable -path=devops kv-v2<\/code><\/td>Enable KV secrets engine<\/td><\/tr>
    3<\/td>vault auth enable userpass<\/code><\/td>Enable username\/password login<\/td><\/tr>
    4<\/td>vault write auth\/userpass\/users\/devuser<\/code><\/td>Create user without policy<\/td><\/tr>
    5<\/td>vault login -method=userpass<\/code><\/td>Login as user<\/td><\/tr>
    6<\/td>vault kv put\/get<\/code><\/td>Fails because user has no policy<\/td><\/tr>
    7<\/td>vault policy write<\/code><\/td>Create CRUD policy<\/td><\/tr>
    8<\/td>vault write auth\/userpass\/users\/devuser policies=...<\/code><\/td>Attach policy<\/td><\/tr>
    9<\/td>vault login -method=userpass<\/code><\/td>Login again with policy<\/td><\/tr>
    10<\/td>vault kv put\/get\/list\/delete<\/code><\/td>CRUD succeeds<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    This lab proves the key Vault concept: authentication only proves who the user is; policy decides what the user can do.<\/strong><\/p>\n","protected":false},"excerpt":{"rendered":"
    This lab uses Vault CLI on Linux and demonstrates the full flow: Vault\u2019s kv command works with both KV v1 and KV v2, but for KV v2… <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-1006","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/posts\/1006","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/comments?post=1006"}],"version-history":[{"count":1,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/posts\/1006\/revisions"}],"predecessor-version":[{"id":1007,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/posts\/1006\/revisions\/1007"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/media?parent=1006"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/categories?post=1006"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/tags?post=1006"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}