Illustration of a terminal

How to provision secrets as environment variables

Many applications that follow the popular 12-Factor App guidelines source their secrets from the environment. This guide will walk you through the steps necessary to achieve this with SecretHub.

Before you begin

Before you start, make sure you have completed the following steps:

  1. Set up SecretHub on your workstation.

Step 1: Running the demo app

We will be using the SecretHub Demo app to demonstrate the process of injecting secrets as environment variables. This application serves a web page and tries to connect to using credentials provided in the environment (DEMO_USERNAME and DEMO_PASSWORD).

First, try to run the app locally without setting the username and password:

secrethub demo serve

A web page will now be served at http://localhost:8080, but if you visit it, you’ll see that it shows an error because it’s missing the username and password.

Step 2: Write your secrets

To get the demo application to work correctly, you’ll need to provide a username and password. You wouldn’t want to have those scattered around in plaintext, so let’s store those on SecretHub instead.

Here’s a nice shortcut to auto-generate the values for you at your-username/demo:

secrethub demo init

Step 3: Passing the secrets to the application

To provision an app with the secret it needs, you can use secrethub run:

secrethub run -- <application run command>

In the case of our demo app, that is:

secrethub run -- secrethub demo serve

Before you can execute this command, you have to tell the run command how it should map secrets to environment variables. There are two options to accomplish this.

Option 1: Secret References

Any environment variable value of the form secrethub://path/to/secret will be replaced with the specified secret.

export DEMO_USERNAME=secrethub://your-username/demo/username
export DEMO_PASSWORD=secrethub://your-username/demo/password

Secret references play well within configuration as code tools and CI configurations, because you can define the secrets next to the other configuration.

Option 2: Environment File

run also looks for a secrethub.env file in which you can configure environment variables:

DEMO_USERNAME = {{ your-username/demo/username }}
DEMO_PASSWORD = {{ your-username/demo/password }}

Environment files provide portability: you can check them into source control and use the same environment everywhere. For example, if you use them for your test secrets, you can run your tests both locally and in CI without having to manage the secrets separately.

Verifying it works

Having configured one of the options above, you can run the app again to see it all work:

secrethub run -- secrethub demo serve

If you visit http://localhost:8080 again, you’ll see that the red cross got replaced by a green checkmark.

run has set the environment variables as specified in either the secret references or secrethub.env file. Moreover, it will also mask the secrets on stdout and stderr to avoid accidentally logging them. The wisdom that was hidden in the Demo API has now been revealed!

See also

Happy coding!