README
¶
dp-vault
Setting up vault
Using brew type brew install vault or the latest binaries can be downloaded at https://www.vaultproject.io/downloads.html
Running vault
To simplify running vault hashicorp has included a development mode for vault. Here is a list of things to remember when running in this mode;
- HTTPS is disabled
- An in-memory store is used (restarting vault will erase all data, including policies)
- When using the CLI tools make sure to export the following environment variable
VAULT_ADDR='http://127.0.0.1:8200' - When starting in development mode the vault is already in an
unsealedstate - The first 10 log lines in development mode print the
sealandroot-tokenkeys - Once the vault server is started the
root-tokenis written to~/.vault-token(usingvault login 'token'will overwrite this)
To run in development mode run vault server -dev
An example of log output for the root token looks like this;
You may need to set the following environment variable:
$ export VAULT_ADDR='http://127.0.0.1:8200'
The unseal key and root token are displayed below in case you want to
seal/unseal the Vault or re-authenticate.
Unseal Key: 4oHp2u/l6w2uPiZ/jqOe6EHTN6op6Xj7il9MUZCY7Ic=
Root Token: cb0a36cf-12c5-6b8c-87c9-63f990661f2e
Running the vault client example
To run the example code, make sure vault is started in development mode (vault server -dev). Then using the
Makefile run make debug
If the example ran successfully you should see the following output;
2018-03-02 12:55:16.278977145 +0000 GMT m=+0.003972743 debug: successfully written and read a key from vault
-> address: http://127.0.0.1:8200
-> token: c7598b3b-d9f5-465e-8e10-0bb7ee86f423
-> pk-key: 098980474948463874535354
Behind the scenes some additional operations were carried out to create a unique vault token for this app. All this is done in the Makefile. The following operations are carried out;
- Require the root_token
- Create a policy to allow the app to
readandcreateinsecret/shared/datasets/* - Using the newly created policy generates a token for the application
- Inject the generated token to the app from an environment variable
The root token could be used for the app, but the app will have the permission to carry out any operations in vault. This does not allow the policy to be tested when developing the app
The policy used for this app can be found at policy.hcl
Health package
The Vault checker function currently uses the Health functionality provided by the underlying Vault library by hashicorp. Otherwise, if it is not initialized, a CRITICAL Check structure is returned.
Read the Health Check Specification for details.
After running vault as described above, instantiate a vault client:
import "github.com/ONSdigital/dp-vault/vault"
...
vaultcli := vault.CreateClient(<token>, <vaultAddress>, <retries>)
...
Call the checker with vaultcli.Checker(context.Background()) and this will return a check object:
{
"name": "string",
"status": "string",
"message": "string",
"status_code": "int",
"last_checked": "ISO8601 - UTC date time",
"last_success": "ISO8601 - UTC date time",
"last_failure": "ISO8601 - UTC date time"
}
Contributing
See CONTRIBUTING for details.
License
Copyright © 2020, Office for National Statistics (https://www.ons.gov.uk)
Released under MIT license, see LICENSE for details.
Documentation
¶
Index ¶
- Constants
- Variables
- type APIClient
- type APIClientImpl
- type Client
- func CreateClient(token, vaultAddress string, retries int) (*Client, error)
- func CreateClientTLS(token, vaultAddress string, retries int, cacert, cert, key string) (*Client, error)
- func CreateClientWithAPIClient(apiClient APIClient) *Client
- func CreateClientWithConfig(config *vaultapi.Config, token string) (*Client, error)
- func (c *Client) Checker(ctx context.Context, state *health.CheckState) error
- func (c *Client) Healthcheck() (string, error)
- func (c *Client) Read(path string) (map[string]interface{}, error)
- func (c *Client) ReadKey(path, key string) (string, error)
- func (c *Client) VRead(path string) (map[string]interface{}, int64, error)
- func (c *Client) VReadKey(path, key string) (string, int64, error)
- func (c *Client) VWriteKey(path, key, value string) error
- func (c *Client) Write(path string, data map[string]interface{}) error
- func (c *Client) WriteKey(path, key, value string) error
Constants ¶
const MsgHealthy = "vault is healthy"
MsgHealthy Check message returned when vault is healthy
const ServiceName = "vault"
ServiceName vault
Variables ¶
var ( ErrKeyNotFound = errors.New("key not found") ErrVersionNotFound = errors.New("version not found") ErrMetadataNotFound = errors.New("metadata not found") ErrDataNotFound = errors.New("data not found") ErrVersionInvalid = errors.New("version failed to convert to number") )
Error definitions
var (
ErrNotInitialised = errors.New("vault not initialised")
)
Error definitions
Functions ¶
This section is empty.
Types ¶
type APIClient ¶
type APIClient interface {
SetToken(v string)
Read(path string) (*vaultapi.Secret, error)
Write(path string, data map[string]interface{}) (*vaultapi.Secret, error)
Health() (*vaultapi.HealthResponse, error)
}
APIClient is an interface to wrap Vault API Client, which is used by the dp-vault Client in order to interact with Vault, and can be easily mocked for testing
type APIClientImpl ¶
type APIClientImpl struct {
// contains filtered or unexported fields
}
APIClientImpl implements the APIClient interface wrapping the real vault API client calls to nested clients (e.g Logical or Sys)
func (*APIClientImpl) Health ¶
func (api *APIClientImpl) Health() (*vaultapi.HealthResponse, error)
Health calls Health() from the Sys client in vault API client
func (*APIClientImpl) Read ¶
func (api *APIClientImpl) Read(path string) (*vaultapi.Secret, error)
Read calls Read(path) from the Logical client in vault API client
func (*APIClientImpl) SetToken ¶
func (api *APIClientImpl) SetToken(v string)
SetToken calls SetToken directly to vault API client
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client Used to read and write secrets from vault using a vault API client wrapper.
func CreateClient ¶
CreateClient by providing an auth token, vault address and the maximum number of retries for a request
func CreateClientTLS ¶
func CreateClientTLS(token, vaultAddress string, retries int, cacert, cert, key string) (*Client, error)
CreateClientTLS is like the CreateClient function but wraps the HTTP client with TLS
func CreateClientWithAPIClient ¶
CreateClientWithAPIClient creates a Client with a provided Vault API client as input
func CreateClientWithConfig ¶
CreateClientWithConfig creates a Client with provided config and token as inputs
func (*Client) Checker ¶
Checker performs a check health of Vault and updates the provided CheckState accordingly
func (*Client) Healthcheck ¶
Healthcheck determines the state of vault
func (*Client) Read ¶
Read reads a secret from vault. If the token does not have the correct policy this returns an error; if the vault server is not reachable, return all the information stored about the secret.
func (*Client) ReadKey ¶
ReadKey from vault. Like read but only return a single value from the secret
func (*Client) VRead ¶
VRead reads a versioned secret from vault - cf Read, above - returns the secret (map) and the version
func (*Client) VReadKey ¶
VReadKey - cf Read but for versioned secret - return the value of the key and the version
func (*Client) VWriteKey ¶
VWriteKey creates a data map, with a data field containing the key-value, and writes it to vault
Source Files
Directories