HashiCorp Vault 的官方 Ruby 客户端
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.
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 vaultor 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 => # }The following configuration options are available:
…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")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)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")
endTo 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")
endThe 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
# ...
endAfter the number of retries have been exhausted, the original exception is raised.
Vault.with_retries(Exception) do
raise Exception
end #=> #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"…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") #=> trueVault.sys.seal_status
#=> #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...")# 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_tokenA 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)Available Ruby clients:
Vault.kv(mount) - KV v2 secrets engineVault.logical - KV v1 and generic logical operationsVault.sys - System backend (mounts, policies, seal status, etc.)Vault.auth - Authentication methods (AWS, AppRole, GitHub, etc.)Vault.auth_token - Token authVault.approle - AppRole auth configurationVault.transform - Transform secrets engineVault.help - Interactive helpFor full API documentation, see rubydoc.info/gems/vault or check spec/integration for examples
Important Notes:
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.暂无开放 Issues,或尚未同步最近议题。