Secure secret management for Kubernetes (with gpg, Google Cloud KMS and AWS KMS backends).
In short, it allows you to encrypt Secrets so that they can be stored in VCS along
with the rest of resources.
An example of encrypted Secret is shown below (note that only the "data" is encrypted (and that keys are left untouched)):
apiVersion: v1
kind: Secret
metadata:
name: myapp-default-0
type: Opaque
data:
KEY: TUFkWD1iuKs=.O....D...=
ANOTHER_KEY: iOy1nf90+M6FrrEIoymN6cOSUYM=.E...=.q...=
# ...
The nice thing about this approach (compared to complete file encryption) is that git diff
and git merge
become
so much more user-friendly (+ you can ascertain that specific entry is present even if you don't have the key to decrypt the secret).
kubesec
is written in Go, works with (or without) Yubikey ❤.
For general-purpose secret management, take a look at mozilla/sops
(kubesec
's drawn a lot of inspiration from it).
curl -sSL https://github.com/shyiko/kubesec/releases/download/0.9.2/kubesec-0.9.2-darwin-amd64 \
-o kubesec && chmod a+x kubesec && sudo mv kubesec /usr/local/bin/
Verify PGP signature (optional but recommended):
curl -sSL https://github.com/shyiko/kubesec/releases/download/0.9.2/kubesec-0.9.2-darwin-amd64.asc \
-o kubesec.asc
curl -sS https://keybase.io/shyiko/pgp_keys.asc | gpg --import
gpg --verify kubesec.asc /usr/local/bin/kubesec
gpg
can be installed withbrew install gnupg
... with Homebrew
brew install shyiko/kubesec/kubesec
brew install shyiko/kubesec/kubesec --with-short-name # install as "ksec"
brew install shyiko/kubesec/kubesec
is equivalent tobrew tap shyiko/kubesec && brew install kubesec
.
curl -sSL https://github.com/shyiko/kubesec/releases/download/0.9.2/kubesec-0.9.2-linux-amd64 \
-o kubesec && chmod a+x kubesec && sudo mv kubesec /usr/local/bin/
Verify PGP signature (optional but recommended):
curl -sSL https://github.com/shyiko/kubesec/releases/download/0.9.2/kubesec-0.9.2-linux-amd64.asc \
-o kubesec.asc
curl -sS https://keybase.io/shyiko/pgp_keys.asc | gpg --import
gpg --verify kubesec.asc /usr/local/bin/kubesec
Download executable from the Releases page.
If you plan to use gpg:
... but don't have a valid PGP key, see GitHub Help - Generating a new GPG key on how to generate one.
gpg (tested: 2.0+; recommended: 2.1+) must be available on the PATH.
It's also highly recommended to set up gpg-agent to avoid constant passphrase re-entry.
# encrypt existing Secret (see `kubesec create` below on how to create encrypted secret from scratch)
kubesec encrypt secret.yml
# same as above but output is written back to secret.yml (instead of stdout)
kubesec encrypt -i secret.yml
# NOTE: if you don't specify --key - default PGP key will be used
# in other words, `kubesec encrypt secret.yml` is identical to
kubesec encrypt --key=pgp:default secret.yml
# NOTE: multiple --key|s can be specified if needed
# (and they don't have to be of the same type, i.e. `--key=pgp:... --key=arn:...`
# is perfectly valid)
# encrypt with PGP key ("pgp:" prefix is optional)
kubesec encrypt --key=pgp:6206C32E111611688694CF5530BDA87E3E71C268 secret.yml
# avoid gpgagent for pgp passprhase when encrypting with PGP key ("pgp:" prefix is optional)
kubesec encrypt --passphrase=<supersecret> --key=pgp:6206C32E111611688694CF5530BDA87E3E71C268 secret.yml
# encrypt with Google Cloud KMS key ("gcp:" prefix is optional)
#
# NOTE: you'll need either to `gcloud auth application-default login` or set
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
# before attempting secret encryption/decryption
#
# https://developers.google.com/identity/protocols/application-default-credentials#howtheywork
kubesec encrypt --key=gcp:<resource-id of Google Cloud KMS key> secret.yml
kubesec encrypt \
--key=gcp:projects/project-0/locations/global/keyRings/keyring-0/cryptoKeys/key-0 secret.yml
# encrypt with AWS KMS key ("aws:" prefix is optional)
#
# NOTE: you might need to `aws configure` (if you don't have ~/.aws/credentials already)
#
# http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html
kubesec encrypt --key=aws:<ARN of AWS KMS key> secret.yml
kubesec encrypt \
--key=aws:arn:aws:kms:us-west-1:000000000000:key/00000000-0000-0000-0000-000000000000 secret.yml
# add ...D89 key & drop ...310 key (leave all other keys untouched)
kubesec encrypt --key=+pgp:160A7A9CF46221A56B06AD64461A804F2609FD89 \
--key=-pgp:6206C32E111611688694CF5530BDA87E3E71C268 secret.yml
# NOTE: removal of a key will automatically result in data encryption key rotation
# you will also need to change all the secrets as whoever you removed from the chain of trust might
# still have access to the previous version of a file
# encrypt content of stdin
cat secret.yml | kubesec encrypt -
# create encrypted Secret from key=value pair(s) / file(s)
kubesec create secret-name \
--data key=value \
--data file:pki/ca.crt \
--data file:hostname.key=pki/private/server.key \
-o secret.enc.yml
# decrypt a Secret
# (usually combined with kubectl (`kubesec decrypt secret.enc.yml | kubectl apply -f -`))
kubesec decrypt secret.enc.yml
# decrypt without invoking gpgagent - useful for unattended interaction or for alternate keyrings
#
# You can prevent these lines ending up in history with a space
# see https://www.linuxjournal.com/content/using-bash-history-more-efficiently-histcontrol or https://superuser.com/questions/352788/how-to-prevent-a-command-in-the-zshell-from-being-saved-into-history
kubesec decrypt --keyring alternate.keyring --passphrase=<supersecret> secret.yml
# decrypt to a custom Go Template (http://golang.org/pkg/text/template) string
kubesec decrypt secret.enc.yml --cleartext --template='KEY={{ .data.KEY }}'
kubesec decrypt secret.enc.yml --cleartext \
--template=$'{{ range $k, $v := .data }}{{ $k }}={{ $v }}\n{{ end }}' > .env
# open decrypted Secret in $EDITOR (it will be automatically re-encrypted upon save)
kubesec edit -i secret.enc.yml
kubesec edit -i --key=<a-different-key-to-re-encrypt-with> secret.enc.yml
# same as above but secret.enc.yml will be created if it doesn't exist
kubesec edit -if secret.enc.yml
# batch editing (noninteractive)
kubesec patch -i secret.enc.yml --data key1=secret_string --data file:key2=path/to/file
# "decrypt, modify-in-any-way-you-like, re-encrypt"
kubesec decrypt --cleartext secret.enc.yml -o secret.yml
# edit secret.yml using your favourite editor / tool
kubesec encrypt --cleartext secret.yml -o secret.enc.yml --parent=secret.enc.yml
# --parent=path/to/encrypted/secret.enc.yml above is used to preserve keys, DEK and IVs (when safe)
# show information about the Secret (who has access to the "data", last modification date, etc)
kubesec introspect secret.enc.yml
# bash
source <(kubesec completion bash)
# zsh
source <(kubesec completion zsh)
-
can be used anywhere (where a file is expected) to referencestdin
.
(for more information seekubesec --help
)
kubesec create secret-name -d key=value -d file:path/to/file -o secret.enc.yml
kubesec decrypt secret.enc.yml | kubectl apply -f -
If you have docker
installed you don't need to download kubesec
binary just to try it out.
Instead, launch a container and start playing:
docker run -it --rm shyiko/kubesec-playground:0.9.2 /bin/bash
$ kubesec encrypt secret.yml
shyiko/kubesec-playground
image containsgpg
2.1+, kubesec, vim (as a default $EDITOR) and secret PGP key of Jean-Luc Picard (PGP fingerprint - 6206C32E111611688694CF5530BDA87E3E71C268).
Dockerfile is included within this repo.
- "data" values are encrypted with AES-GCM (each value is padded to a block-size (48 bytes by default) and then encrypted using a shared (resource-unique, randomly generated) 256-bit DEK & a 96-bit random IV).
- DEK is encrypted (and signed in case of PGP) with
--key
(s) before being stored in a Secret as# kubesec:<key type>:<key id>:...
(one entry for each--key
).
In addition to the above, kubesec also generates MAC (AES-GMAC, with AAD constructed from both the "data" and the --key
(s)). If MAC is missing or invalid -
decryption will fail (kubesec edit -i --recompute-mac <file>
can be used to recompute MAC when necessary (e.g. after git merge
)).
Please reach me at https://keybase.io/shyiko.
PREREQUISITE: go1.9+.
git clone https://github.com/shyiko/kubesec $GOPATH/src/github.com/shyiko/kubesec
cd $GOPATH/src/github.com/shyiko/kubesec
make fetch
go run kubesec.go
All code, unless specified otherwise, is licensed under the Apache-2.0 license.
Copyright (c) 2018 Stanley Shyiko.