template-transformer

README

Kustomize Template Transformer Plugin

🫥 Kustomize transformer plugin for strict templating of resources

Motivations

Currently, there are two built-in ways to inject dynamic values into the manifests generated when running kustomize build. The first is kustomize vars, which requires that the values already exist as part of a resource's properties, and is also currently planned to be deprecated. The second is kustomize replacements, which is the successor to vars, but has a number of usability concerns.

This repository provides a kustomize plugin (specifically a transformer plugin) that can template values from the working environment into a stream of Kubernetes resource manifests. This plugin also aims to facilitate this in a tightly controlled way in order to avoid runtime errors, user confusion, and to prevent any backsliding into open-ended template sprawl like with Helm.

Installation

Prebuilt binaries for several architectures can be found attached to any of the available releases.

$ wget https://github.com/joshdk/template-transformer/releases/download/v0.2.1/template-transformer-linux-amd64.tar.gz
$ tar -xf template-transformer-linux-amd64.tar.gz
$ mkdir -p ${XDG_CONFIG_HOME}/kustomize/plugin/jdk.sh/v1beta1/templatetransformer/
$ install TemplateTransformer ${XDG_CONFIG_HOME}/kustomize/plugin/jdk.sh/v1beta1/templatetransformer/TemplateTransformer

Usage

To show how things are configured, we can demo adding a version label to an existing deployment manifest.

Inside our existing Kustomize app, we can create a template-transformer.yaml file. Here we are configuring a single property named VERSION which gets its value from the DRONE_COMMIT_SHA environment variable.

The apiVersion and kind must be set to jdk.sh/v1beta1 and TemplateTransformer respectively.

apiVersion: jdk.sh/v1beta1
kind: TemplateTransformer

metadata:
  name: example

properties:
  - name: VERSION
    description: Current application version
    source:
      - DRONE_COMMIT_SHA

In our example kustomization.yaml file, we can reference the template-transformer.yaml file under the transformers section:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml

transformers:
+ - template-transformer.yaml

In our existing (and very abridged) deployment.yaml manifest, we can add a new label that references our property using the template syntax ${{.VERSION}}.

apiVersion: apps/v1
kind: Deployment

metadata:
  name: example
+ labels:
+   app.kubernetes.io/version: ${{.VERSION}}

We can now build our Kustomize app, making sure to set a value for the DRONE_COMMIT_SHA environment variable.

$ DRONE_COMMIT_SHA=$(git rev-parse HEAD) kustomize build --enable-alpha-plugins .

You should now see a rendered deployment labeled with the current git sha.

apiVersion: apps/v1
kind: Deployment

metadata:
  name: example
  labels:
    app.kubernetes.io/version: deca...5bd9

Default Values

If the template transformer can't resolve a value for every single property, it will fail immediately with an error. To prevent errors in environments where an appropriate value might not be available, you can configure a default value instead.

apiVersion: jdk.sh/v1beta1
kind: TemplateTransformer

metadata:
  name: example

properties:
  - name: VERSION
    description: Current application version
    source:
      - DRONE_COMMIT_SHA
+   default: development

Now if we build our Kustomize app, without setting a value for the DRONE_COMMIT_SHA environment variable, we can observe that our default value is templated instead.

$ kustomize build --enable-alpha-plugins .

apiVersion: apps/v1
kind: Deployment

metadata:
  name: example
  labels:
    app.kubernetes.io/version: development

Mutating Values

Often the raw value of the source environment variable isn't appropriate for direct templating. In cases like this you can configure a mutator to modify such values.

In this example we want to keep only the first 8 digits of our git SHA, instead of the entire thing. Additionally, we want to prefix the value with git- since that is the source of our versioning.

ℹ️ See the docs on Regexp.Expand for more information.

apiVersion: jdk.sh/v1beta1
kind: TemplateTransformer

metadata:
  name: example

properties:
  - name: VERSION
    description: Current application version
    source:
      - DRONE_COMMIT_SHA
    default: development
+   mutate:
+     pattern: ^.{8}
+     replace: git-$0

Now if we build our Kustomize app, we can observe the prefixed short SHA value in our deployment label.

$ DRONE_COMMIT_SHA=$(git rev-parse HEAD) kustomize build --enable-alpha-plugins .

apiVersion: apps/v1
kind: Deployment

metadata:
  name: example
  labels:
    app.kubernetes.io/version: git-decafbad

Built in Properties

There are a number of built in, non-redefinable properties that are implicitly included for convenience.

Name	Description	Usage	Example
DATETIME	The current time in RFC3339 format	${{.DATETIME}}	2022-07-22T14:52:46Z
UNIXTIME	The current time in Unix/Epoch format	${{.UNIXTIME}}	1658501566

ArgoCD

If your are deploying Kustomize applications using ArgoCD, then please take note of the ArgoCD build environment as it contains a very limited set of environment variables. Additional environment variables cannot be configured without completely rebuilding the built-in ArgoCD Kustomize integration.

Our example template-transformer.yaml configuration could be updated to support ArgoCD like so.

apiVersion: jdk.sh/v1beta1
kind: TemplateTransformer

metadata:
  name: example

properties:
  - name: VERSION
    description: Current application version
    source:
      - DRONE_COMMIT_SHA
+     - ARGOCD_APP_REVISION
    default: development
    mutate:
      pattern: ^.{8}
      replace: git-$0

License

This code is distributed under the MIT License, see LICENSE.txt for more information.

Documentation

Overview

Package main defines the main entry point for the TemplateTransformer plugin.