Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/joshdk/template-transformer

🫥 Kustomize transformer plugin for strict templating of resources
https://github.com/joshdk/template-transformer

go golang kubernetes kustomization kustomize kustomize-plugin templating

Last synced: 3 months ago
JSON representation

🫥 Kustomize transformer plugin for strict templating of resources

Host: GitHub
URL: https://github.com/joshdk/template-transformer
Owner: joshdk
License: mit
Created: 2022-06-24T01:24:48.000Z (over 2 years ago)
Default Branch: master
Last Pushed: 2023-11-29T17:09:09.000Z (12 months ago)
Last Synced: 2024-06-20T22:34:09.028Z (5 months ago)
Topics: go, golang, kubernetes, kustomization, kustomize, kustomize-plugin, templating
Language: Go
Homepage:
Size: 39.1 KB
Stars: 12
Watchers: 3
Forks: 2
Open Issues: 3
Metadata Files:
- Readme: README.md
- License: LICENSE.txt

Awesome Lists containing this project

README

[![License][license-badge]][license-link]
[![Actions][github-actions-badge]][github-actions-link]
[![Releases][github-release-badge]][github-release-link]

# 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](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/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](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/replacements/), which is the successor to vars, but has a number of usability concerns.

This repository provides a [kustomize plugin](https://kubectl.docs.kubernetes.io/guides/extending_kustomize/exec_plugins/) (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][github-release-link].

```shell
$ 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.

```yaml
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:

```diff
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}}`.

```diff
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.

```bash
$ 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.

```yaml
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.

```diff
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.

```bash
$ kustomize build --enable-alpha-plugins .
```

```yaml
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](https://pkg.go.dev/regexp#Regexp.Expand) for more information.

```diff
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.

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

```yaml
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](https://argo-cd.readthedocs.io/en/stable/user-guide/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.

```diff
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][license-link], see [LICENSE.txt][license-file] for more information.

[github-actions-badge]: https://github.com/joshdk/template-transformer/workflows/Build/badge.svg
[github-actions-link]: https://github.com/joshdk/template-transformer/actions
[github-release-badge]: https://img.shields.io/github/release/joshdk/template-transformer/all.svg
[github-release-link]: https://github.com/joshdk/template-transformer/releases
[license-badge]: https://img.shields.io/badge/license-MIT-green.svg
[license-file]: https://github.com/joshdk/template-transformer/blob/master/LICENSE.txt
[license-link]: https://opensource.org/licenses/MIT