what-is-ksonnet.md

What is ksonnet?

How can the current concepts in ksonnet be demonstrated in their simplest form?

We have a Deployment object that needs to be in the cluster. If you create the object, you can apply it to the cluster with kubectl apply -f deployment.yaml. In many cases, you’ll have multiple objects. For example, to make a Deployment object useful, it is often paired with a Service and Ingress objects. These additional objects can be applied to the cluster with kubectl apply -f service.yaml and kubectl apply -f ingress.yaml.

Applications aren’t only deployed to product environments. Teams often use development and staging environments as well. How do you manage the components of your application in multiple locations? In these different environments, configuration parameters might be different. e.g. the host name for the an application will be different depending of the environment, or the amount of replicas of pods might change due to the amount of traffic the application will receive. To successfully manage these environments and their applications, there needs to be a way to override component parameters with their environment values.

ksonnet applications

Ksonnet applications provide a convention for storing source files. These files can be combined to create the required objects that will be applied to the Kubernetes cluster.

app.yaml

app.yaml contains the configuration for a ksonnet application. It describes environments, libraries, and registries.

# These two entries describe the document.
apiVersion: 0.1.0
kind: ksonnet.io/app

# The name of the ksonnet application.
name: mule

# The version of the ksonnet applicaiton.
version: 0.0.1

# This section describes the environments for this ksonnet application.
environments:
  default:
    destination:
      namespace: default
      server: https://35.193.252.24
    k8sVersion: v1.8.9
    path: default

# This section describes the libraries this ksonnet application has installed.
libraries:
  core:
    gitVersion: null
    name: core
    registry: kubeflow

# This sections describes the registries the ksonnet application has knowledge of.
registries:
  kubeflow:
    protocol: fs
    uri: /tmp/kubeflow/kubeflow

Environments contains:

• A name which describes the environment
• destination: Kubernetes cluster address and namespace.
• Kubernetes version
• Path to the environment configuration
• Components this environment targets

Libraries contains:

• A name which describes the environment.
• The registry this library belongs to
• Optional Git metadata

Registries contains:

• A name which describes the registry
• The protocol for the registry
• The URI for the registry

Registries and environments can overridden using app.override.yaml

environments:
  apps/ksonnet/dev:
    destination:
      namespace: default
      server: https://35.193.252.24
    k8sVersion: v1.7.0
    path: apps/ksonnet/dev

components

Components are the building blocks of your application. A component is a description of an object. Currently ksonnet supports Jsonnet, YAML, and JSON as object descriptions. These components can be paired with variable parameters to describe an object.

Jsonnet

Jsonnet components are in Jsonnet source files with a jsonnet extension. Parameters from params.libsonnet are exposed as variables which can be used to update dynamic values.

YAML and JSON

YAML components are in YAML format. Ksonnet only supports one object per file. JSON components are in JSON format. Parameters from params.libsonnet are applied as an overlay.

environments

The environments directory contains environments.

.
├── apps
│   └── ksonnet
│       └── dev
│           ├── globals.libsonnet
│           ├── main.jsonnet
│           └── params.libsonnet
├── base.libsonnet
└── default
    ├── globals.libsonnet
    ├── main.jsonnet
    └── params.libsonnet

base.libsonnet provides a reusable base that is used by individual environments. It returns all the components.

What’s an environment?

An environment contains

• main.jsonnet: Provides a base file to evaluate components for an environment.
• params.libsonnet: environment parameters
• globals.libsonnet: global values overlay that will be applied to all components in an environment

lib

Lib is where ksonnet application wide libraries are stored.

Currently, ksonnet-lib is the only provided application wide library. ksonnet-lib is a jsonnet conversion of the Kubernetes OpenAPI specification for a particular version. It can be used to construct Kubernetes objects.

lib
├── v1.7.0
│  ├── k.libsonnet
│  ├── k8s.libsonnet
│  └── swagger.json
└── v1.8.9
    ├── k.libsonnet
    ├── k8s.libsonnet
    └── swagger.json

In the near future, lib will be extended to support other application-wide libraries. This will allow ksonnet users to consolidate all their shared code to lib.

vendor

Vendor contains libraries that have been installed from registries. Registries define the location for remote (to the ksonnet app) dependencies. Registries can live in a GitHub repository or a on a local filesystem. They can contain one or more Part.

Parts are individual libraries. They can contain code libraries and Prototypes. The libraries are made available to all components. Prototypes are example implementations using the Part’s code library.

Building objects with ksonnet

Using the conventions in the ksonnet application, ks can build objects for a particular environment.

An environment’s main.jsonnet is evaluated with an embedded jsonnet VM. Components are passed to the evaluation as an argument. The process in turn evaluates the parameters for each component. The output is converted into Kubernetes runtime objects. These objects can be converted to YAML or JSON or applied to the Kubernetes cluster.