https://github.com/hashicorp/vault-ruby

The official Ruby client for HashiCorp's Vault
https://github.com/hashicorp/vault-ruby

Keywords from Contributors

activerecord activejob mvc cfgmgt chef deployment feature-flag multithreading rack feature-toggle

Last synced: about 11 hours ago
JSON representation

Repository metadata

The official Ruby client for HashiCorp's Vault

Host: GitHub
URL: https://github.com/hashicorp/vault-ruby
Owner: hashicorp
License: mpl-2.0
Created: 2015-04-24T19:47:49.000Z (over 11 years ago)
Default Branch: master
Last Pushed: 2026-06-18T17:02:42.000Z (about 1 month ago)
Last Synced: 2026-06-19T18:05:25.111Z (about 1 month ago)
Language: Ruby
Size: 596 KB
Stars: 354
Watchers: 271
Forks: 137
Open Issues: 23
Releases: 2
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: CODEOWNERS

Vault Ruby Client

Vault is the official Ruby client for interacting with Vault by HashiCorp.

If you're viewing this README from GitHub on the master branch, know that it may contain unreleased features or
different APIs than the most recently released version. Please see the Git tag that corresponds to your version of the
Vault Ruby client for the proper documentation.

Quick Start

Install Ruby 3.1+: Guide.

Please note that as of Vault Ruby version 0.19.0, the minimum required Ruby version is 3.1. All EOL Ruby versions are no longer supported.

Install via Rubygems:

$ gem install vault

or add it to your Gemfile if you're using Bundler:

gem "vault"

and then run the bundle command to install.

Start a Vault client:

Vault.address = "http://127.0.0.1:8200" # Also reads from ENV["VAULT_ADDR"]
Vault.token   = "abcd-1234" # Also reads from ENV["VAULT_TOKEN"]
# Optional - if using the Namespace enterprise feature
# Vault.namespace   = "my-namespace" # Also reads from ENV["VAULT_NAMESPACE"]

Vault.sys.mounts #=> { :secret => #<struct Vault::Mount type="generic", description="generic secret storage"> }

Usage

The following configuration options are available:

Vault.configure do |config|
  # The address of the Vault server, also read as ENV["VAULT_ADDR"]
  config.address = "https://127.0.0.1:8200"

  # The token to authenticate with Vault, also read as ENV["VAULT_TOKEN"]
  config.token = "abcd-1234"
  # Optional - if using the Namespace enterprise feature
  # config.namespace   = "my-namespace" # Also reads from ENV["VAULT_NAMESPACE"]

  # Proxy connection information, also read as ENV["VAULT_PROXY_(thing)"]
  config.proxy_address  = "..."
  config.proxy_port     = "..."
  config.proxy_username = "..."
  config.proxy_password = "..."

  # Custom SSL PEM, also read as ENV["VAULT_SSL_CERT"]
  config.ssl_pem_file = "/path/on/disk.pem"

  # As an alternative to a pem file, you can provide the raw PEM string, also read in the following order of preference:
  # ENV["VAULT_SSL_PEM_CONTENTS_BASE64"] then ENV["VAULT_SSL_PEM_CONTENTS"]
  config.ssl_pem_contents = "-----BEGIN ENCRYPTED..."

  # Passphrase for encrypted PEM files
  config.ssl_pem_passphrase = "my-passphrase"

  # Custom SSL CA certificate for verification
  config.ssl_ca_cert = "/path/to/ca.crt"

  # Custom SSL CA certificate directory
  config.ssl_ca_path = "/path/to/ca/directory"

  # Custom SSL certificate store
  config.ssl_cert_store = OpenSSL::X509::Store.new

  # Specify SSL ciphers to use
  config.ssl_ciphers = "TLSv1.2:!aNULL:!eNULL"

  # Use SSL verification, also read as ENV["VAULT_SSL_VERIFY"]
  config.ssl_verify = false

  # SNI hostname to use for SSL connections
  config.hostname = "vault.example.com"

  # Timeout the connection after a certain amount of time (seconds), also read
  # as ENV["VAULT_TIMEOUT"]
  config.timeout = 30

  # It is also possible to have finer-grained controls over the timeouts, these
  # may also be read as environment variables
  config.ssl_timeout  = 5
  config.open_timeout = 5
  config.read_timeout = 30

  # Connection pool settings for persistent connections
  config.pool_size = 5
  config.pool_timeout = 5
