diff options
Diffstat (limited to 'ops/kontemplate/README.md')
| -rw-r--r-- | ops/kontemplate/README.md | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/ops/kontemplate/README.md b/ops/kontemplate/README.md new file mode 100644 index 000000000000..803a1c4f16fb --- /dev/null +++ b/ops/kontemplate/README.md @@ -0,0 +1,185 @@ +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). + +[Helm]: https://helm.sh/ +[releases page]: https://github.com/tazjin/kontemplate/releases |