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
- Getting Started
- Development
- How to Get Help
- Contributing
- Further Reading
- License
- Authors
- Acknowledgments
Helm-Vault supports the following features:
- Encrypt/Decrypt YAML files
- View/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.
The work isn't complete.
- Python 3.8+
- 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.
- Install the requirements
pip3 install -r https://raw.githubusercontent.com/shizacat/helm-vault-new/main/requirements.txt
- Install plugin
helm plugin install https://github.com/shizacat/helm-vault-new
$ 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, http://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 ".dec.yaml" by default
Note: Flags take precedence 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 |
Environment Variable | Default Value (if unset) |
Overview | Required |
---|---|---|---|
HELM_VAULT_PATH |
secret/helm |
The default path used within Vault | |
HELM_VAULT_MOUNT_POINT |
secret |
The default mountpoint used within Vault | |
HELM_VAULT_DELIMINATOR |
changeme |
The value which will be searched for within YAML to prompt for encryption/decryption | |
HELM_VAULT_TEMPLATE |
VAULT: |
Used for Vault Path Templating | |
HELM_VAULT_KVVERSION |
v2 |
The K/V secret engine version within Vault | |
HELM_VAULT_EDITOR |
- Windows: notepad - macOS/Linux: vi |
The editor used when calling helm vault edit |
VAULT_ADDR
The HTTP(S) address of Vault, for example, http://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
.
HELM_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 and through dot name of key.
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.
HELM_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.
HELM_VAULT_DELIMINATOR
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
.
HELM_VAULT_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:
HELM_VAULT_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.
HELM_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
enc Encrypt file
dec Decrypt file
view Print decrypted file
edit Edit file (decrypt before, manual cleanup)
clean Delete *.dec.yaml 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 |
-p , --path |
The Vault Path (secret mount location in Vault) | secret/helm |
enc , dec , view , edit , install , template , upgrade , lint , diff |
-mp , --mount-point |
The Vault Mount Point | secret |
enc , dec , view , edit , install , template , upgrade , lint , diff |
-t , --template |
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 | v2 |
enc , dec , view , edit , install , template , upgrade , lint , diff |
-v , --verbose |
Verbose output | enc , dec , clean , view , edit , install , template , upgrade , lint , diff |
|
-f , --file |
The specific YAML file to be deleted, without .dec.yaml . This option can be specified more than once. |
clean |
|
-f , --values |
The encrypted YAML file to decrypt on the fly. This option can be specified more than once. | install , template , upgrade , lint , diff |
|
-ed , --editor |
Editor name | Windows: notepad , macOS/Linux: vi |
edit |
-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 -f values.yaml
Input a value for nextcloud.password: asdf1
Input a value for externalDatabase.user: asdf2
Input a value for .mariadb.db.password: asdf3
In addition, you can namespace your secrets to a desired environment by using the -e
flag.
helm vault enc -f 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.dec.yaml:
$ helm vault dec -f values.yaml
The values.dec.yaml 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.{environment}.dec.yaml
For example
$ helm vault dec -f values.yaml -e prod
Will result in your production environment secrets being dumped into a file named values.prod.dec.yaml
The view operation decrypts values.yaml and prints it to stdout:
$ helm vault view -f values.yaml
The edit operation will decrypt the values.yaml file and open it in an editor.
$ helm vault edit -f values.yaml
This will read a value from $HELM_VAULT_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.yaml
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
key_filename.txt: VAULT:/helm2/test.key_filename..txt
This mean that key1 will be storing into base_path/helm1/test (key1) and key2 into /helm2/test (key2). If you need the dot in path or key, you can double it, example: key_filename.txt. 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
This project is hosted on GitHub. You can clone this project directly using this command:
git clone git@github.com:shizacat/helm-vault-new.git
Helm-Vault has built-in unit tests using pytest, you can run them with the command below:
pip3 install -r requirements-dev.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 LGTM.com
Both of these checks must pass before PRs will be merged.
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) 2022 Alexey Matveev
This project is licensed under GPLv3 - see LICENSE.md file for details.
The idea for this project comes from helm-vault.
Goal, to make the code more supported.
The idea for this project (helm-vault) comes from Helm-Secrets.
Special thanks to the Python Discord server.