Helm-Vault stores private data from YAML files in Hashicorp Vault. Helm-Vault should be used if you want to publicize your YAML configuration files, without worrying about leaking secret information.
- Helm-Vault
- About the Project
- Project Status
- Getting Started
- Release Process
- How to Get Help
- Contributing
- Further Reading
- License
- Authors
- Acknowledgments
Helm-Vault supports the following features:
- Encrypt YAML files
- Decrypt YAML files
- View decrypted YAML files
- Edit decrypted YAML files
- Clean up decrypted YAML files
- Helm Wrapper, automatically decrypts and cleans up during helm commands
- Install
- Upgrade
- Template
- Lint
- Diff
Helm-Vault was created to provide a better way to manage secrets for Helm, with the ability to take existing public Helm Charts, and with minimal modification, provide a way to have production data that is not stored in a public location.
$ helm vault enc values.yaml
Input a value for /mariadb/db/password:
Input a value for /externalDatabase/user:
Input a value for /nextcloud/password:
Build Status:
Helm-Vault is in a production state. It should work across platforms, and should be able to handle most YAML thrown at it.
To get started with Helm-Vault, follow these steps:
-
Clone the repository to your machine
-
Install the requirements
pip3 install -r requirements.txt
-
Test it out! This will test out encrypting an example YAML file
./src/vault.py enc ./tests/test.yaml
- Python 3.7+
- pip3
- Working Hashicorp Vault environment
- Hashicorp Vault token
- Environment Variables for Vault
- VAULT_ADDR: The HTTP Address of Vault
- VAULT_TOKEN: The token for accessing Vault
- YAML files must be in a git repo or have the full path specified in the file. See Vault Path Templating.
This project is hosted on GitHub. You can clone this project directly using this command:
git clone [email protected]:Justin-Tech/helm-vault.git
Helm-Vault has built-in unit tests using pytest, you can run them with the command below:
pip3 install -r ./tests/requirements.txt
python3 -m pytest
for running tests using docker, you can use the following command:
./run-test.sh
Unittesting and integration testing is automatically run via Github Actions on commit and PRs.
Additionally, code quality checking is handled by CodeQL.
Both of these checks must pass before PRs will be merged.
pip3 install git+https://github.com/Just-Insane/helm-vault
helm plugin install https://github.com/Just-Insane/helm-vault
$ helm vault --help
usage: vault.py [-h] {enc,dec,clean,view,edit} ...
Store secrets from Helm in Vault
Requirements:
Environment Variables:
VAULT_ADDR: (The HTTP address of Vault, for example, https://localhost:8200)
VAULT_TOKEN: (The token used to authenticate with Vault)
positional arguments:
{enc,dec,clean,view,edit}
enc Parse a YAML file and store user entered data in Vault
dec Parse a YAML file and retrieve values from Vault
clean Remove decrypted files (in the current directory)
view View decrypted YAML file
edit Edit decrypted YAML file. DOES NOT CLEAN UP AUTOMATICALLY.
optional arguments:
-h, --help show this help message and exit
Any YAML file can be transparently "encrypted" as long as it has a deliminator for secret values.
Decrypted files have the suffix ".yaml.dec" by default
Note: Flags take precedent over Environment Variables.
Environment Variable | Default Value (if unset) |
Overview | Required |
---|---|---|---|
VAULT_ADDR |
null |
The HTTP(S) address fo Vault | Yes |
VAULT_TOKEN |
null |
The token used to authenticate with Vault | Yes |
VAULT_NAMESPACE |
null |
The Vault namespace used for the command | |
VAULT_PATH |
secret/helm |
The default path used within Vault | |
VAULT_MOUNT_POINT |
secret |
The default mountpoint used within Vault | |
SECRET_DELIM |
changeme |
The value which will be searched for within YAML to prompt for encryption/decryption | |
SECRET_TEMPLATE |
VAULT: |
Used for Vault Path Templating | |
EDITOR |
- Windows: notepad - macOS/Linux: vi |
The editor used when calling helm vault edit |
|
KVVERSION |
v1 |
The K/V secret engine version within Vault |
More detailed information available below:
VAULT_ADDR
The HTTP(S) address of Vault, for example, https://localhost:8200
Default when not set: null
, the program will error and inform you that this address needs to be set as an environment variable.
VAULT_TOKEN
The token used to authenticate with Vault.
Default when not set: null
, the program will error and inform you that this value needs to be set as an environment variable.
VAULT_NAMESPACE
The Vault namespace used for the command. Namespaces are isolated environments that functionally exist as "Vaults within a Vault." They have separate login paths and support creating and managing data isolated to their namespace. Namespaces are only available in Vault Enterprise.
Default when not set: null
.
VAULT_PATH
This is the path within Vault that secrets are stored. It should start with the name of the secrets engine being used and an optional folder within that secrets engine that all Helm-Vault secrets will be stored.
Default when not set: secret/helm
, where secret
is the secrets engine being used, and helm
is the folder in which all secrets will be stored.
VAULT_MOUNT_POINT
This is the mountpoint within Vault that secrets are stored. Vault stores secrets in the following url format /{mount_point}/data/{path}
. Mountpoint in this case could also include any namespaces, e.g. namespace1/subnamespace/mountpoint
= /namespace1/subnamespace/mountpoint/data/{path}
.
Default when not set: secret
, where secret
is the mountpoint being used.
SECRET_DELIM
This is the value which Helm-Vault will search for within the YAML files to prompt for encryption, or replace when decrypting.
Default when not set: changeme
.
SECRET_TEMPLATE
This is the value that Helm-Vault will search for within the YAML files to denote Vault Path Templating.
Default when not set: VAULT:
EDITOR
This is the editor that Helm-Vault will use when requesting helm vault edit
.
Default when not set:
- Windows:
notepad
- macOS/Linux:
vi
KVVERSION
This is the K/V secret engine version within Vault, currently v1
and v2
are supported.
Default when not set: v1
Note: Expect this to change in a later version, as Vault now defaults to v2
K/V secrets engines.
enc Encrypt file
dec Decrypt file
view Print decrypted file
edit Edit file (decrypt before, manual cleanup)
clean Delete *.yaml.dec files in directory (recursively)
Each of these commands have their own help, referenced by helm vault {enc,dec,clean,view,edit} --help
.
Flag | Usage | Default | Availability |
---|---|---|---|
-d , --deliminator |
The secret deliminator used when parsing | changeme |
enc , dec , view , edit , install , template , upgrade , lint , diff |
-vp , --vaultpath |
The Vault Path (secret mount location in Vault) | secret/helm |
enc , dec , view , edit , install , template , upgrade , lint , diff |
-mp , --mountpoint |
The Vault Mount Point | secret |
enc , dec , view , edit , install , template , upgrade , lint , diff |
-vt , --vaulttemplate |
Substring with path to vault key instead of deliminator. | VAULT: |
enc , dec , view , edit , install , template , upgrade , lint , diff |
-kv , --kvversion |
The version of the KV secrets engine in Vault | v1 |
enc , dec , view , edit , install , template , upgrade , lint , diff |
-v , --verbose |
Verbose output | enc , dec , clean , view , edit , install , template , upgrade , lint , diff |
|
-s , --secret-file |
File containing secrets for input, rather than using stdin, must end in .yaml.dec |
enc |
|
-f , --file |
The specific YAML file to be deleted, without .dec |
clean |
|
-ed , --editor |
Editor name | Windows: notepad , macOS/Linux: vi |
edit |
-f , --values |
The encrypted YAML file to decrypt on the fly | install , template , upgrade , lint , diff |
|
-e , --environment |
Environment that secrets should be stored under | enc , dec , clean , install |
The encrypt operation encrypts a values.yaml file and saves the encrypted values in Vault:
$ helm vault enc values.yaml
Input a value for nextcloud.password: asdf1
Input a value for externalDatabase.user: asdf2
Input a value for .mariadb.db.password: asdf3
If you don't want to enter the secrets manually on stdin, you can pass a file containing the secrets. Copy values.yaml
to values.yaml.dec
and edit the file, replacing "changeme" (the deliminator) with the secret value. Then you can save the secret to vault by running:
$ helm vault enc values.yaml -s values.yaml.dec
By default the name of the secret file has to end in .yaml.dec
so you can add this extension to gitignore to prevent committing a secret to your git repo.
In addition, you can namespace your secrets to a desired environment by using the -e
flag.
helm vault enc values.yaml -e prod
Input a value for nextcloud.password: asdf1
Input a value for externalDatabase.user: asdf2
Input a value for mariadb.db.password: asdf3
The decrypt operation decrypts a values.yaml file and saves the decrypted result in values.yaml.dec:
$ helm vault dec values.yaml
The values.yaml.dec file:
...
nextcloud:
host: nextcloud.example.com
username: admin
password: asdf1
...
mariadb:
parameters
enabled: true
db:
name: nextcloud
user: nextcloud
password: asdf2
...
If leveraging environment specific secrets, you can decrypt the desired environment by specifying with the -e
flag.
Doing so will result in a decrypted file that is stored as my_file.yaml.{environment}.dec
For example
$ helm vault dec values.yaml -e prod
Will result in your production environment secrets being dumped into a file named values.yaml.prod.dec
The view operation decrypts values.yaml and prints it to stdout:
$ helm vault view values.yaml
The edit operation will decrypt the values.yaml file and open it in an editor.
$ helm vault edit values.yaml
This will read a value from $EDITOR, or be specified with the -e, --editor
option, or will choose a default of vi
for Linux/MacOS, and notepad
for Windows.
Note: This will save a .dec
file that is not automatically cleaned up.
The operation will delete all decrypted files in a directory:
$ helm vault clean
It is possible to setup vault's path inside helm chart like this
key1: VAULT:helm1/test/key1
key2: VAULT:/helm2/test/key2
This mean that key1 will be storing into base_path/helm1/test/key1 and key2 into /helm2/test/key2 . Where is helm2 is root path enabled via secrets enable. For example:
vault secrets enable -path=helm2 kv-v2
To override default value of template path pattern use SECRET_TEMPLATE variable. By default this value is VAULT: . This is mean that all keys with values like VAULT:something will be stored inside vault.
The operation wraps the default helm install
command, automatically decrypting the -f values.yaml
file and then cleaning up afterwards.
$ helm vault install stable/nextcloud --name nextcloud --namespace nextcloud -f values.yaml
Specifically, this command will do the following:
- Run
helm install
with the following options: stable/nextcloud
- the chart to install--name nextcloud
- the Helm release name will benextcloud
--namespace nextcloud
- Nextcloud will run in the nextcloud namespace on Kubernetes-f values.yaml
- the (encrypted) values file to use
The operation wraps the default helm template
command, automatically decrypting the -f values.yaml
file and then cleaning up afterwards.
$ helm vault template ./nextcloud --name nextcloud --namespace nextcloud -f values.yaml
- Run
helm template
with the following options: ./nextcloud
- the chart to template--name nextcloud
- the Helm release name will benextcloud
--namespace nextcloud
- Nextcloud will run in the nextcloud namespace on Kubernetes-f values.yaml
- the (encrypted) values file to use
The operation wraps the default helm upgrade
command, automatically decrypting the -f values.yaml
file and then cleaning up afterwards.
$ helm vault upgrade nextcloud stable/nextcloud -f values.yaml
- Run
helm upgrade
with the following options: nextcloud
- the Helm release namestable/nextcloud
- the chart path-f values.yaml
- the (encrypted) values file to use
The operation wraps the default helm lint
command, automatically decrypting the -f values.yaml
file and then cleaning up afterwards.
$ helm vault lint nextcloud -f values.yaml
- Run
helm upgrade
with the following options: nextcloud
- the Helm release name-f values.yaml
- the (encrypted) values file to use
The operation wraps the helm diff
command (diff is another Helm plugin), automatically decrypting the -f values.yaml
file and then cleaning up afterwards.
$ helm vault diff upgrade nextcloud stable/nextcloud -f values.yaml
- Run
helm diff upgrade
with the following options: nextcloud
- the Helm release namestable/nextcloud
- the Helm chart-f values.yaml
- the (encrypted) values file to use
Releases are made for new features, and bugfixes.
To get a new release, run the following:
helm plugin upgrade vault
This project uses Semantic Versioning. For a list of available versions, see the repository tag list.
If you need help or have questions, please open a new discussion Q&A section.
We encourage public contributions! Please review CONTRIBUTING.md for details on our code of conduct and development process.
Copyright (c) 2019 Justin Gauthier
This project is licensed under GPLv3 - see LICENSE.md file for details.
The idea for this project comes from Helm-Secrets
Special thanks to the Python Discord server.