Kubernetes manifests are really well designed for the Kubernetes API system to evolve and be maintainable. This design pattern however comes at a cost — the user has to work with extremely verbose Kubernetes API system keys that are not human-friendly.

The Kubernetes manifest format trades off simplicity, readability and maintainability for a machine-friendly representation.

Consider this scenario — “You want to run nginx reverse proxy on a machine in the availability zone us-east-1a ”. Let’s look at how this can be expressed in Kubernetes format:

1 apiVersion: v1 # Version of the Kubernetes API

2 kind: Pod # Kind of Obj in this YAML doc

3 metadata:

4 name: nginx # identifying information

5 labels:

6 app: nginx

7 spec:

8 containers:

9 - name: nginx_container # information about the workload

10 image: nginx:latest

11 affinity: # information about where it is run

12 nodeAffinity:

13 requiredDuringSchedulingIgnoredDuringExecution:

14 nodeSelectorTerms:

15 - matchExpressions:

16 - key: k8s.io/failure-domain

17 operator: In

18 values:

19 - us-east-1a

The above YAML document represents the scenario I described earlier. i.e. This is Kubernetes speak for the above scenario.

[Lines 1–2] represent meta-information about the object’s type

[Lines 3–6] represent meta-information about the object’s contents

[Lines 9–10] represent the workload itself (nginx)

[Lines 11–19] represent where the workload should run

The most complicated part of this document is the information held in [Lines 11–19]. Line 11 declares affinity — i.e. “what should the pod have an affinity towards”

Line 12 declares nodeAffinity — i.e. “what node should the pod have an affinity towards”. This drills down into the resource type of the object to which there’s an affinity.

Line 13 declares requiredDuringSchedulingIgnoredDuringExecution . This looks like the name of a Java variable. It’s not easy to read, write, or understand. It just means the affinity must be satisfied, but only during the time the pod is being scheduled, and need not be satisfied if the pod is already running.

Line 14 declares nodeSelectorTerms — i.e. Now that I’ve expressed that I want affinity, affinity to some nodes, and affinity that is only respected while scheduling the pod — I want to describe the precise nodes that should run my pod.

Line 15–19 describes that the precise node to run my pod, is one whose label’s ( k8s.io/failure-domain ) value equals us-east-1a.

This example above could be much easier to read and write if:

Information is digested and presented in a human-friendly format.

e.g.

k8s.io/failure-domain=us-east-1a

is much more readable than

- key: k8s.io/failure-domain

operator: In

values:

- us-east-1a

Long-winded names like requiredDuringSchedulingIgnoredDuringExecution should be avoided. The above key already has a simpler name — It’s known as hard affinity.

should be avoided. The above key already has a simpler name — It’s known as hard affinity. Human friendly structures incorporate reasonable defaults, unlike machine-oriented structures. Most affinities represent hard affinity, so it can be the default.

Combining all of the above principles, the same data in [Lines 11–19] from the YAML document above can be simplified to

affinity:

- node: k8s.io/failure-domain=us-east-1a

instead of

affinity:

nodeAffinity:

requiredDuringSchedulingIgnoredDuringExecution:

nodeSelectorTerms:

- matchExpressions:

- key: k8s.io/failure-domain

operator: In

values:

- us-east-1a

Before we look at the entire document in the simpler format, let’s try and maintain the original document. If I needed to add another rule to say that this pod should not run on a machine with the label k8s.io/reserved , the representation in the original format becomes:

1 apiVersion: v1 # Version of the Kubernetes API

2 kind: Pod # Kind of Obj in this YAML doc

3 metadata:

4 name: nginx # identifying information

5 labels:

6 app: nginx

7 spec:

8 containers:

9 - name: nginx_container # information about the workload

10 image: nginx:latest

11 affinity: # information about where it is run

12 nodeAffinity:

13 requiredDuringSchedulingIgnoredDuringExecution:

14 nodeSelectorTerms:

15 - matchExpressions:

16 - key: k8s.io/failure-domain

17 operator: In

18 values:

19 - us-east-1a

20 - key: k8s.io/reserved

21 operator: DoesNotExist

This is even less readable.

The verbose nature of the Kubernetes manifest format adds noise to the reader’s eyes that must be filtered out each time this document is read.

A lot of time and energy is wasted in filtering this noise out. Koki Short is designed to solve exactly this problem:

It reduces the amount of energy and effort needed to create, represent, understand, and evolve information pertinent to your deployment. It tunes out the noise.

Here’s the equivalent representation in Short format:

1 pod:

2 name: nginx

3 labels:

4 app: nginx

5 containers:

6 - name: nginx

7 image: nginx:latest

8 affinity:

9 - node: k8s.io/failure-domain=us-east-1a&!k8s.io/reserved

10 version: v1

We built Short so that you, the DevOps engineer, the Developer or the IT engineer, can be more productive. Get a lot more done, a lot more quickly. Koki Short makes your conversation with Kubernetes quiet, concise and simple — like two people who understand each other really well.

I encourage you to try it out: docs.koki.io/short/user-guide.

Short supports every Kubernetes resource type and converts to and from native Kubernetes manifests without losing any information.

Additionally, we are announcing further optimization to your Kubernetes experience — Drone plugin for Koki Short.

The Drone plugin allows users to exclusively use Short format for representing Kubernetes workloads. Users can leverage the Drone plugin to translate Short files to Kubernetes manifests on the fly in their CI pipeline.

Learn more about it here: docs.koki.io/short/user-guide/drone