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][quick-start].
For more context head to our [introduction blog post][blog-0]!

More complex examples

- [A Kubernetes deployment written in Typescript][guestbook-ts]
- [Generating Kubernetes objects, using e.g., kustomize-like behavior][k8s-examples]
- [Using jk with JavaScript libraries][js-examples]

Architecture & design

$3

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

$3

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.

$3

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

- [kubernetes][kubernetes]: build Kubernetes objects
- [grafana][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][issue110], [#44][issue44], [topic/hermeticity][issueHermeticity]).
- Native typescript support ([#54][issue54]).
- HCL support ([#94][issue94]).

[v8]: https://v8.dev/
[blog-0]: https://damien.lespiau.name/posts/2019-06-12-jk-configuration-as-code/
[quick-start]: https://jkcfg.github.io/#/documentation/quick-start
[grafana]: https://github.com/jkcfg/grafana
[kubernetes]: https://github.com/jkcfg/kubernetes
[guestbook-ts]: https://github.com/jkcfg/kubernetes/blob/master/examples/guestbook-ts
[js-examples]: https://github.com/jkcfg/jk/tree/master/examples
[k8s-examples]: https://github.com/jkcfg/jk/tree/master/examples/kubernetes
[v8worker2]: https://github.com/ry/v8worker2
[flatbuffers]: https://github.com/google/flatbuffers

[issue44]: https://github.com/jkcfg/jk/issues/44
[issue54]: https://github.com/jkcfg/jk/issues/54
[issue94]: https://github.com/jkcfg/jk/issues/94
[issue110]: https://github.com/jkcfg/jk/issues/110
[issueHermeticity]: https://github.com/jkcfg/jk/issues?q=is%3Aissue+is%3Aopen+label%3Atopic%2Fhermeticity

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.

$3

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:
``bash
$ 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:
`bash
$ 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:
`bash


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
`

$3

After setting up the environment, the jk binary can be built:
`bash
$ 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:
`bash
$ ./run-in-docker.sh make dep jk
``