jk

README

jk

Caveat: jk is pre-1.0, and as such, features, commands, and APIs inevitably will change.

Releases within a minor version should be stable; we try to signal breaking changes ahead of time in ./docs/deprecations.md.

jk - configuration as code

jk is a data templating tool designed to help writing structured configuration files.

The main idea behind jk is to use a general purpose language for this task. They offer mature tooling, great runtimes, a well established ecosystem and many learning resources. jk uses Javascript and a runtime tailored for configuration.

Quick start

A good way to start with jk is to read our introduction tutorial. For more context head to our introduction blog post!

More complex examples

• A Kubernetes deployment written in Typescript
• Generating Kubernetes objects, using e.g., kustomize-like behavior
• Using jk with JavaScript libraries

Architecture & design

v8

jk itself is a Javascript runtime written in Go and embedding v8. It uses Ryan Dahl's v8worker2 to embed v8 and flatbuffers for the v8 ⟷ Go communication.

Hermeticity

While a general purpose language is great, configuration code can be made more maintainable by restricting what it can do. A nice property jk has to offer is being hermetic: if you clone a git repository and execute a jk script, the resulting files should be the same on any machine. To give concrete examples, this means the jk standard library doesn't support environment variables nor has any networking capability.

Library support

jk provides an unopinionated data templating layer. On top of the jk runtime, libraries provide APIs for users to write configuration.

• kubernetes: build Kubernetes objects
• grafana: build dashboard configs for Grafana

Roadmap

This project is still in early stages but future (exciting!) plans include:

• Reach the state of having Kubernetes examples working and well documented.
• Work on hermeticity. (eg. #110, #44, topic/hermeticity).
• Native typescript support (#54).
• HCL support (#94).

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue with the owners of this repository before making a change.

Setup

The jk executable itself is written in Go, but the JavaScript part of this project requires NodeJS.

Prerequisites:

• go 1.11.4 or later (modules support)
• nodejs, npm
• make
• pkg-config

First off, clone this repository:

$ git clone https://github.com/jkcfg/jk.git
# or with hub:
$ hub clone jkcfg/jk

$ cd ./jk

Then pull most of the dependencies using the Makefile:

$ make dep

jk is linked against v8worker2. As building V8 takes ~30 minutes, prebuilt versions are provided for linux/amd64 and darwin/amd64. This also includes flatc from flatbuffers:

# download the prebuilt artifacts from GitHub:
$ git clone https://github.com/jkcfg/prebuilt.git
$ cd ./prebuilt

# these following put files in /usr/local, so you may need sudo

# x64 Linux:
$ make install-linux-amd64

# x64 macOS:
$ make install-darwin-amd64

Building

After setting up the environment, the jk binary can be built:

$ make jk
$ ./jk --help # confirm it works

Additionally, on Linux, it's possible to use a docker container to build the project instead of installing the prebuilt libraries and binaries:

$ ./run-in-docker.sh make dep jk