vaultfs

Documentation

Overview

Package vaultfs provides an interface to Hashicorp Vault which allows you to interact with the Vault API as a standard filesystem.

This filesystem's behaviour complies with testing/fstest.TestFS.

Usage

To use this filesystem, call New with a base URL. All reads from the filesystem are relative to this base URL. The schemes "vault", "vault+https", "https", "vault+http", and "http" are supported, though the http schemes should only be used in development/test environments. If no authority part (host:port) is present in the URL, the $VAULT_ADDR environment variable will be used as the Vault server's address.

To scope the filesystem to a specific path, use that path on the URL. For example, for a filesystem that can only read from the K/V engine mounted on "secret" with a prefix of "dev", you could use a URL like:

vault:///secret/dev/

Note: when scoping URLs to specific paths, the URL must end in "/".

Reading secrets and credentials from all Vault Secret Engines is supported, though some may require parameters to be set. To set parameters, append a URL query string to the path when reading (in the form "?param=value&param2=value2"). When parameters are set in this way, vaultfs will send a POST request to the Vault API, except when the K/V Version 2 secret engine is in use.

In general, data is read from Vault in the same way as with the Vault CLI - that is, the "/v1" prefix is not needed, and with the K/V Version 2 secret engine the "data" prefix should not be provided.

When reading from K/V v2 secret engines, specific versions of the secret can be read by providing a "version" query parameter. For example, to read the fifth version of the secret at "secret/mysecret", you could use a URL like:

vault:///secret/mysecret?version=5

See the Vault Secret Engine Docs for more details.

Authentication

A number of authentication methods are supported and documented in detail by the vaultauth package. Use the vaultauth.WithAuthMethod function to set your desired auth method. Custom auth methods can be created by implementing the github.com/hashicorp/vault/api.AuthMethod interface.

By default, the $VAULT_TOKEN environment variable will be used as the Vault token, falling back to the content of $HOME/.vault-token.

When multiple files are opened simultaneously, the same authentication token will be used for each of them, and will only be revoked when the last file is closed. This ensures that a minimal number of tokens are acquired, however this also means that tokens may be leaked if all opened files are not closed.

See the vaultauth docs for details on each auth method.

For help in deciding which auth method to use, consult the Vault Auth Docs.

Permissions

The correct capabilities must be allowed for the authenticated credentials. Regular secret read operations require the "read" capability, dynamic secret generation requires "create" and "update", and listing (ReadDir) requires the "list" capability.

See Vault Capabilities Docs for more details on how to configure these on your Vault server.

Environment Variables

A number of environment variables are understood by the Go Vault client that vaultfs uses internally. See Vault Client Environment Variable Docs for detail.

Example

base, _ := url.Parse("vault://my.vaultserver.local:8200")
token := "1234abcd"

fsys, _ := New(base)
fsys = vaultauth.WithAuthMethod(vaultauth.NewTokenAuth(token), fsys)

b, _ := fs.ReadFile(fsys, "secret/mysecret")

// data returned by Vault is always JSON
s := struct{ Value string }{}

_ = json.Unmarshal(b, &s)

fmt.Printf("the secret is %s\n", s.Value)

Index

• Variables
• func New(u *url.URL) (fs.FS, error)
• func WithAuthMethod(auth AuthMethod, fsys fs.FS) fs.FS
• type AuthMethod
  • func AppRoleAuthMethod(roleID, secretID, mount string) AuthMethod
  • func EnvAuthMethod() AuthMethod
  • func GitHubAuthMethod(ghtoken, mount string) AuthMethod
  • func TokenAuthMethod(token string) AuthMethod
  • func UserPassAuthMethod(username, password, mount string) AuthMethod

Examples

• Package

Variables

var FS = fsimpl.FSProviderFunc(New, "vault", "vault+http", "vault+https")

FS is used to register this filesystem with an fsimpl.FSMux

Functions

func New

func New(u *url.URL) (fs.FS, error)

New creates a filesystem for the Vault endpoint rooted at u.

It is especially important to make sure that opened files are closed, otherwise a Vault token may be leaked!

The filesystem may be configured with:

• vaultauth.WithAuthMethod (set the auth method)
• fsimpl.WithContextFS (inject a context)
• fsimpl.WithHeaderFS (inject custom HTTP headers)

func WithAuthMethod

func WithAuthMethod(auth AuthMethod, fsys fs.FS) fs.FS

WithAuthMethod configures the given FS to authenticate with auth, if the filesystem supports it.

Note that this is not required if $VAULT_TOKEN is set.

Deprecated: use github.com/hairyhenderson/go-fsimpl/vaultfs/vaultauth.WithAuthMethod instead

Types

type AuthMethod

type AuthMethod interface {
	// Login acquires a Vault token using client for communicating with Vault,
	// and configures client with the token.
	Login(ctx context.Context, client *api.Client) error

	// Logout revokes the Vault token attached to client.
	Logout(ctx context.Context, client *api.Client) error
}

AuthMethod is an authentication method that vaultfs can use to acquire a token.

Deprecated: see github.com/hashicorp/vault/api.AuthMethod instead

func AppRoleAuthMethod

func AppRoleAuthMethod(roleID, secretID, mount string) AuthMethod

AppRoleAuthMethod authenticates to Vault with the AppRole auth method. If either roleID or secretID are omitted, the values will be read from the $VAULT_ROLE_ID and/or $VAULT_SECRET_ID environment variables.

If mount is not set, it defaults to the value of $VAULT_AUTH_APPROLE_MOUNT or "approle".

See also https://www.vaultproject.io/docs/auth/approle

Deprecated: use github.com/hashicorp/vault/api/auth/approle.NewAppRoleAuth instead

func EnvAuthMethod

func EnvAuthMethod() AuthMethod

EnvAuthMethod chooses the first auth method to have the correct environment variables set, in this order of precedence:

AppRoleAuthMethod
GitHubAuthMethod
UserPassAuthMethod
TokenAuthMethod

Deprecated: use github.com/hairyhenderson/go-fsimpl/vaultfs/vaultauth.EnvAuthMethod instead

func GitHubAuthMethod

func GitHubAuthMethod(ghtoken, mount string) AuthMethod

GitHubAuthMethod authenticates to Vault with the GitHub auth method. If ghtoken is omitted, its value will be read from the $VAULT_AUTH_GITHUB_TOKEN environment variable.

If mount is not set, it defaults to the value of $VAULT_AUTH_GITHUB_MOUNT or "github".

See also https://www.vaultproject.io/docs/auth/github

Deprecated: use github.com/hairyhenderson/go-fsimpl/vaultfs/vaultauth.GitHubAuthMethod instead

func TokenAuthMethod

func TokenAuthMethod(token string) AuthMethod

TokenAuthMethod authenticates with the given token, or if none is provided, attempts to read from the $VAULT_TOKEN environment variable, or the $HOME/.vault-token file.

See also https://www.vaultproject.io/docs/auth/token

Deprecated: use github.com/hairyhenderson/go-fsimpl/vaultfs/vaultauth.TokenAuthMethod instead

func UserPassAuthMethod

func UserPassAuthMethod(username, password, mount string) AuthMethod

UserPassAuthMethod authenticates to Vault with the UpserPass auth method. If either username or password are omitted, the values will be read from the $VAULT_AUTH_USERNAME and/or $VAULT_AUTH_PASSWORD environment variables.

If mount is not set, it defaults to the value of $VAULT_AUTH_USERPASS_MOUNT or "userpass".

See also https://www.vaultproject.io/docs/auth/userpass

Deprecated: use github.com/hashicorp/vault/api/auth/userpass.NewUserPassAuth instead