jmclean-starburst / helm-secrets

A helm plugin that help manage secrets with Git workflow and store them anywhere

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: docs/USAGE.md for more information

ArgoCD

For running helm-secrets with ArgoCD, see docs/ARGOCD.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.

vals

vals is a tool for managing configuration values and secrets form various sources.

It supports various backends including:

• Vault
• AWS SSM Parameter Store
• AWS Secrets Manager
• AWS S3
• GCP Secrets Manager
• Azure Key Vault
• SOPS-encrypted files
• Terraform State
• Plain File

All clients are integrated into vals, no additional tools required.

Download: https://github.com/variantdev/vals/releases/latest

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

Doppler

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

brew install dopplerhq/cli/doppler

You need to make sure chart folder or parent one is in correct CLI's scope with enough access to project.

Using Helm plugin manager

Install a specific version (recommend)

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

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.10.0/helm-secrets.tar.gz | tar -C "%APPDATA%\helm\plugins" -xzf-

MacOS / Linux

curl -LsSf https://github.com/jkroepke/helm-secrets/releases/download/v3.10.0/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:

1. Install helm-secrets via manual installation, but extract inside helm2 plugin directory e.g.: $(helm home)/plugins/
2. Strip platformCommand from plugin.yaml like:

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

3. Done

Client here for an example!

Explicitly specify binary path

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_$DRIVER_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
HELM_SECRETS_VALS_PATH=/custom/location/vals 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:

• Support for YAML/JSON structures encryption - Helm YAML secrets files
• Encryption per value where visual Diff should work even on encrypted files
• On the fly decryption for git diff
• Multiple key management solutions like PGP, AWS KMS and GCP KMS at same time
• Simple adding/removing keys
• With AWS KMS permissions management for keys
• Secrets files directory tree separation with recursive .sops.yaml files search
• Extracting sub-elements from encrypted file structure
• Encrypt only part of a file if needed. Example encrypted file

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.

See USAGE.md for example.

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

© 2020-2021 Jan-Otto Kröpke (jkroepke)

© 2017-2020 Zendesk

Licensed under the Apache License, Version 2.0