end

If you do not want the Vault singleton, or if you need to communicate with multiple Vault servers at once, you can create independent client objects:

client_1 = Vault::Client.new(address: "https://vault.mycompany.com")
client_2 = Vault::Client.new(address: "https://other-vault.mycompany.com")

Authentication

Authenticate using various methods:

# LDAP
Vault.auth.ldap("username", "password")

# Username/Password
Vault.auth.userpass("username", "password")

# AppRole
Vault.auth.approle("role_id", "secret_id")

# GitHub token
Vault.auth.github("github_token")

# AWS IAM
Vault.auth.aws_iam("role_name", credentials_provider, "header_value")

And if you want to authenticate with a AWS EC2 :

    # Export VAULT_ADDR to ENV then
    # Get the pkcs7 value from AWS
    signature = `curl http://169.254.169.254/latest/dynamic/instance-identity/pkcs7`
    iam_role = `curl http://169.254.169.254/latest/meta-data/iam/security-credentials/`
    vault_token = Vault.auth.aws_ec2(iam_role, signature, nil)
    vault_client = Vault::Client.new(address: ENV["VAULT_ADDR"], token: vault_token.auth.client_token)

Making requests

All of the methods and API calls are heavily documented with examples inline using YARD. In order to keep the examples versioned with the code, the README only lists a few examples for using the Vault gem. Please see the inline documentation for the full API documentation. The tests in the 'spec' directory are an additional source of examples.

Idempotent requests can be wrapped with a with_retries clause to automatically retry on certain connection errors. For example, to retry on socket/network-level issues, you can do the following:

Vault.with_retries(Vault::HTTPConnectionError) do
  Vault.logical.read("secret/on_bad_network")
end

To rescue particular HTTP exceptions:

# Rescue 4xx errors
Vault.with_retries(Vault::HTTPClientError) {}

# Rescue 5xx errors
Vault.with_retries(Vault::HTTPServerError) {}

# Rescue all HTTP errors
Vault.with_retries(Vault::HTTPError) {}

For advanced users, the first argument of the block is the attempt number and the second argument is the exception itself:

Vault.with_retries(Vault::HTTPConnectionError, Vault::HTTPError) do |attempt, e|
  if e
    log "Received exception #{e} from Vault - attempt #{attempt}"
  end
  Vault.logical.read("secret/bacon")
end

The following options are available:

# :attempts - The number of retries when communicating with the Vault server.
#   The default value is 2.
#
# :base - The base interval for retry exponential backoff. The default value is
#   0.05s.
#
# :max_wait - The maximum amount of time for a single exponential backoff to
#   sleep. The default value is 2.0s.

Vault.with_retries(Vault::HTTPError, attempts: 5) do
  # ...
end

After the number of retries have been exhausted, the original exception is raised.

Vault.with_retries(Exception) do
  raise Exception
end #=> #<Exception>

KV Secrets Engine

Vault's KV secrets engine has two versions: v2 (versioned, default in Vault 0.10+) and v1 (unversioned). Use Vault.kv(mount) for v2 and Vault.logical for v1.

# Check which version your mount uses
mounts = Vault.sys.mounts
mounts[:secret].options[:version] #=> "2" or "1"

KV v2 (versioned secrets)

# Write and read
Vault.kv("secret").write("db/creds", username: "admin", password: "secret123")
secret = Vault.kv("secret").read("db/creds")
secret.data[:data] #=> { :username => "admin", :password => "secret123" }

