Documentation ¶
Overview ¶
Package vaku wraps an official Vault client with useful high-level functions.
Terminology ¶
A 'path' in vault references a location. This location can either be a secret itself or a folder containing secrets. A clean path does not start or end with a '/'.
A 'key' is the same as a path except that it can end in a '/', signifying for certain that it is a folder. A trailing slash is a way of notifying that a path is a folder, but lack of a trailing slash does not imply the opposite.
A 'folder' is a key that ends in a '/'. Folders are not secrets, but they contain secrets and/or other folders.
Summary ¶
Vaku is intended to provide useful functions for Vault that let users operate securely and efficiently. Using the official Vault API and CLI it is only possible to take CRUD actions on individual paths, however normal usage of vault will eventually lead to a desire for more advanced functions like the ability to copy or move paths or even entire folders. The functions in this package can be broken into the distinct categroies below.
Helpers ¶
These exported functions provide useful ways to manage Vault paths in code. They provide utilities for cleaning, combining, and splitting Vault paths, keys, and folders. Many of these utilities exist unexported in the official Vault Golang API, but they are useful enough to provide to end users here.
Path Functions ¶
Path functions act on vault paths under both versions of the key/value secrets engine. They should not be used on paths outside of those engines. The path functions in Vaku are opinionated and easy to use. However this means that they do not support many of the features in the Vault API. For example, PathRead() does not return any metadata or other information about a secret, only the data of the secret itself.
Folder Functions ¶
Folder functions act on vault folders under both versions of the key/value secrets engine. They should not be used on folders outside of those engines. In general, a folder function acts on all paths found by listing the input path recursively. For example, FolderDelete() on "secret/test" will list all paths within "secret/test" and its subfolders and then call PathDelete() on each one. Folder functions are executed concurrently using a worker pool of goroutines and channels.
Policy and Role Functions ¶
Policy and role functions are intended to provide an opinionated and easy way of enforcing configuration in code. When setup properly you can run these functions daily (or as often as you like) to ensure that all policies and roles in Vault are defined in code. These functions will create all resources as defined in code and then delete any resources not defined.
Index ¶
- Variables
- func Version() string
- type Client
- func (c *Client) FolderCopy(s *PathInput, t *PathInput) error
- func (c *Client) FolderDelete(i *PathInput) error
- func (c *Client) FolderDestroy(i *PathInput) error
- func (c *Client) FolderList(i *PathInput) ([]string, error)
- func (c *Client) FolderMove(s *PathInput, t *PathInput) error
- func (c *Client) FolderRead(i *PathInput) (map[string]map[string]interface{}, error)
- func (c *Client) FolderReadOnce(i *PathInput) (map[string]map[string]interface{}, error)
- func (c *Client) FolderSearch(i *PathInput, s string) ([]string, error)
- func (c *Client) FolderWrite(d map[string]map[string]interface{}) error
- func (c *Client) InitPathInput(i *PathInput) error
- func (c *Client) KeyBase(k string) string
- func (c *Client) KeyClean(k string) string
- func (c *Client) KeyIsFolder(k string) bool
- func (c *Client) KeyJoin(ks ...string) string
- func (c *Client) MountInfo(p string) (*MountInfoOutput, error)
- func (c *Client) PathBase(p string) string
- func (c *Client) PathClean(p string) string
- func (c *Client) PathCopy(s *PathInput, t *PathInput) error
- func (c *Client) PathDelete(i *PathInput) error
- func (c *Client) PathDestroy(i *PathInput) error
- func (c *Client) PathJoin(ps ...string) string
- func (c *Client) PathList(i *PathInput) ([]string, error)
- func (c *Client) PathMove(s *PathInput, t *PathInput) error
- func (c *Client) PathRead(i *PathInput) (map[string]interface{}, error)
- func (c *Client) PathSearch(i *PathInput, s string) (bool, error)
- func (c *Client) PathUpdate(i *PathInput, d map[string]interface{}) error
- func (c *Client) PathWrite(i *PathInput, d map[string]interface{}) error
- func (c *Client) SliceAddKeyPrefix(ss []string, p string)
- func (c *Client) SliceRemoveFolders(ss []string) []string
- func (c *Client) SliceTrimKeyPrefix(ss []string, p string)
- type MountInfoOutput
- type PathInput
Constants ¶
This section is empty.
Variables ¶
var MaxConcurrency = 10
MaxConcurrency is the maximum number of threads/workers to use when calling Folder-based functions that execute concurrently. The default value is 10, but a stable and well-tuned Vault server should be able to handle up to 100 without issues. Use with caution and tune specifically to your environment and storage backend.
Functions ¶
Types ¶
type Client ¶
Client is a simple wrapper around a real Vault API client. All Vaku functions are defined on Client as well, which lets anyone already using a Vault Client easily make use of Vaku.
func NewClient ¶
func NewClient() *Client
NewClient returns a new empty Vaku Client. Using this function requires that you initialize and set the nested Vault client on your own before Vaku functions will work.
func NewClientFromVaultClient ¶
NewClientFromVaultClient takes in an official Vault Client that you have already created and returns a Vaku client that wraps your Vault client.
func (*Client) FolderCopy ¶
FolderCopy takes in a source PathInput and target PathInput and copies every path in the source to the target. Note that this will copy the input path if it is a secret and all paths under the input path that result from calling FolderList() on that path. Also note that this will overwrite any existing keys at the target paths.
func (*Client) FolderDelete ¶
FolderDelete takes in a path and deletes every key in that folder and all sub-folders. Note that this calls PathDelete() on every path found in the folder, and for v2 secret mounts that means deleting the active version, but not all versions.
func (*Client) FolderDestroy ¶ added in v1.1.0
FolderDestroy takes in a path and destroys every key in that folder and all sub-folders. Note that this function only works on V2 mounts and that it destroys ALL versions of ALL keys
func (*Client) FolderList ¶
FolderList takes in a PathInput and walks the path by calling PathList on the input path and all folders within that path as well. Returns the results as a sorted slice of paths.
func (*Client) FolderMove ¶
FolderMove calls FolderCopy() with the same inputs followed by FolderDelete() on the source path if the copy was successful.
func (*Client) FolderRead ¶
FolderRead takes in a PathInput and calls PathRead() on all paths in that path and all nested paths. It outputs a map of paths (strings) to PathRead() outputs (map[string]interface{}).
func (*Client) FolderReadOnce ¶
FolderReadOnce takes in a PathInput and calls PathRead() on all non-folders in that path. It outputs a map of paths (strings) to PathRead() outputs (map[string]interface{}). This function is different from FolderRead in that it reads the immediately nested keys, instead of all keys in the folder and its subfolders.
func (*Client) FolderSearch ¶
FolderSearch takes in a PathInput and a search string. It then calls FolderList() on that path and concurrently runs PathSearch() on every returned path in the list. It returns a list of paths at which the search string was found. Note that running this function against a path that is not a folder will produce an error, to search a single path you should use PathSearch() instead.
func (*Client) FolderWrite ¶
FolderWrite takes in a map of paths to data that should be written to that path. Users may find this function difficult to call on its own because the input can be large and specific, however the output of FolderRead matches the input of FolderWrite(), making them easy to use together. Note that mount/version information is determined only once using a random path in the map and cached for all future writes. Therefore this function cannot write to two mounts of different versions in the same call.
func (*Client) InitPathInput ¶
InitPathInput fills in missing values from PathInput with defaults and mount information. This function will rarely be useful by end-users, but could lead to performance gain if multiple actions are being taken on the same PathInput by preventing repeats of the relatively expensive task of determining mount information about the path
func (*Client) KeyBase ¶
KeyBase returns the last element of path k and cleans it. If k is empty or all slashes, return an empty string
func (*Client) KeyClean ¶
KeyClean simply calls KeyJoin() with one string. KeyJoin already cleans keys, so this helper exists only for naming simplicity.
func (*Client) KeyIsFolder ¶
KeyIsFolder returns true if the string ends in a '/'.
func (*Client) KeyJoin ¶
KeyJoin takes n strings and combines them into a clean Vault key. Vault keys (as opposed to paths) optionally have a trailing '/' to signify they are a folder.
func (*Client) MountInfo ¶
func (c *Client) MountInfo(p string) (*MountInfoOutput, error)
MountInfo gets information about the mount at the specified path that can be used to determine what actions to take on that path.
func (*Client) PathClean ¶
PathClean just calls PathJoin() with one string. PathJoin already cleans paths, so this helper exists only for naming simplicity.
func (*Client) PathCopy ¶
PathCopy takes in a source PathInput and a target PathInput. It then copies the data from one path to another. Note that PathCopy can be used to copy data from one mount to another. Note also that this will overwrite any existing key at the target path.
func (*Client) PathDelete ¶
PathDelete takes in a PathInput and calls the native Vault delete on it. For v2 mounts this function only "marks the path as deleted", it does nothing with the versions of the path
func (*Client) PathDestroy ¶ added in v1.1.0
PathDestroy takes in a PathInput and calls the native delete on 'mount/metadata/path' This function only works on versioned (V2) key/value mounts. Note that this destroys ALL versions at the path, there is no current support for destroying specific versions.
func (*Client) PathJoin ¶
PathJoin takes n strings and combines them into a clean Vault path. Paths in vault (unlike keys) never end with a '/'.
func (*Client) PathList ¶
PathList takes in a PathInput, calls the native vault list on it, extracts the secret (list of keys), and returns it. Note that any metadata or other information returned by the list is thrown away.
func (*Client) PathMove ¶
PathMove calls PathCopy() with the same inputs followed by PathDelete() on the source if the copy was successful. Note that this will overwrite any existing keys at the target Path.
func (*Client) PathRead ¶
PathRead takes in a PathInput, calls the native vault read on it, extracts the secret, and returns it as a map of strings to values. Note that this is the way secrets are represented in Vault, as map[string]interface{} (JSON)
func (*Client) PathSearch ¶
PathSearch takes in a PathInput and a search string, reads the path, and searches the read data for a match on the search string. Returns true if the string is found in the data. Note that this is a simple search that just checks if the secret contains the search string anywhere. Also note that if this is a KV version 2 mount and the input path has been deleted (but not destroyed) this returns false with no error.
func (*Client) PathUpdate ¶
PathUpdate takes in a path with existing data and new data to write to that path. It then merges the data at the existing path with the new data, with precedence given to the new data, and writes the merged data back to Vault
func (*Client) PathWrite ¶
PathWrite takes in a PathInput and data to written to that path. It then calls the native vault write with that data at the specified path.
func (*Client) SliceAddKeyPrefix ¶
SliceAddKeyPrefix takes in a slice of keys (strings) and a prefix and adds that prefix to every key in the slice
func (*Client) SliceRemoveFolders ¶
SliceRemoveFolders takes a list of keys and removes any folders (strings that end in a '/') and returns the new filtered list
func (*Client) SliceTrimKeyPrefix ¶
SliceTrimKeyPrefix takes in a slice of keys (strings) and a prefix and trims that prefix from every key in the slice
type MountInfoOutput ¶
type MountInfoOutput struct { FullPath string // The original input path MountPath string // The path of the mount MountlessPath string // The FullPath with the MountPath removed MountVersion string // The version of the mount, default "unknown" }
MountInfoOutput holds output for MountInfo. This data can be useful for determining which key/value engine version a path is mounted on and acting accordingly.
type PathInput ¶
PathInput is the standard way of representing a Vault path with Vaku. The only required input is the Path itself. You can also specify TrimPathPrefix which determines if returned paths include the full input Path or only the nested paths. This struct also holds unexported data about the version of the key/value mount that the path is in.
func NewPathInput ¶
NewPathInput takes in a Path and returns the default PathInput. This function can be used to easily take a path string and use it as input for a Vaku function. TrimPathPrefix is true by default, which produces behavior similar to the Vault API.
Source Files ¶
- client.go
- defaults.go
- doc.go
- folder_copy.go
- folder_delete.go
- folder_destroy.go
- folder_list.go
- folder_move.go
- folder_read.go
- folder_search.go
- folder_write.go
- helpers.go
- mount_helpers.go
- path_copy.go
- path_delete.go
- path_destroy.go
- path_list.go
- path_move.go
- path_read.go
- path_search.go
- path_types.go
- path_update.go
- path_write.go
- version.go