about summary refs log tree commit diff
path: root/ops/kontemplate/README.md
blob: 774796c909495243c5f61980caf5e5d497292f33 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
Kontemplate - A simple Kubernetes templater
===========================================

[Kontemplate][] is a simple CLI tool that can take sets of Kubernetes resource
files with placeholders and insert values per environment.

This tool was made because in many cases all I want in terms of Kubernetes
configuration is simple value interpolation per environment (i.e. Kubernetes
cluster), but with the same deployment files.

In my experience this is often enough and more complex solutions such as
[Helm][] are not required.

Check out a Kontemplate setup example and the feature list below!

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**Table of Contents**

- [Kontemplate - A simple Kubernetes templater](#kontemplate---a-simple-kubernetes-templater)
    - [Features](#features)
    - [Example](#example)
    - [Installation](#installation)
        - [Homebrew](#homebrew)
        - [Arch Linux](#arch-linux)
        - [Building repeatably from source](#building-repeatably-from-source)
        - [Building from source](#building-from-source)
    - [Usage](#usage)
    - [Contributing](#contributing)

<!-- markdown-toc end -->

## Features

* [Simple, yet powerful templates](docs/templates.md)
* [Clean cluster configuration files](docs/cluster-config.md)
* [Resources organised as simple resource sets](docs/resource-sets.md)
* Integration with pass
* Integration with kubectl

## Example

Kontemplate lets you describe resources as you normally would in a simple folder structure:

```
.
├── prod-cluster.yaml
└── some-api
    ├── deployment.yaml
    └── service.yaml
```

This example has all resources belonging to `some-api` (no file naming conventions enforced at all!) in the `some-api`
folder and the configuration for the cluster `prod-cluster` in the corresponding file.

Lets take a short look at `prod-cluster.yaml`:

```yaml
---
context: k8s.prod.mydomain.com
global:
  globalVar: lizards
include:
  - name: some-api
    values:
      version: 1.0-0e6884d
      importantFeature: true
      apiPort: 4567
```

Those values are then templated into the resource files of `some-api`. That's it!

You can also set up more complicated folder structures for organisation, for example:

```
.
├── api
│   ├── image-api
│   │   └── deployment.yaml
│   └── music-api
│       └── deployment.yaml
│   │   └── default.json
├── frontend
│   ├── main-app
│   │   ├── deployment.yaml
│   │   └── service.yaml
│   └── user-page
│       ├── deployment.yaml
│       └── service.yaml
├── prod-cluster.yaml
└── test-cluster.yaml
```

And selectively template or apply resources with a command such as
`kontemplate apply test-cluster.yaml --include api --include frontend/user-page`
to only update the `api` resource sets and the `frontend/user-page` resource set.

## Installation

It is recommended to install Kontemplate from the [Nix](https://nixos.org/) package set,
where it is available since NixOS 17.09 as `kontemplate`.

If using Nix is not an option for you, several other methods of installation are
available:

### Binary releases

Signed binary releases are available on the [releases page][] for Linux, OS X, FreeBSD and
Windows.

Releases are signed with the GPG key `DCF34CFAC1AC44B87E26333136EE34814F6D294A`.

### Building from source

You can clone Kontemplate either by cloning the full TVL
[depot][https://code.tvl.fyi] or by just cloning the kontemplate
subtree like so:

    git clone https://code.tvl.fyi/depot.git:/ops/kontemplate.git

The `go` tooling can be used as normal with this cloned repository. In
a full clone of the depot, Nix can be used to build Kontemplate:

    nix-build -A ops.kontemplate

## Usage

You must have `kubectl` installed to use Kontemplate effectively.

```
usage: kontemplate [<flags>] <command> [<args> ...]

simple Kubernetes resource templating

Flags:
  -h, --help                 Show context-sensitive help (also try --help-long and --help-man).
  -i, --include=INCLUDE ...  Resource sets to include explicitly
  -e, --exclude=EXCLUDE ...  Resource sets to exclude explicitly

Commands:
  help [<command>...]
    Show help.

  template <file>
    Template resource sets and print them

  apply [<flags>] <file>
    Template resources and pass to 'kubectl apply'

  replace <file>
    Template resources and pass to 'kubectl replace'

  delete <file>
    Template resources and pass to 'kubectl delete'

  create <file>
    Template resources and pass to 'kubectl create'

```

Examples:

```
# Look at output for a specific resource set and check to see if it's correct ...
kontemplate template example/prod-cluster.yaml -i some-api

# ... maybe do a dry-run to see what kubectl would do:
kontemplate apply example/prod-cluster.yaml --dry-run

# And actually apply it if you like what you see:
kontemplate apply example/prod-cluster.yaml
```

Check out the feature list and the individual feature documentation above. Then you should be good to go!

## Contributing

Feel free to contribute pull requests, file bugs and open issues with feature suggestions!

Kontemplate is licensed under the GPLv3, a copy of the license and its terms can be found
in the `LICENSE` file.

Please follow the [code of conduct](CODE_OF_CONDUCT.md).

[Kontemplate]: http://kontemplate.works
[Helm]: https://helm.sh/
[releases page]: https://github.com/tazjin/kontemplate/releases