Skip to content

Commit

Permalink
Merge pull request zendesk#15 from futuresimple/readme_update
Browse files Browse the repository at this point in the history 
Readme updates
  • Loading branch information
@szibis
szibis authored Jul 11, 2017
2 parents cd012c6 + f9dd520 commit da42d40
Showing 1 changed file with 131 additions and 12 deletions.
143 changes: 131 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@

# Plugin for secrets management in Helm

Developed and used on all environments in [BaseCRM](https://getbase.com/).
Developed and used in all environments in [BaseCRM](https://getbase.com/).

First internal version of the plugin used pure PGP and the whole secret file was encrypted as one.
A first internal version of the plugin used pure PGP and the whole secret file was encrypted as one.

A current version of the plugin using Golang sops as backend which could be integrated in future into Helm itself, but currently, it is only shell wrapper.

Expand All @@ -21,11 +21,21 @@ What kind of problems this plugin solves:
* On the fly decryption and cleanup for helm install/upgrade with this plugin helm bash command wrapper
* [Multiple key management solutions like PGP and AWS KMS at same time](https://github.com/mozilla/sops#using-sops-yaml-conf-to-select-kms-pgp-for-new-files)
* [Simple adding/removing keys](https://github.com/mozilla/sops#adding-and-removing-keys)
* [With AWS KMS permissions managment for keys](https://aws.amazon.com/kms/)
* [Secrets files directory tree seperation with recursive .sops.yaml files search](https://github.com/mozilla/sops#using-sops-yaml-conf-to-select-kms-pgp-for-new-files)
* [Extracting sub elements from encrypted file structure](https://github.com/mozilla/sops#extract-a-sub-part-of-a-document-tree)
* [With AWS KMS permissions management for keys](https://aws.amazon.com/kms/)
* [Secrets files directory tree separation with recursive .sops.yaml files search](https://github.com/mozilla/sops#using-sops-yaml-conf-to-select-kms-pgp-for-new-files)
* [Extracting sub-elements from encrypted file structure](https://github.com/mozilla/sops#extract-a-sub-part-of-a-document-tree)
* [Encrypt only part of a file if needed](https://github.com/mozilla/sops#encrypting-only-parts-of-a-file). [Example encrypted file](https://github.com/mozilla/sops/blob/master/example.yaml)

## Moving parts of project

```helm-wrapper``` - It is not a part of Helm project itself. It is the just simple wrapper in the shell that runs helm bellow but wrapping secrets decryption and cleaning on-the-fly, before and after Helm run. Created from install-binary.sh in helm-secrets plugin install process as hook action making the symlink to wrapper.sh. This should be used as default command to operate with Helm client with helm-secrets installed.

```test.sh``` - Test script to check if all parts of the plugin work. Using example dir with vars structure and PGP keys to make real tests on real data with real encryption/decryption.

```install-binary.sh``` - Script used as the hook to install helm-wrapper, download and install sops and install git diff configuration for helm-secret files.

```secrets.sh``` - Main helm-secrets plugin code for all helm-secrets plugin actions available in ```helm secrets help``` after plugin install

## Install

#### SOPS install
Expand Down Expand Up @@ -61,13 +71,11 @@ curl -L $TARBALL_URL | tar -C $(helm home)/plugins -xzv
```

#### Helm-wrapper configuration
By default helm-wrapper is configured to not encrypt/decrypt secrets.yaml in charts templates.
Set your own options as ENV variables if you like:
By default helm-wrapper is not configured to encrypt/decrypt secrets.yaml in charts templates. They are templates and values from specific secrets/value files should e used in this templates as reference from helm itself.
Set you own options as ENV variables if you like overwrite default kms enabled and decrypt charts disabled.
```
DECRYPT_CHARTS=false helm-wrapper ....
```
If you'd like to use it in a different way just change this line.

## Usage and examples

```
Expand All @@ -83,9 +91,64 @@ $ helm secrets help
```
Any of this command have its own help

## Use case
## Use case and workflow

#### Usage examples

##### Decrypt
```
$ helm secrets dec example/helm_vars/projectX/production/us-east-1/java-app/secrets.yaml
Decrypting example/helm_vars/projectX/production/us-east-1/java-app/secrets.yaml
```
As the output you will get example/helm_vars/projectX/production/us-east-1/java-app/secrets.yaml.dec with decrypted secrets inside
```
secret_production_projectx: secret_foo_123
```
##### Encrypt
Decrypt
```
$ helm secrets dec example/helm_vars/projectX/production/us-east-1/java-app/secrets.yaml
Decrypting example/helm_vars/projectX/production/us-east-1/java-app/secrets.yaml
```
Now encrypt
```
$ helm secrets enc example/helm_vars/projectX/production/us-east-1/java-app/secrets.yaml
Encrypting example/helm_vars/projectX/production/us-east-1/java-app/secrets.yaml
Encrypted example/helm_vars/projectX/production/us-east-1/java-app/secrets.yaml
```
##### View
With this option you will get decrypted file on stdout
```
$ helm secrets view example/helm_vars/projectX/production/us-east-1/java-app/secrets.yaml
secret_production_projectx: secret_foo_123
```
##### Edit
Currently will open vim with decrypted data from secret and on save will encrypt file with new edited data. If you quit without any modification no changes will be saved.
```
$ helm secrets edit example/helm_vars/projectX/production/us-east-1/java-app/secrets.yaml
```
There is new feature in SOPS master that allows using $EDITOR to spcify editor used by sops but not released yet.

##### Clean

We use vars for Helm Charts from separate directory tree with structure like this:
Now clean dec file after manual decrypt
```
$ helm secrets clean example/helm_vars/projectX/production/us-east-1/java-app/
example/helm_vars/projectX/production/us-east-1/java-app/secrets.yaml.dec
```
If you use git there is commit hook that prevents commiting decrypted files and youo can add all *.dec files in you charts project ```.gitignore``` file.

#### Summary

* Values/Secrets data are not a part of the chart. You need to manage your values, public charts contains mostly defaults without secrets - data vs code
* To use the helm-secrets plugin you should build your ```.sops.yaml``` rules to make everything automatic
* Use helm secrets <enc|dec|view|edit> to everyday work with you secret yaml files
* Use version control systems like GIT to work in teams and get history of versions
* Everyday search keys is simple even with encrypted files or decrypt on-the-fly with git diff config included
* With example helm_vars you can manage multiple world locations with multiple projects that contain multiple environments
* With helm-wrapper you can easily run helm install/upgrade/rollback with secrets files included as ```-f``` option from you helm_vars values dir tree.

We use vars for Helm Charts from separate directory tree with the structure like this:
```
helm_vars/
├── .sops.yaml
Expand Down Expand Up @@ -125,7 +188,7 @@ helm_vars/
└── values.yaml
```
As you can see we can run different PGP or KMS keys per project, globally or per any tree level. Thanks to this we can isolate tree on different CI/CD instances using same GIT repository.
As we use simple -f option when running helm-wrapper we can just use encrypted secrets.yaml and all this secrets will be decrypted and cleaned on the fly before and after helm run.
As we use simple -f option when running helm-wrapper we can just use encrypted secrets.yaml and all these secrets will be decrypted and cleaned on the fly before and after helm run.

```.sops.yaml``` file example
```
Expand All @@ -143,6 +206,62 @@ Multiple KMS and PGP are allowed.

Everything is described in SOPS docs - links in this project description.

## Helm Wrapper

Running helm to install/upgrade chart with our secret files is simple with helm-wrapper which will decrypt on-the-fly and use decrypted secret files specified by us.
Real example of helm-wrapper usage with simple java helloworld application.
```
AWS_PROFILE=production helm-secrets upgrade --install --timeout 600 --wait helloworld stable/java-app --kube-context=production --namespace=projectx --set global.app_version=bff8fc4 -f helm_vars/projectx/sandbox/us-east-1/java-app/helloworld/secrets.yaml -f helm_vars/projectx/sandbox/us-east-1/java-app/helloworld/values.yaml -f helm_vars/secrets.yaml -f helm_vars/values.yaml
>>>>>> Decrypt
Decrypting helm_vars/projectx/sandbox/us-east-1/java-app/helloworld/secrets.yaml
>>>>>> Decrypt
Decrypting helm_vars/secrets.yaml
Release "helloworld" has been upgraded. Happy Helming!
LAST DEPLOYED: Fri May 5 13:27:01 2017
NAMESPACE: projectx
STATUS: DEPLOYED
RESOURCES:
==> extensions/v1beta1/Deployment
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
helloworld 3 3 3 2 1h
==> v1/Secret
NAME TYPE DATA AGE
helloworld Opaque 10 1h
==> v1/ConfigMap
NAME DATA AGE
helloworld 2 1h
==> v1/Service
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
helloworld 100.65.221.245 <none> 8080/TCP 1h
NOTES:
Deploy success helloworld-bff8fc4 in namespace projectx
>>>>>> Cleanup
helm_vars/projectx/sandbox/us-east-1/java-app/helloworld/secrets.yaml.dec
helm_vars/secrets.yaml.dec
```
You can see that we use global secret file and specific for this app in this project/environment/region secret. We use some plain value files next to secrets. We use values from secrets in some secrets template in helloworld application chart template and some values are used in the configmap template in the same chart. Some values are added as env variables in deployment manifest templates in the chart. As you can see we can use secrets and values in helm in many ways. Everything depends on use case.

Even when helm failed then decrypted files are cleaned
```
AWS_PROFILE=production helm-wrapper upgrade --install --timeout 600 --wait helloworld stable/java-app --kube-context=wrongcontext --namespace=projectx --set global.app_version=bff8fc4 -f helm_vars/projectx/sandbox/us-east-1/java-app/helloworld/secrets.yaml -f helm_vars/projectx/sandbox/us-east-1/java-app/helloworld/values.yaml -f helm_vars/secrets.yaml -f helm_vars/values.yaml
>>>>>> Decrypt
Decrypting helm_vars/projectx/sandbox/us-east-1/java-app/helloworld/secrets.yaml
>>>>>> Decrypt
Decrypting helm_vars/secrets.yaml
Error: could not get kubernetes config for context 'wrongcontext': context "wrongcontext" does not exist
>>>>>> Cleanup
helm_vars/projectx/sandbox/us-east-1/java-app/helloworld/secrets.yaml.dec
helm_vars/secrets.yaml.dec
```
## Tips

#### Prevent committing decrypted files to git
Expand Down

0 comments on commit da42d40

Please sign in to comment.