kustomize-sopssecretgenerator

SecretGenerator ❤ sops

Why use this?

Kustomize is a great tool for implementing a GitOps workflow. When a repository describes the entire system state, it often contains secrets that need to be encrypted at rest. Mozilla's sops is a simple and flexible tool that is very suitable for that task.

This Kustomize plugin allows you to create Secrets transparently from sops-encrypted files during resource generation. It is explicitly modeled after the builtin SecretGenerator plugin. Because it is an exec plugin, it is not tied to the specific compilation of Kustomize, like Go plugins are.

Since version 1.5.0, the plugin can be used as a KRM Function.

Credit goes to Seth Pollack for the Kustomize Secret Generator Plugins KEP and subsequent implementation that made this possible.

Installation

SopsSecretGenerator is available as a binary, or as a Docker image.

Binary

Download the SopsSecretGenerator binary for your platform from the GitHub releases page and make it executable.

For example, to install version 1.6.0 on Linux:

VERSION=1.6.0 PLATFORM=linux ARCH=amd64
curl -Lo SopsSecretGenerator "https://github.com/goabout/kustomize-sopssecretgenerator/releases/download/v${VERSION}/SopsSecretGenerator_${VERSION}_${PLATFORM}_${ARCH}"
chmod +x SopsSecretGenerator

You do not need to install the sops binary for the plugin to work. The plugin includes and calls sops internally.

Docker image

See the goabout/kustomize-sopssecretgenerator image at Docker Hub.

Usage

Create some encrypted values using sops:

echo FOO=secret >secret-vars.env
sops -e -i secret-vars.env

echo secret >secret-file.txt
sops -e -i secret-file.txt

Exec KRM Function

Although the generator can run in a Docker container, any real usage requires to access to local resources such as the filesystem or a PGP socket. This example calls the binary directly.

Add a generator to your kustomization:

cat <<. >kustomization.yaml
generators:
  - generator.yaml
.

cat <<. >generator.yaml
apiVersion: goabout.com/v1beta1
kind: SopsSecretGenerator
metadata:
  annotations:
   config.kubernetes.io/function: |
      exec:
        path: ./SopsSecretGenerator
  name: my-secret
envs:
  - secret-vars.env
files:
  - secret-file.txt
.

(Change the path to the SopsSecretGenerator binary to suit your installation. Kustomize will use the binary search path, $PATH, if you use a bare command.)

Run kustomize build with the --enable-alpha-plugins and --enable-exec flags:

kustomize build --enable-alpha-plugins --enable-exec

The output is a Kubernetes secret containing the decrypted data:

apiVersion: v1
data:
  FOO: J3NlY3JldCc=
  secret-file.txt: c2VjcmV0Cg==
kind: Secret
metadata:
  name: my-secret-6d2fchb89d

Legacy Plugin

First, install the plugin to $XDG_CONFIG_HOME: (By default, $XDG_CONFIG_HOME points to $HOME/.config on Linux and OS X, and %LOCALAPPDATA% on Windows.)

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/kustomize/plugin/goabout.com/v1beta1/sopssecretgenerator"
mv SopsSecretGenerator "${XDG_CONFIG_HOME:-$HOME/.config}/kustomize/plugin/goabout.com/v1beta1/sopssecretgenerator"

Add a generator to your kustomization:

cat <<. >kustomization.yaml
generators:
  - generator.yaml
.

cat <<. >generator.yaml
apiVersion: goabout.com/v1beta1
kind: SopsSecretGenerator
metadata:
  name: my-secret
envs:
  - secret-vars.env
files:
  - secret-file.txt
.

Generator Options

Like SecretGenerator, SopsSecretGenerator supports the generatorOptions fields. Additionally, labels and annotations are copied over to the Secret. Data key-values ("envs") can be read from dotenv, INI, YAML and JSON files. If the data is a file and the Secret data key needs to be different from the filename, you can specify the key by adding desiredKey=filename instead of just the filename.

An example showing all options:

apiVersion: goabout.com/v1beta1
kind: SopsSecretGenerator
metadata:
  name: my-secret
  labels:
    app: my-app
  annotations:
    create-by: me
behavior: create
disableNameSuffixHash: true
envs:
  - secret-vars.env
  - secret-vars.ini
  - secret-vars.yaml
  - secret-vars.json
files:
  - secret-file1.txt
  - secret-file2.txt=secret-file2.sops.txt
type: Opaque

Using SopsSecretsGenerator with ArgoCD

SopsSecretGenerator can be added to ArgoCD by patching an initContainer into the ArgoCD provided install.yaml.

Alternatives

There are a number of other plugins that can serve the same function:

• viaduct-ai/kustomize-sops
• Agilicus/kustomize-sops
• barlik/kustomize-sops
• monopole/sopsencodedsecrets
• omninonsense/kustomize-sopsgenerator
• whatever-company/secretgen

Additionally, there are other ways to use sops-encrypted secrets in Kubernetes:

• isindir/sops-secrets-operator
• craftypath/sops-operator
• jkroepke/helm-secrets
• dschniepp/sealit

Most of these projects are in constant development. I invite you to check them out and pick the project that best fits your goals.

Development

You will need Go 1.17 or higher to develop and build the plugin.

Test

Run all tests:

make test

In order to create encrypted test data, you need to import the secret key from testdata/keyring.gpg into your GPG keyring once:

cd testdata
gpg --import keyring.gpg

You can then use sops to create encrypted files:

sops -e -i newfile.txt

Build

Create a binary for your system:

make

The resulting executable will be named SopsSecretGenerator.

Release

This project uses GitHub Actions and goreleaser to publish releases on GitHub.

First, don't forget to update the documentation for the new version you are going to release.

Then create a Git tag for the release:

VERSION=X.X.X
git tag -a v$VERSION -m "Version $VERSION"

And push it to GitHub:

git push

The GitHub Actions workflow will build and release the binaries automatically.