Crate k8src 

k8src

k8src is the kubernetes rc scripting language. It combines rc.conf style configuration with YAML templates to generate Kubernetes manifests.

The common layout is:

/rc.conf
/service.yaml.template
/rc.d/<service>.yaml.template
/pets/...

service.yaml.template is the default template for enabled services. A file in rc.d/ with the service name overrides the default template for that service and for aliases that resolve to it. pets/ is copied through to the generated manifests unchanged.

Quick Start

Create a minimal project:

$ k8src init
$ k8src regenerate --dry-run
$ k8src regenerate --overwrite

Print the built-in service template:

$ k8src template service.yaml.template

Inspect what k8src will do:

$ k8src explain-template memcached
$ k8src explain-vars memcached
$ k8src regenerate --diff

How it Works

At its core, k8src is a shell-like substitution library for YAML. Given an rc.conf, it substitutes values according to the cascading rules of rc into the YAML.

For example, this rc.conf enables a memcached service:

NAMESPACE="memcached"

memcached_IMAGE="rescrv/memcached:latest"
memcached_ENABLED="YES"
memcached_HOST=memcached.example.org
memcached_PORT=11211

memcached_two_INHERIT="YES"
memcached_two_ALIASES="memcached"
memcached_two_ENABLED="YES"
memcached_two_PORT="22122"

A matching service.yaml.template can use those values:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ${SERVICE:?SERVICE not set}
  namespace: ${NAMESPACE:?NAMESPACE not set}
  labels:
    app: ${SERVICE}
spec:
  replicas: ${REPLICAS:-1}
  selector:
    matchLabels:
      app: ${SERVICE}
  template:
    metadata:
      labels:
        app: ${SERVICE}
    spec:
      containers:
      - name: ${SERVICE}
        image: ${IMAGE:?IMAGE not set}
        ports:
        - containerPort: ${PORT:-8000}
---
apiVersion: v1
kind: Service
metadata:
  name: ${SERVICE}
  namespace: ${NAMESPACE}
  labels:
    app: ${SERVICE}
spec:
  type: ClusterIP
  ports:
  - port: ${PORT:-8000}
    protocol: TCP
    targetPort: ${PORT:-8000}
  selector:
    app: ${SERVICE}

The syntax matches FreeBSD /bin/sh parameter expansion for ${FOO:-expand if not set}, ${FOO:?ERROR message}, and ${FOO:+expand if set}. ${FOO:?} marks a value optional; optional values are omitted in a cascading fashion.

Template Selection

For each enabled service, k8src searches from the deepest overlay back to the root:

<overlay>/rc.d/<service>.yaml.template
<root>/rc.d/<service>.yaml.template
<overlay>/service.yaml.template
<root>/service.yaml.template
built-in default template

Alias fallback is transitive. If frontend aliases app, k8src first looks for rc.d/frontend.yaml.template, then for rc.d/app.yaml.template, then for the default template.

Output Format

Generated output goes under manifests/:

/manifests/kustomization.yaml
/manifests/herd
/manifests/herd/kustomization.yaml
/manifests/herd/memcached.yaml
/manifests/herd/memcached_two.yaml
/manifests/pets/...

Services from rc.conf are generated under herd/. Files under pets/ should already be valid kustomize input and are copied verbatim.

Overlays

Overlays are nested directories with their own rc.conf. For example:

/rc.conf
/service.yaml.template
/rc.d/Sjc_CyberDyne_memcached.yaml.template
/pets/...
/env1/rc.conf
/env1/service.yaml.template
/env1/rc.d/memcached.yaml.template
/env1/pets/...
/env2/rc.conf

k8src generates manifests for terminal rc.conf files. It infers an rc_conf_path such as rc.conf:env1/rc.conf, where later values mask earlier values. Each overlay may override env/rc.conf, env/service.yaml.template, env/rc.d/<service>.yaml.template, and env/pets/....

Running k8src

$ k8src help
$ k8src regenerate --help

Status

Active development. I plan to build tooling for rolling out rc.conf changes and then mark it as maintenance track.

Documentation

The latest documentation is always available at docs.rs.

Structs

RegenerateOptions

TemplateCandidate

TemplateResolution

Enums

Error

Functions

candidates

default_service_template

Return the built-in default service template.

error_code

error_message

error_string_field

explain_template

explain_vars

rc_conf_path

regenerate

rewrite

template_resolution