# Read specific version
secret = Vault.kv("secret").read("db/creds", 2)

# List paths
Vault.kv("secret").list("db") #=> ["creds"]

# Soft delete (can be undeleted)
Vault.kv("secret").delete("db/creds")
Vault.kv("secret").delete_versions("db/creds", [1, 2])

# Undelete
Vault.kv("secret").undelete_versions("db/creds", [1])

# Permanently destroy
Vault.kv("secret").destroy_versions("db/creds", [1])
Vault.kv("secret").destroy("db/creds") # destroys all versions and metadata

# Metadata operations
Vault.kv("secret").write_metadata("db/creds", max_versions: 5)
metadata = Vault.kv("secret").read_metadata("db/creds")

KV v1 (unversioned secrets)

Vault.logical.write("secret/db/creds", username: "admin", password: "secret123")
secret = Vault.logical.read("secret/db/creds")
secret.data #=> { :username => "admin", :password => "secret123" }

Vault.logical.list("secret/db") #=> ["creds"]
Vault.logical.delete("secret/db/creds") #=> true

Seal Status

Vault.sys.seal_status
#=> #<Vault::SealStatus sealed=false, t=1, n=1, progress=0>

Tokens

See the Token Auth API docs for details.

# Create, lookup, renew, and revoke
token = Vault.auth_token.create(policies: ["app-read"], ttl: "1h", renewable: true)
info = Vault.auth_token.lookup_self
Vault.auth_token.renew_self(3600)
Vault.auth_token.revoke("hvs.CAESI...")

Response wrapping

# Request new access token as wrapped response where the TTL of the temporary
# token is "5s".
wrapped = Vault.auth_token.create(wrap_ttl: "5s")

# Unwrap the wrapped response to get the final token using the initial temporary
# token from the first request.
unwrapped = Vault.logical.unwrap(wrapped.wrap_info.token)

# Extract the final token from the response.
token = unwrapped.data.auth.client_token

A helper function is also provided when unwrapping a token directly:

# Request new access token as wrapped response where the TTL of the temporary
# token is "5s".
wrapped = Vault.auth_token.create(wrap_ttl: "5s")

# Unwrap wrapped response for final token using the initial temporary token.
token = Vault.logical.unwrap_token(wrapped)

API Coverage

Available Ruby clients:

Vault.kv(mount) - KV v2 secrets engine
Vault.logical - KV v1 and generic logical operations
Vault.sys - System backend (mounts, policies, seal status, etc.)
Vault.auth - Authentication methods (AWS, AppRole, GitHub, etc.)
Vault.auth_token - Token auth
Vault.approle - AppRole auth configuration
Vault.transform - Transform secrets engine
Vault.help - Interactive help

For full API documentation, see rubydoc.info/gems/vault or check spec/integration for examples

Development

Clone the project on GitHub
Create a feature branch
Submit a Pull Request

Important Notes:

All new features must include test coverage. At a bare minimum, Unit tests are required. It is preferred if you include integration tests as well.
The tests must be idempotent. The HTTP calls made during a test should be able to be run over and over.
Tests are order independent. The default RSpec configuration randomizes the test order, so this should not be a problem.
Integration tests require Vault Vault must be available in the path for the integration tests to pass.
- In order to be considered an integration test: The test MUST use the vault_test_client or vault_redirect_test_client as the client. This spawns a process, or uses an already existing process from another test, to run against.

Owner metadata

Name: HashiCorp
Login: hashicorp
Email: hello@hashicorp.com
Kind: organization
Description: Consistent workflows to provision, secure, connect, and run any infrastructure for any application.
Website: https://hashicorp.com
Location: San Francisco, CA
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/761456?v=4
Repositories: 920
Last ynced at: 2025-07-01T06:04:51.252Z
Profile URL: https://github.com/hashicorp

GitHub Events

Total

