kustomize/docs/plugins/README.md

kustomize plugins

Quick guides:

• linux exec plugin in 60 sec
• linux Go plugin in 60 sec

Kustomize offers a plugin framework allowing people to write their own resource generators and transformers.

Write a plugin when changing generator options or transformer configs doesn't meet your needs.

• A generator plugin could be a helm chart inflator, or a plugin that emits all the components (deployment, service, scaler, ingress, etc.) needed by someone's 12-factor application, based on a smaller number of free variables.

• A transformer plugin might perform special container command line edits, or any other transformation that exceeds the power of the builtin transformations (namePrefix, commonLabels, etc.).

Specification in kustomization.yaml

Start by adding a generators and/or transformers field to your kustomization.

Each field accepts a string list:

generators:
- relative/path/to/some/file.yaml
- relative/path/to/some/kustomization
- /absolute/path/to/some/kustomization
- https://github.com/org/repo/some/kustomization

transformers:
- {as above}

This is exactly like the syntax of the resources field.

The value of each entry in a resources, generators or transformers list must be a relative path to a YAML file, or a path or URL to a kustomization.

In the former case the YAML is read from disk directly, and in the latter case a kustomization is performed, and its YAML output is merged with the YAML read directly from files. The net result in all three cases is a set of YAML objects.

Each object resulting from a generators or transformers field is now further interpreted by kustomize as a plugin configuration object.

Configuration

A kustomization file could have the following lines:

generators:
- chartInflator.yaml

Given this, the kustomization process would expect to find a file called chartInflator.yaml in the kustomization root.

This is the plugin's configuration file.

The file chartInflator.yaml could contain:

apiVersion: someteam.example.com/v1
kind: ChartInflator
metadata:
  name: notImportantHere
chartName: minecraft

The apiVersion and kind fields are used to locate the plugin.

Thus, these fields are required. They are also required because a kustomize plugin configuration object is also a k8s object.

To get the plugin ready to generator or transform, it is given the entire contents of the configuration file.

For more examples of plugin configuration YAML, browse the unit tests below the plugins root, e.g. the tests for ChartInflator or NameTransformer.

Placement

Each plugin gets its own dedicated directory named

$XDG_CONFIG_HOME/kustomize/plugin
    /${apiVersion}/LOWERCASE(${kind})

The default value of XDG_CONFIG_HOME is $HOME/.config.

The one-plugin-per-directory requirement eases creation of a plugin tarball (source, test, plugin data files, etc.) for sharing.

In the case of a Go plugin, it also allows one to provide a go.mod file for the single plugin, easing resolution of package version dependency skew.

When loading, kustomize will first look for an executable file called

$XDG_CONFIG_HOME/kustomize/plugin
    /${apiVersion}/LOWERCASE(${kind})/${kind}

If this file is not found or is not executable, kustomize will look for a file called ${kind}.so in the same directory and attempt to load it as a Go plugin.

If both checks fail, the plugin load fails the overall kustomize build.

Execution

Plugins are only used during a run of the kustomize build command.

Generator plugins are run after processing the resources field (which itself is in some sense a generator in that it emits resources for further processing).

The full set of resources is then passed into the transformation pipeline, wherein builtin transformations like namePrefix and commonLabel are applied (if they were specified in the kustomization file), followed by the user-specified transformers in the transformers field.

The specified order of transformers in the transformers field should be respected, as transformers cannot be expected to be commutative.

A kustomize build that tries to use plugins but omits the flag

--enable_alpha_plugins

will fail with a warning about plugin use.

Flag use is an opt-in acknowledging the absence of plugin provenance. It's meant to give pause to someone who blindly downloads a kustomization from the internet and attempts to run it, without realizing that it might attempt to run 3rd party code in plugin form. The plugin would have to be installed already, but nevertheless the flag is a reminder.

Writing plugins

Exec plugins

A exec plugin is any executable that accepts a single argument on its command line - the name of a YAML file containing its configuration (the file name provided in the kustomization file).

TODO: more restrictions on plugin to allow the same exec plugin to be specified in a config under both the generators and transformers fields.

• first arg could be the fixed string generate or transform, (the name of the configuration file moves to the 2nd arg), or
• by default an exec plugin behaves as a tranformer unless a flag -g is provided, switching the exec plugin to behave as a generator.

Examples

• helm chart inflator - A generator that inflates a helm chart.
• bashed config map - Super simple configMap generation from bash.
• sed transformer - Define your unstructured edits using a plugin like this one.

A generator plugin accepts nothing on stdin, but emits generated resources to stdout.

A transformer plugin accepts resource YAML on stdin, and emits those resources, presumably transformed, to stdout.

kustomize uses an exec plugin adapter to provide marshalled resources on stdin and capture stdout for further processing.

Go plugins

A Go plugin for kustomize looks like this:

package main

import (
  "sigs.k8s.io/kustomize/v3/pkg/ifc"
  "sigs.k8s.io/kustomize/v3/pkg/resmap"
  ...
)

type plugin struct {...}

var KustomizePlugin plugin

func (p *plugin) Config(
   ldr ifc.Loader,
   rf *resmap.Factory,
   c []byte) error {...}

func (p *plugin) Generate() (resmap.ResMap, error) {...}

func (p *plugin) Transform(m resmap.ResMap) error {...}

Use of the identifiers plugin, KustomizePlugin and implementation of the method signature Config is required.

Implementing the Generator or Transformer method allows (respectively) the plugin's config file to be added to the generators or transformers field in the kustomization file. Do one or the other or both as desired.

Examples

• secret generator - Generate secrets from a database.
• service generator - Generate a service from a name and port argument.
• string prefixer - uses the value in metadata/name as the prefix. This particular example exists to show how a plugin can transform the behavior of a plugin. See the TestTransformedTransformers test in the target package.
• date prefixer - prefix the current date to resource names, a simple example used to modify the string prefixer plugin just mentioned.
• All the builtin plugins here. User authored plugins are on the same footing as builtin operations.

A plugin can be both a generator and a transformer. The Generate method will run along with all the other generators before the Transform method runs.

Here's a build command that sensibly assumes the plugin source code sits in the directory where kustomize expects to find .so files:

d=$XDG_CONFIG_HOME/kustomize/plugin\
/${apiVersion}/LOWERCASE(${kind})

go build -buildmode plugin \
   -o $d/${kind}.so $d/${kind}.go

Caveats

Go plugins allow kustomize extensions that run without the cost marshalling/unmarshalling all resource data to/from a subprocess for each plugin run.

Go plugins work as defined, but fall short of common notions associated with the word plugin. Go plugin compilation creates an ELF formatted .so file, which by definition has no information about the provenance of the object code. Skew between the compilation conditions (versions of package dependencies, GOOS, GOARCH) of the main program ELF and the plugin ELF will cause plugin load failure.

Exec plugins also lack provenance, but won't complain about compilation skew.

In either case, a sensible way to share a plugin is as a tar file of source code, tests and associated data, unpackable under $XDG_CONFIG_HOME/kustomize/plugin (exactly where one would develop a plugin).

In the case of a Go plugin, an end user accepting a shared plugin must compile both kustomize and the plugin. Tooling could be built to make Go plugin sharing easier, but this requires some critical mass of plugin authoring, which in turn is hampered by confusion around sharing. Go modules, once they are more widely adopted, will solve one of the biggest plugin sharing difficulties - ambiguous plugin vs host dependencies.