README.md 4.8 KB
Newer Older
msvechla's avatar
msvechla committed
1
2
# Kubehiera

3
Lightweight tool to render go template files based on hierarchical data. Support for multiple encryption backends and fully compatible with hiera-eyaml. Designed with rendering Kubernetes deployments in mind and inspired by the well-known hiera.
msvechla's avatar
msvechla committed
4
5
6

## Getting Started

7
A good way of getting started is by looking at one of the examples provided in the [example folder](./example/). As a bare-minium you will need a hiera.yml file. You can also see usage information by running `./kubehiera --help`
msvechla's avatar
msvechla committed
8

9
10
11
12
### Download the latest release

We provide automated builds for all major platforms. You can find all releases in our [tags](https://gitlab.com/msvechla/kubehiera/tags) section. Simply click on downloads and select "artifacts" to get the desired version. Alternatively feel free to build the latest release from master yourself.

13
### Setting up your hierarchy
msvechla's avatar
msvechla committed
14

15
Kubehiera requires one single configuration file, which defines the hierarchy used when rendering your templates and configuration for crypt backends.
msvechla's avatar
msvechla committed
16

17
18
19
20
21
22
The hiera.yml file contains the following configuration:

| Config Key       | Type          | Description                |
| ---------------- |:-------------:| -------------------------- |
| `hierarchy`      | array         | Dynamic list of data files |
| `cryptobackends` | map           | Currently supports `pkcs7` |
msvechla's avatar
msvechla committed
23

24
25
26
27
28
29
30
31
32
33
34
35
```yaml
---
hierarchy:
  - datacenter/{{ .datacenter }}.yml
  - environment/{{ .environment }}.yml
  - common.yml

cryptobackends:
  pkcs7:
    private_key: "key.pem"
    public_key: "cert.pem"
```
36
*Examplary hiera.yml file from [example/data/hiera.yml](./example/data/hiera.yml)*
msvechla's avatar
msvechla committed
37

38
`hierarchy` is read from bottom to top. Configuration at a higher level overrides configuration at a lower hierarchical level. You can use go-template syntax to define input data files based on variables.
msvechla's avatar
msvechla committed
39

40
`cryptobackends` currently only supplies coniguration for the pkcs7 cryotobackend. `private_key`and `public_key` contain the relative paths to the correspondent files starting from the location of the hiera.yml
41
### Rendering Templates
msvechla's avatar
msvechla committed
42

43
The main focus of Kubehiera is to render template files based on hierarchical data. This is done by specifying the path to your hiera.yml, the template file you want to render and some environment configuration:
msvechla's avatar
msvechla committed
44

45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
```
./kubehiera render -p example/data/hiera.yml example/configmap.yml -e "environment:prod" -e "datacenter:ams01"
```
This will render the template file `example/configmap.yml` by using values defined in the data files, which are referenced in the `example/data/hiera.yml`. Additionally we supply environment configuration with the `-e <key:value>` option. This will be used when walking the hiera.yml to select the desired data.

## Encrypting sensitive data using CryptoBackends

Currently Kubehiera support two different CryptoBackends. **ENV** and **PKCS7**. CryptoBackends can be used in any of your data yaml files by stating ```ENC[BACKEND,VALUE]```. For more details on the specific backends, see below.

### ENV CryptoBackend
The ENV CryptoBackend allows you to retrieve sensitive data from environment variables. This has been established as best practice for example by the [twelve-factor app](https://12factor.net/).

To use the data from the "password" environment variable inside any of your data yaml files, you can simply use: ```ENC[ENV,password]```. During the rendering process, this will then be replaced with the actual value.

### PKCS7 CryptoBackend
The PKCS7 backend can be used to encrypt sensitive data, which then can safely be stored inside your git repository. The CryptoBackend is fully compatible with [hiera-eyaml](https://github.com/voxpupuli/hiera-eyaml), so you can use your existing encrypted hiera data files with Kubehiera  by specifying your keys inside the ```hiera.yml```.
msvechla's avatar
msvechla committed
61

62
63
64
65
66
67
68
69
70
71
72
If you do not have any existing keypairs, you can generate them by specifying ```./kubehiera setup -c pkcs7```. After configuring them inside your ```hiera.yml``` you are ready to use encrypted values inside your data yaml files.

To encrypt data you can use the integrated encryption tool:
```
./kubehiera encrypt -s "HelloThisIsASecret" -p example/data/hiera.yml
```
Afterwards you can use the encrypted value in any of your hiera data files, e.g.:
```yaml
---
mypass: ENC[PKCS7,MIICqgYJKoZ...]
```
msvechla's avatar
msvechla committed
73
74
75
76
77
78
79

## Contributing

Please read [CONTRIBUTING.md]() for details on our code of conduct, and the process for submitting pull requests to us.

## Versioning

80
We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://gitlab.com/msvechla/kubehiera/tags).
msvechla's avatar
msvechla committed
81
82
83

## Authors

84
* **Marius Svechla** - *Initial work*
msvechla's avatar
msvechla committed
85

86
See also the list of [contributors](https://gitlab.com/msvechla/kubehiera/graphs/master) who participated in this project.
msvechla's avatar
msvechla committed
87
88
89
90
91
92

## License


## Acknowledgments

93
* [Hiera](https://github.com/puppetlabs/hiera) - for being the inspiration of this tool