ksonnet: Simplify working with Kubernetes

ksonnet (currently in beta testing) provides a simpler alternative to writing complex YAML for your Kubernetes configurations. Instead, you write template functions against the Kubernetes application API using the data templating language Jsonnet . Components called mixins also help simplify the work that's required to extend your configuration as your application scales up.

Other projects help simplify the work of writing a Kubernetes configuration by creating a simpler API that wraps the Kubernetes API. These projects include Kompose, OpenCompose, and compose2kube.

ksonnet instead streamlines the process of writing configurations that create native Kubernetes objects.

Install

First, install Jsonnet.

Mac OS X

If you do not have Homebrew installed, install it now.

Then run:

brew install jsonnet

Linux

You must build the binary. For details, see the GitHub repository.

Run

Fork or clone this repository, using a command such as:

git clone git@github.com:ksonnet/ksonnet-lib.git

Then add the appropriate import statements for the library to your Jsonnet code:

local k = import "ksonnet.beta.1/k.libsonnet";

As Jsonnet does not yet support go get-style importing from HTTP, import paths are relative to the root of the ksonnet repository. Remember to modify the paths appropriately when you work in another environment so that they point at your clone.

Additionally, since Jsonnet does not yet support ES2016-style imports it is common to "unpack" an import with a series of local definitions, as so:

local container = k.core.v1.container;
local deployment = k.extensions.v1beta1.deployment;

Tools

Developed in tandem with ksonnet-lib is vscode-jsonnet, a static analysis toolset written as a Visual Studio Code plugin, meant to provide features such as autocomplete, syntax highlighting, and static analysis.

Get started

If you're not familiar with Jsonnet, check out the website and their tutorial. For usage, see the command line tool.

You can also start writing .libsonnet or .jsonnet files based on the examples in this readme. Then run the following command:

jsonnet <filename.libsonnet>

This command produces a JSON file that you can then run the appropriate kubectl commands against, with the following syntax:

kubectl <command> -<options> <filename.json>

Write your config files with ksonnet

The YAML for the Kubernetes nginx hello world tutorial looks like this:

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 2
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.7.9
        ports:
        - containerPort: 80

Instead, you can write the following ksonnet code:

local k = import "../../ksonnet.beta.1/k.libsonnet";

local container = k.core.v1.container;
local deployment = k.apps.v1beta1.deployment;

local nginxContainer =
  container.default("nginx", "nginx:1.7.9") +
  container.helpers.namedPort("http", 80);

deployment.default("nginx-deployment", nginxContainer) +
deployment.mixin.spec.replicas(2)

Save the file as helloworld.libsonnet, then run:

jsonnet helloworld.libsonnet

This command creates the deployment.json file that the ksonnet snippet defines.

You can now apply this deployment to your Kubernetes cluster by running the following command:

kubectl apply -f deployment.json

The ksonnet libraries

The ksonnet project organizes libraries by the level of abstraction they approach. For most users, the right entry point is:

ksonnet.beta.1/k.libsonnet: higher-level abstractions and methods to help create complex Kubernetes objects out of smaller objects

k.libsonnet is built on top of several lower-level utility libraries that extends the object model and functions of Jsonnet to implement the Kubernetes API. These are generated directly from the swagger spec, and are organized by the API groups they belong to:

ksonnet.beta.1/apps.v1beta1.libsonnet
ksonnet.beta.1/core.v1.libsonnet
ksonnet.beta.1/extensions.v1beta1.libsonnet

Contributing

Thanks for taking the time to join our community and start contributing!

Before you start

Please familiarize yourself with the Code of Conduct before contributing.
See CONTRIBUTING.md for instructions on the developer certificate of origin that we require.

Pull requests

We welcome pull requests. Feel free to dig through the issues and jump in.

Contact us

Have any questions or long-form feedback? You can always find us here:

Our Slack channel [working having an auto-invite system!)
Our mailing list.
We monitor the ksonnet tag on Stack Overflow.

wlan0/ksonnet-lib