Skip to content
A tool for provisioning instances of Hashicorp's Vault
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

This is a work in progress



One who provisions Vaults


It's a play on locksmith.



vaultsmith is a tool for provisioning instances of Hashicorp Vault, for example by setting up roles and access permissions. The goal is to support a declarative style of configuration, i.e. the configuration reflects the final state, and executions are idempotent.

This project is under active development, and third party contributions are most welcome.

Documentation is lacking at this point, and given its early stage, it should only be used on test servers.


A couple of years ago, Hashicorp published a blog post "Codifying Vault Policies and Configuration". We used a heavily modified version of their scripts to get us going with Vault. Vaultsmith is really just an extension of that idea, except that it uses the official Go client, and obviously is written in Go as well.

Essentially, the directory structure (document-path) reflects the API endpoints of Vault, and the contents of the document within is posted to Vault, using the built-in Vault client. It gets more complicated when you consider endpoints such as sys/auth and sys/policy have special methods in the Vault client, so these directories are assigned specific handlers which call the appropriate methods.


Native Go

go get


The image is not published, but you can build it after go get with:

cd $GOPATH/src/
make docker


$ vaultsmith -h
Usage of vaultsmith:
      --document-path string      The root directory of the configuration. Can be a local directory, local gz tarball or http url to a gz tarball.
      --dry                       Dry run; will read from but not write to vault
      --http-auth-token string    Auth token to pass as 'Authorization' header. Useful for passing user tokens to private github repos.
      --log-level string          Log level, valid values are [panic fatal error warning info debug] (default "info")
      --role string               The Vault role to authenticate as (default "root")
      --tar-dir string            Directory within the tarball to use as the document-path. If not specified, and there is only one directory within the archive, that one will be used. If there is more than one diretory, the root directory of the archive will be used.
      --template-file string      JSON file containing template mappings. If not specified, vaultsmith will look for "_vaultsmith.json" in the base of the document path.
      --template-params strings   Template parameters. Applies globally, but values in template-file take precedence. E.G.: service=foo,account=bar

It is strongly recommended that you use the --dry option before running against any live server. This ensures that no writes can happen during the run. If it indicates that it would do something unexpected, set log-level to debug with --log-level debug and it will show you (in go terms) exactly what it would write. If that looks wrong to you, please raise a bug!

It is important to remember that directories which are present in document-path reflect the final state. Thus, if you created an empty directory within document-path called say, "secrets", and ran it against your server, all documents under this path would be deleted from Vault!

Thus, ensure any vaultsmith-managed documents are in a separate path to user-managed documents. Or use it for configuration endpoints only as intended :)

Paths not present in document-path will not be affected.


Documentation required, but see example/_vaultsmith.json for an example.


Run up a test vault server and export your token:

docker run -p 8200:8200 vault:latest
export VAULT_TOKEN=$root_token
export VAULT_ADDR=http://localhost:8200

Run vaultsmith and it should apply the example document set:

vaultsmith --document-path

Pulling archives from private Github repositories

As github tarballs place the repository in a subdirectory, a little more work is needed. If for example you have your vault documents in directory called "data", which is within a git repository (I.E repository_root/data):

vaultsmith --document-path$ORG/$REPO/tarball/master --http-auth-token $TOKEN --tar-dir $ORG-$REPO-$COMMIT_SHA/data --dry

See the Github API docs for more information.

You can sidestep this by placing the documents at the root of the repository, and having nothing else in it, but the recommended solution is to create and upload your own tarballs to a private repository.

You can’t perform that action at this time.