The Templating API

If you're using Kerbi, you probably enjoy Ruby in YAML, a.k.a ERB. This guide covers the most useful methods available to you inside your .yaml.erb files.

Most of the methods here come from Kerbi::Mixins::Mixer, which is documented here.

Public and Custom Mixer API methods

In addition to the methods listed in the next sections, you have access to:

• Every public method from the Mixer API (e.g values, file(), etc...), except #push()

• Any custom methods you define in your Mixer subclass, including those included from modules

See both in action below with file() and ingress_enabled?():

ingress.yaml.erb

<% if ingress_enabled? %>
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: minimal-ingress
  annotations: <%= embed(file("ingress-annotations")) %>
spec:
  #...
<% end %>

ingress-annotations.yaml

nginx.ingress.kubernetes.io/rewrite-target: /
nginx.ingress.kubernetes.io/custom-http-errors: "404,415"
nginx.ingress.kubernetes.io/cors-expose-headers: "*, X-CustomResponseHeader"

Output

Running kerbi template default . --set ingress.enabled=true:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: minimal-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: "/"
    nginx.ingress.kubernetes.io/custom-http-errors: '404,415'
    nginx.ingress.kubernetes.io/cors-expose-headers: "*, X-CustomResponseHeader"
spec: 

kerbifile.rb

class TemplatingExample < Kerbi::Mixer
  def mix
    push file("ingress")
  end
  
  def ingress_enabled?
    values.dig(:ingress, :enabled).present?
  end
end

The b64enc() method

Encodes a string as its Base64 representation, as it is often necessary with Secrets:

Template

kind: Secret
metadata:
  name: postgres-pw
data:
  password: <%= b64enc(values.dig(:web, :db, :pw) || "unsafe") %>

Output

kind: Secret
metadata:
  name: postgres-pw
data:
  password: dW5zYWZl

The b64dec() method

Decodes a string from its Base64 representation:

Template

kind: Secret
metadata:
  name: postgres-pw
data:
  password: <%= b64dec("dW5zYWZl") %>

Output

kind: Secret
metadata:
  name: postgres-pw
data:
  password: unsafe

The embed() and embed_array() methods

The embed() and embed_array() methods convert, respectively, a Hash and an Array<Hash>, into an appropriately indented String that can be embedded into a YAML file.

Template

apiVersion: networking.k8s.io/v1
kind: Pod
metadata:
  name: minimal-ingress
  annotations: <%= embed({foo: "bar"}) %>
spec: 
  restartPolicy: Never
  containers: <%= embed_array(dir("containers")) %>

Output

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: minimal-ingress
  annotations:
    foo: bar
spec: 

About Indentation

Both methods assume that what you're trying to embed should appear as far "right" as possible. If this is not what you need, you can pass the optional indent: Integer option. If the indent is wrong, e.g it is too small, YAML parsing will raise an exception and templating will fail.

Embedding items into a List

If you have a YAML-defined list and need to add individual items, the best known way to do this (although this is not ideal), is to call embed_array() with an explicit indent: Integer that you find by counting, or more realistically by trial and error.

Template

apiVersion: v1
kind: Pod
metadata:
  name: embed-item
  namespace: <%= release_name %>
spec:
  containers:
    - name: nginx
      image: nginx
      <%= embed_array(
            [{name: "traefik", image: "traefik"}],
            indent: 4
       ) %>

Output

apiVersion: v1
kind: Pod
metadata:
  name: embed-item
  namespace: aasd
spec:
  containers:
  - name: nginx
    image: nginx
  - name: traefik
    image: traefik