In this tutorial, we will set up Vault Agent to generate a .env file with secrets from HashiCorp Vault. We’ll use the AppRole authentication method to securely authenticate and retrieve secrets, then write them to an environment file for use in your application.

You can find the complete configuration files and setup used in this tutorial in the GitHub repository.

⚠️ Important Note: This tutorial uses Vault in development mode (-dev) for simplicity. Development mode is not secure and should only be used for testing and learning purposes. In a production environment:

• Use a properly initialized and unsealed Vault server.
• Secure the Vault server with TLS certificates and access control.

Prerequisites

• Vault server running (in development mode for testing)
• Vault Agent installed and configured
• Basic knowledge of Vault and its authentication methods

Step 1: Start Vault Server in Development Mode

We’ll start Vault in development mode for testing purposes. This will make Vault accessible via 127.0.0.1:8200 with a root token.

Run the following command:

vault server -dev -dev-root-token-id=root -dev-tls

Then export VAULT_ADDR and VAULT_CACERT from the output of previous command to give the ability to cli to have access to Vault server:

export VAULT_ADDR='https://127.0.0.1:8200'
export VAULT_CACERT='/tmp/vault-tls900287623/vault-ca.pem'

And create two dummy secrets as username and password of a database that later we want to write them in a env variable:

vault kv put secret/dbinfo user=root pass=test123

Access Vault’s UI by navigating to https://127.0.0.1:8200 and logging in with the root token.

Step 2: Set Up the AppRole Authentication Method

We will use AppRole for authentication. First, enable the AppRole authentication method:

vault auth enable approle

Next, create a new AppRole and attach a policy that allows reading from the secret/data/dbinfo path:

1. Create the Vault policy (agent-policy.hcl):
   

   path "secret/data/dbinfo" {
     capabilities = ["read"]
   }
   

2. Write the policy:
   

   vault policy write agent-policy agent-policy.hcl
   

3. Create the AppRole and attach the policy:
   

   vault write auth/approle/role/vault-agent-role policies="agent-policy"
   

4. Generate the role_id and secret_id:
   

   vault read auth/approle/role/vault-agent-role/role-id
   vault write -f auth/approle/role/vault-agent-role/secret-id
   

The role_id and secret_id are required to authenticate via AppRole. Save these values to the files role_id and secret_id.

Step 3: Configure Vault Agent

The Vault Agent configuration file (vault-agent.hcl) will authenticate with Vault using the AppRole and generate a .env file with the secret values. Here’s an example configuration:

# Vault Agent configuration
vault {
  address = "https://127.0.0.1:8200"
  token = "<client_token>"
}

auto_auth {
  method "approle" {
    mount_path = "auth/approle"
    config = {
      role_id_file_path = "./role_id"
      secret_id_file_path = "./secret_id"
    }
  }

  sink "file" {
    path = "./vault-agent-token"
  }
}

template {
  source      = "./env-template.tmpl"
  destination = "./.env"
}

Explanation:

• The role_id_file_path and secret_id_file_path point to the files containing the AppRole credentials.
• The template block specifies the path to the env-template.tmpl file and the destination for the generated .env file.

Step 4: Create the Template File (env-template.tmpl)

Create a template file (env-template.tmpl) that Vault Agent will use to generate the .env file. Here’s an example template:

DB_USER={{ with secret "secret/data/dbinfo" }}{{ .Data.data.user }}{{ end }}
DB_PASS={{ with secret "secret/data/dbinfo" }}{{ .Data.data.pass }}{{ end }}

This template will insert the user and pass from the Vault secrets into the .env file.

Step 5: Start Vault Agent

Now, we will start the Vault Agent to authenticate and generate the .env file:

vault agent -config=./vault-agent.hcl

Vault Agent will authenticate using AppRole, retrieve the secret from secret/data/dbinfo, and generate the .env file at the specified location.

Step 6: Check the Generated .env File

After Vault Agent runs, the .env file will be populated with the secrets from Vault:

DB_USER=root
DB_PASS=test123

This file can now be used to set environment variables for your application.

Your final files should be like this:

agent-policy.hcl
env-template.tmpl
role_id
secret_id
vault-agent.hcl
vault-agent.pid
vault-agent-token

Conclusion

In this tutorial, we’ve configured Vault Agent to authenticate with Vault using AppRole, retrieve secrets, and generate a .env file. This is a simple and secure way to manage sensitive configuration data in your application.

I hope this tutorial helps you get Vault Agent running smoothly. Happy coding! 🚀