helm-secrets.adoc

Working with Helm secrets

Table of Contents

• Overview
• Local Setup
• Editing Secrets
• Using Secrets in Pipelines
• Adding more recipients to encrypted files

The ods-pipeline-helm-deploy task supports encrypted secrets via the helm-secrets plugin, using sops and age under the hood.

Note	Storing secrets, even in encrypted form, in Git repositories should be avoided if possible. Prefer to use a secrets management solution like the External Secrets Operator. The remainder of the guide explains how to handle the secrets in Git if you really need or want to do this.

Overview

helm-secrets supports different ways to encrypt secrets at rest. The ods-pipeline-helm-deploy task supports age key encryption. In a nutshell, the content is encrypted using a list of age public keys. Owners of the corresponding age secret keys can decrypt the content. As such, you must encrypt the content against an age public key and the corresponding age secret key must be made available to ods-pipeline-helm-deploy.

Local Setup

To begin with, make sure you have helm (including the helm-secrets plugin), sops and age installed.

Further, you’ll need an age key to encrypt and/or decrypt secret files. If you do not have an age key yet or want to create a new one for this purpose, you can generate one via age-keygen. As described in the sops documentation, when decrypting using age, sops will look for a text file name keys.txt located in a sops subdirectory of your user configuration directory. Therefore it is best to place your age key in that directory. On Linux, this would be $XDG_CONFIG_HOME/sops/age/keys.txt (if $XDG_CONFIG_HOME is not set, it is usually $HOME/.config). On macOS, this would be $HOME/Library/Application\ Support/sops/age/keys.txt. On Windows, this would be %AppData%\sops\age\keys.txt.

Warning

If you do not use your user configuration directory as the location of your age key, you need to specify its location via SOPS_AGE_KEY_FILE.

A key pair for encryption can be created by running:

mkdir -p <your_user_config_dir>/sops/age
age-keygen -o <your_user_config_dir>/sops/age/keys.txt

Now you are ready to work with secret files!

Editing Secrets

In the age keys.txt file you see a commented line with #public key: <public key value>. Take this public key and use it to create an encrypted version of your not-yet encrypted secrets.yaml:

sops --encrypt --age <your_age_public_key> --in-place secrets.yaml

Note	you can add multiple recipients (e.g.: each team member has its own age key) comma-separated:

sops --encrypt --age <your_age_public_key>,<another_age_public_key> --in-place secrets.yaml

From now on, you can also edit the secrets through a simpler interface provided by the helm-secrets plugin:

helm secrets edit secrets.yaml

Next to the edit command, the helm-secrets plugin offers a few other commands to work with secrets. See all of them via helm secrets --help.

It is common practice ot use secrets. as a prefix and .yaml as extension for your secret files. The ods-pipeline-helm-deploy task will automatically pick up secrets.yaml and secret files corresponding to the target environment, see the ods-pipeline-helm-deploy task documentation.

Using Secrets in Pipelines

Once you have encrypted secrets, the ods-pipeline-helm-deploy task needs to decrypt them on the fly. In order to do this, it needs access to an age key which can decrypt the content. You can expose this to the task via a Kubernetes Secret resource. You can create such a resource containing a new age key by running:

age-keygen | kubectl create secret generic helm-secrets-age-key \
  --namespace=<your cd namespace> \
  --from-file=key.txt=/dev/stdin

This will create a Secret named helm-secrets-age-key in the namespace you specify. The age key is then the value of the field key.txt. The secret will automatically be detected by the ods-pipeline-helm-deploy task, and the age key will be loaded via SOPS_AGE_KEY_FILE so that the helm-secrets plugin can use it. Note that the field must be named key.txt. If you wish to use a different secret name (e.g. to use different private keys for different repos in the same namespace), you may do so, by supplying a value for the age-key-secret parameter of the ods-pipeline-helm-deploy task.

Adding more recipients to encrypted files

If you want to give additional people access to view and edit secrets, you can do so via the following:

sops -r -i --add-age <another_age_public_key> secrets.yaml

More information can be found in sops documentation