Jan Kühle

A CLI, which helps you to work with and deploy plain Kubernetes YAML files.

Background

There are many great tools out there to manage Kubernetes manifests, e.g. ksonnet or kustomize. They try to make working with manifests easier by deduplicating config. However they usually introduce other configuration files, which comes with complexity on its own. I wanted something simpler, especially for smaller applications.

So here is kyml:

• Work with plain Kubernetes YAML files. No additional config files.
• Duplicate files for each environment. But ensure updates always happen to all environments.
• Support dynamic values with limited templating.
• Save to run. Never touch original YAML files.

Install

macOS

brew install frigus02/tap/kyml

Linux & Windows

Download a binary from the release page.

This downloads the latest version for Linux:

curl -sfL -o /usr/local/bin/kyml https://github.com/frigus02/kyml/releases/download/v20210610/kyml_20210610_linux_amd64 && chmod +x /usr/local/bin/kyml

Usage

kyml provides commands for concatenating YAML files

• Structure your manifests in the way you want
• kyml cat - concatenate YAML files
• kyml test - ensure updates always happen to all environments
• kyml tmpl - inject dynamic values
• kyml resolve - resolve Docker images to their digest

Run kyml --help for details about the different commands.

Structure your manifests in the way you want

For most of the examples in this readme we assume the following structure:

manifests
|- staging
|  |- deployment.yaml
|  |- ingress.yaml
|  `- service.yaml
`- production
   |- deployment.yaml
   |- ingress.yaml
   `- service.yaml

And some of them use this:

manifests
|- base
|  |- ingress.yaml
|  `- service.yaml
`- overlays
   |- staging
   |  `- deployment.yaml
   `- production
      `- deployment.yaml

You can adapt these or use anything else

kyml cat - concatenate YAML files

Concatenate your files and pipe them into kubectl apply to deploy them. This does 2 things:

• If multiple files contain the same Kubernetes resource, kyml cat deduplicates them. Only the one specified last makes it into the output.
• Resources are sorted by dependencies. So even if you specify the namespace last (e.g. kyml cat deployment.yaml namespace.yaml) the namespace will appear first in the output. This makes sure your resources are created in the correct order.

kyml cat manifests/production/* | kubectl apply -f -

kyml cat manifests/base/* manifests/overlays/production/* | kubectl apply -f -

kyml test - ensure updates always happen to all environments

Testing works by creating a diff between two environments and storing it in a snapshot file. The command compares the diff result to the snapshot and fails if it doesn't match.

kyml test reads manifests of the main environment from stdin and files from the comparison environment are specified as arguments

kyml cat manifests/production/* |
    kyml test manifests/staging/* \
        --name-main production \
        --name-comparison staging \
        --snapshot-file tests/snapshot-production-vs-staging.diff |
    kubectl apply -f -

kyml tmpl - inject dynamic values

Use templates (in the go template syntax) to inject dynamic values. To make sure values are escaped properly and this feature doesn't get misused you can only template string scalars. Example:

apiVersion: v1
kind: Namespace
metadata:
  name: the-namespace
  labels:
    branch: "{{.TRAVIS_BRANCH}}"

kyml test reads manifests from stdin and prints the result to stdout. Values are provided as command line options. Use --value key=value for literal strings and --env ENV_VAR for environment variables. These options can be repeated multiple times. The command fails if the manifests contain any template key

kyml cat manifests/production/* |
    kyml test manifests/staging/* \
        --name-main production \
        --name-comparison staging \
        --snapshot-file tests/snapshot-production-vs-staging.diff |
    kyml tmpl \
        -v Greeting=hello \
        -v ImageTag=$(git rev-parse --short HEAD) \
        -e TRAVIS_BRANCH |
    kubectl apply -f -

kyml resolve - resolve Docker images to their digest

If you tag the same image multiple times (e.g. because you build every commit and tag images with the commit sha)

kyml cat manifests/production/* |
    kyml tmpl -v ImageTag=$(git rev-parse --short HEAD) |
    kyml resolve |
    kubectl apply -f -

Contributing

Please see CONTRIBUTING.md.

License

MIT