helm-secrets

Usage

Decrypt secrets via plugin command

Wraps the whole helm command. Slow on multiple value files.

helm secrets upgrade name . -f secrets.yaml

Decrypt secrets via protocol handler

Run decrypted command on specific value files.

helm upgrade name . -f secrets://secrets.yaml

See: USAGE.md for more information

Installation and Dependencies

SOPS

If you use sops with helm-secrets, the sops CLI tool is needed.

You can install it manually using Homebrew:

brew install sops

Download: https://github.com/mozilla/sops/releases/latest

sops 3.2.0 is required at minimum.

Hashicorp Vault

If you use Vault with helm-secrets, the vault CLI tool is needed.

You can install it manually using Homebrew:

brew install vault

Download: https://www.vaultproject.io/downloads

envsubst

If you have stored you secret inside environment variables, you could use the envsubst driver.

brew install gettext

SOPS git diff

Git config part is installed with the plugin, but to be fully functional the following needs to be added to the .gitattributes file in the root directory of a charts repo:

secrets.yaml diff=sopsdiffer
secrets.*.yaml diff=sopsdiffer

More info on sops page

By default, helm plugin install does this for you.

Using Helm plugin manager

Install a specific version (recommend)

helm plugin install https://github.com/jkroepke/helm-secrets --version v3.8.2

Install latest unstable version from main branch

helm plugin install https://github.com/jkroepke/helm-secrets

Find the latest version here: https://github.com/jkroepke/helm-secrets/releases

Manual installation

Latest version

Windows (inside cmd, needs to be verified)

curl -LsSf https://github.com/jkroepke/helm-secrets/releases/latest/download/helm-secrets.tar.gz | tar -C "%APPDATA%\helm\plugins" -xzf-

MacOS / Linux

curl -LsSf https://github.com/jkroepke/helm-secrets/releases/latest/download/helm-secrets.tar.gz | tar -C "$(helm env HELM_PLUGINS)" -xzf-

Specific version

Windows (inside cmd, needs to be verified)

curl -LsSf https://github.com/jkroepke/helm-secrets/releases/download/v3.8.2/helm-secrets.tar.gz | tar -C "%APPDATA%\helm\plugins" -xzf-

MacOS / Linux

curl -LsSf https://github.com/jkroepke/helm-secrets/releases/download/v3.8.2/helm-secrets.tar.gz | tar -C "$(helm env HELM_PLUGINS)" -xzf-

Installation on Helm 2

Helm 2 doesn't support downloading plugins. Since unknown keys in plugin.yaml are fatal plugin installation needs special handling.

Error on Helm 2 installation:

# helm plugin install https://github.com/jkroepke/helm-secrets
Error: yaml: unmarshal errors:
  line 12: field platformCommand not found in type plugin.Metadata

Workaround:

Install helm-secrets via manual installation, but extract inside helm2 plugin directory e.g.: $(helm home)/plugins/

Strip platformCommand from plugin.yaml like:

sed -i '/platformCommand:/,+2 d' "${HELM_HOME:-"${HOME}/.helm"}/plugins/helm-secrets*/plugin.yaml"

Done

Client here for an example!

Explicitly specify sops binary

If sops is installed at the non-default location or if you have multiple versions of sops on your system, you can use HELM_SECRETS_SOPS_PATH to explicitly specify the sops binary to be used.

# Example for in-tree drivers via environment variable
HELM_SECRETS_SOPS_PATH=/custom/location/sops helm secrets view ./tests/assets/helm_vars/secrets.yaml

Change secret driver

It's possible to use another secret driver then sops, e.g. Hasicorp Vault.

Start by a copy of sops driver and adjust to your own needs.

The custom driver can be load via HELM_SECRETS_DRIVER parameter or -d option (higher preference):

Example for in-tree drivers via option

helm secrets -d sops view ./tests/assets/helm_vars/secrets.yaml

Example for in-tree drivers via environment variable

HELM_SECRETS_DRIVER=vault helm secrets view ./tests/assets/helm_vars/secrets.yaml

Example for out-of-tree drivers

helm secrets -d ./path/to/driver.sh view ./tests/assets/helm_vars/secrets.yaml

Pull Requests are much appreciated.

The driver option is a global one. A file level switch isn't supported yet.

Pass additional arguments to secret driver

helm secrets -a "--verbose" view ./tests/assets/helm_vars/secrets.yaml

results into:

[PGP]    INFO[0000] Decryption succeeded                          fingerprint=D6174A02027050E59C711075B430C4E58E2BBBA3
[SOPS]   INFO[0000] Data key recovered successfully
[SOPS]   DEBU[0000] Decrypting tree
[helm-secrets] Decrypt: tests/assets/values/sops/secrets.yaml
==> Linting examples/sops
[INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed

[helm-secrets] Removed: tests/assets/values/sops/secrets.yaml.dec

Main features

The current version of this plugin using mozilla/sops by default as backend.

Hashicorp Vault is supported as secret source since v3.2.0, too. In addition, sops support vault since v3.6.0 natively.

What kind of problems this plugin solves:

Simple replaceable layer integrated with helm command for encrypting, decrypting, view secrets files stored in any place.
On the fly decryption and cleanup for helm install/upgrade with a helm command wrapper

If you are using sops (used by default) you have some additional features:

An additional documentation, resources and examples can be found here.

ArgoCD support

helm-secrets could detect an ArgoCD environment by the ARGOCD_APP_NAME environment variable. If detected, HELM_SECRETS_QUIET is set to true.

Terraform support

The terraform helm provider does not support downloader plugins.

An example how to use helm-secrets with terraform could be found in contrib/terraform.

Moving parts of project

scripts/run.sh - Main helm-secrets plugin code for all helm-secrets plugin actions available in helm secrets help after plugin install
scripts/drivers - Location of the in-tree secrets drivers
scripts/commands - Sub Commands of helm secrets are defined here.
scripts/lib - Common functions used by helm secrets.
scripts/wrapper - Wrapper scripts for Windows systems.
tests - Test scripts to check if all parts of the plugin work. Using test assets with PGP keys to make real tests on real data with real encryption/decryption. See tests/README.md for more informations.
examples - Some example secrets.yaml

Copyright and license

Licensed under the Apache License, Version 2.0

oofnikj/helm-secrets