Secrets Providers

Secrets Providers

When using the Secrets Store feature, you can bring your own Secrets Provider Backend. Every Team on the platform is provided with a default encrypted secrets provider out of the box, but we recommend configuring your own Secrets Provider Backend for use in production environments.

We currently only directly support HashiCorp Vault as a Secrets Provider Backend, but we plan to expand support at some point in the future. Feel free to reach out to us if you have secrets storage needs that don’t fit our existing solutions.

General Usage Documentation
This page contains content specific to configuring and using third-party Secrets Provider Backends. Although you will likely want to set one up, you should begin with an overview of Configs and Secrets Stores.

Registering a Secrets Provider Backend

This section contains reference documentation about configuring a third-party Secrets Provider Backend for your Team and using to keep your Team’s sensitive configuration details secure on the platform.

Developing with HashiCorp Vault

Using Vault in Production

Configuring and managing a production-grade deployment of HashiCorp Vault is beyond the scope of this documentation. The information on this page is intended to help developers start building with HashiCorp Vault as quickly as possible, using a local Vault deployment during development.

Before using HashiCorp Vault as a Secrets Provider Backend in a production environment, we strongly recommend reviewing and following HashiCorp’s Vault reference documentation. DO NOT use HashiCorp Vault in production until you have reviewed the Production Hardening guide published by its maintainer.

To develop with HashiCorp Vault as your Secrets Provider Backend, you will need to install the Vault binary on your local machine. After it’s installed, run a local Vault server in development mode:

From the output of the above command, you’ll need to copy the ROOT_TOKEN to use in registering Vault with the platform (which has the value hvs.pvW6ZrrcKBOCtGbdGR4FA05f in the example below):

Configuring Dev Vault

You can then use a Commands workflow from our community to configure this running Vault instance for your Team. The usage instructions for the @vahid/vault workflow are shown here:

We can use the ops run command to start this workflow and begin configuring Vault as our Secrets Provider Backend.

Before using the following example, you should set the value of $TEAM_NAME to your currently active Team and the value of $VAULT_ROOT_TOKEN to the root token returned from the Vault development server above. Note that if your Vault dev server isn’t running on your local machine, you’ll also need to specify a --url flag with the full base URL (including port) of that server (as the default value for --url is http://host.docker.internal:8200).

If this command completes successfully, it will return a Vault token specifically for accessing your Team’s secrets stored by your development server.

Registering Dev Vault

If you would like to continue following along with the examples on this page, you’ll need to make your Vault dev server accessible from the public internet. One way to do this is by installing and configuring an ngrok tunnel…

…which points to the dev server on your local machine at port 8200, via HTTP.

Development Purposes Only

Installing ngrok or configuring other methods of making the dev server publicly accessible (e.g. SSH tunnels, port forwarding) are beyond the scope of this documentation.

Furthermore, please note that these instructions are only provided as an outline of the process you must follow to configure and register Vault as a Secrets Provider Backend for development purposes. These are not instructions for configuring a production environment.

With your Vault dev server accessible from the public internet, our CLI can be used to link it with your Team:

Run ops secrets:register in your terminal, and provide the public URL and your team’s Vault access token when prompted:

After your local Vault dev server has been registered with your Team, any operations that add, update, or retrieve values in your Secrets Store will use the linked Vault backend, rather than the default secrets provider.