Delete event: 27
Pull request event: 44
Fork event: 4
Issues event: 11
Watch event: 10
Issue comment event: 26
Push event: 15
Pull request review event: 6
Pull request review comment event: 1
Create event: 29

Last Year

Delete event: 27
Pull request event: 41
Issues event: 11
Watch event: 1
Issue comment event: 20
Push event: 15
Pull request review event: 6
Pull request review comment event: 1
Create event: 29

Committers metadata

Last synced: 26 days ago

Total Commits: 446
Total Committers: 78
Avg Commits per committer: 5.718
Development Distribution Score (DDS): 0.587

Commits in past year: 34
Committers in past year: 7
Avg Commits per committer in past year: 4.857
Development Distribution Score (DDS) in past year: 0.559

Name	Email	Commits
Seth Vargo	s**o@g**m	184
Evan Phoenix	e**n@p**o	36
Lauren Voswinkel	l**l@h**m	32
Max Schwenk	m**k@g**m	25
dependabot[bot]	4****]	19
Chris Arcand	c**s@c**m	17
nick evans	n**k@r**v	12
Pat Allan	p**t@f**m	9
Dylan Canfield	D**d@c**u	6
Stephan Epping	s**g@z**e	6
Joerg Freimuth	j**h@o**e	5
tcosgrave	t**e@w**m	5
hashicorp-copywrite[bot]	1****]	3
Matthew Sanabria	2****o	3
Matthew Lapworth	m**h@n**m	3
Ev Ralston	e****n	3
Kerri Miller	k**r@k**m	3
Sarah Thompson	s**n@h**m	2
Paul Hinze	p**e@p**m	2
Michele	m**s@g**m	2
Matt Button	m**n@g**m	2
Kenneth Vestergaard	k**s@b**k	2
Jurriaan Pruis	e**l@j**l	2
Daniel Huckins	d****s	2
Mathieu Jobin	m**u@v**m	2
Eric Jacobs	e**j@s**m	2
Max Timchenko	m**t@p**m	2
Tom Maher	t**r@g**m	2
Tim Chambers	t**m@p**m	2
Tom Proctor	t****p	2
and 48 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 26 days ago

Total issues: 44
Total pull requests: 195
Average time to close issues: about 1 year
Average time to close pull requests: 3 months
Total issue authors: 41
Total pull request authors: 59
Average comments per issue: 2.14
Average comments per pull request: 1.19
Merged pull request: 73
Bot issues: 0
Bot pull requests: 97

Past year issues: 5
Past year pull requests: 55
Past year average time to close issues: about 2 months
Past year average time to close pull requests: 11 days
Past year issue authors: 5
Past year pull request authors: 7
Past year average comments per issue: 0.4
Past year average comments per pull request: 0.76
Past year merged pull request: 6
Past year bot issues: 0
Past year bot pull requests: 45

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/hashicorp/vault-ruby

Top Issue Authors

hunter86bg (2)
broksonic21 (2)
eheydrick (2)
ls-brentsmith (1)
jacobat (1)
dmaze (1)
castro1688 (1)
mike-bailey (1)
yakatz (1)
adoyleplm (1)
SarahRiley (1)
khawkins (1)
rethridge-lbi (1)
rileytg (1)
jaark (1)

Top Pull Request Authors

dependabot[bot] (88)
Valarissa (16)
nevans (9)
TaopaiC (4)
hashicorp-copywrite[bot] (3)
sudomateo (3)
chrisarcand (3)
dhuckins (3)
compliance-pr-automation-bot[bot] (3)
sarahethompson (2)
yesmeck (2)
tomhjp (2)
petems (2)
hashicorp-tsccr[bot] (2)
mladlow (2)

Top Issue Labels

enhancement (1)

Top Pull Request Labels

dependencies (88)
github_actions (86)
legal (3)
automated (3)
SEC-090 (2)
parked (1)
ecosystem (1)
SEC-090/Pinning/Trusted (1)