tvl-depot/ops/kontemplate
Moritz Sanft b16ddb54b0 chore(kontemplate): Migrate to Go modules
This switches to [Go modules](https://go.dev/blog/using-go-modules), which have now been the standard for dependency management in Go codebases for a while. In addition to initializing a new Go module, it also updates the paths of some gopkg.in dependencies, which are deprecated as well.

Change-Id: Ie5c9faa415a65ab76cbe59f4afb437a9250be392
Signed-off-by: Moritz Sanft <58110325+msanft@users.noreply.github.com>
Reviewed-on: https://cl.tvl.fyi/c/depot/+/11773
Tested-by: BuildkiteCI
Reviewed-by: tazjin <tazjin@tvl.su>
2024-06-10 07:40:05 +00:00
..
context style: format all Go code 2021-12-19 18:05:04 +00:00
docs docs(cluster-config): Correct term in cluster config doc 2019-12-20 22:32:06 +00:00
example chore(kontemplate): Prepare kontemplate for depot-merge 2019-12-20 22:13:07 +00:00
image chore(kontemplate): Prepare kontemplate for depot-merge 2019-12-20 22:13:07 +00:00
templater chore(kontemplate): Migrate to Go modules 2024-06-10 07:40:05 +00:00
util chore(kontemplate): Prepare kontemplate for depot-merge 2019-12-20 22:13:07 +00:00
.gitignore chore(kontemplate): Prepare kontemplate for depot-merge 2019-12-20 22:13:07 +00:00
build-release.sh chore(kontemplate): Prepare kontemplate for depot-merge 2019-12-20 22:13:07 +00:00
default.nix chore(kontemplate): Migrate to Go modules 2024-06-10 07:40:05 +00:00
go.mod chore(kontemplate): Migrate to Go modules 2024-06-10 07:40:05 +00:00
go.sum chore(kontemplate): Migrate to Go modules 2024-06-10 07:40:05 +00:00
LICENSE chore(kontemplate): Prepare kontemplate for depot-merge 2019-12-20 22:13:07 +00:00
main.go chore(kontemplate): Migrate to Go modules 2024-06-10 07:40:05 +00:00
README.md docs(kontemplate): Remove mention of kontemplate website 2021-09-18 12:35:47 +00:00
release.nix style: format entire depot with nixpkgs-fmt 2022-01-31 16:11:53 +00:00

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!

Table of Contents

Features

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:

---
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 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.