ksonnet-lib

README

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.2/k.libsonnet";

Jsonnet import statements look along a "search path" specified using jsonnet -J <path>. To use ksonnet, the search path should include the root of the ksonnet-lib git repository. You should add additional -J paths as you build up your own local libraries.

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

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 -J /path/to/ksonnet-lib <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.2/k.libsonnet";

// Specify the import objects that we need
local container = k.extensions.v1beta1.deployment.mixin.spec.template.spec.containersType;
local containerPort = container.portsType;
local deployment = k.extensions.v1beta1.deployment;

local targetPort = 80;
local podLabels = {app: "nginx"};

local nginxContainer =
  container.new("nginx", "nginx:1.7.9") +
  container.ports(containerPort.containerPort(targetPort));

local nginxDeployment =
  deployment.new("nginx-deployment", 2, nginxContainer, podLabels);

k.core.v1.list.new(nginxDeployment)

Save the file as helloworld.libsonnet, then run:

jsonnet -J </path/to/ksonnet-lib> helloworld.libsonnet > deployment.json

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.2/k.libsonnet: higher-level abstractions and methods to help create complex Kubernetes objects out of smaller objects

k.libsonnet is built on top of a utility library, k8s.libsonnet, that is generated directly from the OpenAPI definition.

Mixins

Mixins are a core feature of ksonnet. Conceptually, they provide dynamic inheritance, at runtime instead of compile time, which lets you combine them freely to modify objects or create new ones.

ksonnet ships with a large library of built-in mixins, or you can write your own custom mixins. The tutorial shows you how to create a custom mixin that you can then easily add as a Sidecar container to your Kubernetes cluster.

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.