Exec plugins (deprecated)

Authoring legacy exec plugins

An 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).

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 bundle (source, tests, plugin data files, etc.) for sharing.

When loading, kustomize will look for an executable file called kind.

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

Failure to find a plugin to load fails the overall kustomize build.

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.
• hashicorp go-getter - Download kustomize layes and build it to generate resources

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.

Guided example

This is a (no reading allowed!) 60 second copy/paste guided example.

This demo writes and uses a somewhat ridiculous exec plugin (written in bash) that generates a ConfigMap.

Prerequisites:

• linux
• git
• curl
• Go 1.13

Make a place to work

DEMO=$(mktemp -d)

Install kustomize

Per the instructions:

curl -s "https://raw.githubusercontent.com/\
kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"  | bash
mkdir -p $DEMO/bin
mv kustomize $DEMO/bin

Create a kustomization

Make a kustomization directory to hold all your config:

MYAPP=$DEMO/myapp
mkdir -p $MYAPP

Make a deployment config:

# $MYAPP/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: the-deployment
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: the-container
        image: monopole/hello:1
        command: ["/hello",
                  "--port=8080",
                  "--enableRiskyFeature=$(ENABLE_RISKY)"]
        ports:
        - containerPort: 8080
        env:
        - name: ALT_GREETING
          valueFrom:
            configMapKeyRef:
              name: the-map
              key: altGreeting
        - name: ENABLE_RISKY
          valueFrom:
            configMapKeyRef:
              name: the-map
              key: enableRisky
EOF

Make a service config:

# $MYAPP/service.yaml
kind: Service
apiVersion: v1
metadata:
  name: the-service
spec:
  type: LoadBalancer
  ports:
  - protocol: TCP
    port: 8666
    targetPort: 8080
EOF

Now make a config file for the plugin you’re about to write.

This config file is just another k8s resource object. The values of its apiVersion and kind fields are used to find the plugin code on your filesystem (more on this later).

# $MYAPP/cmGenerator.yaml
apiVersion: myDevOpsTeam
kind: SillyConfigMapGenerator
metadata:
  name: whatever
argsOneLiner: Bienvenue true
EOF

Finally, make a kustomization file referencing all of the above:

# $MYAPP/kustomization.yaml
commonLabels:
  app: hello
resources:
- deployment.yaml
- service.yaml
generators:
- cmGenerator.yaml
EOF

Review the files

ls -C1 $MYAPP

Make a home for plugins

Plugins must live in a particular place for kustomize to find them.

This demo will use the ephemeral directory:

PLUGIN_ROOT=$DEMO/kustomize/plugin

The plugin config defined above in $MYAPP/cmGenerator.yaml specifies:

apiVersion: myDevOpsTeam
kind: SillyConfigMapGenerator

This means the plugin must live in a directory named:

MY_PLUGIN_DIR=$PLUGIN_ROOT/myDevOpsTeam/sillyconfigmapgenerator

mkdir -p $MY_PLUGIN_DIR

The directory name is the plugin config’s apiVersion followed by its lower-cased kind.

A plugin gets its own directory to hold itself, its tests and any supplemental data files it might need.

Create the plugin

Make an exec plugin, installing it to the correct directory and file name. The file name must match the plugin’s kind (in this case, SillyConfigMapGenerator):

# $MY_PLUGIN_DIR/SillyConfigMapGenerator
#!/bin/bash
# Skip the config file name argument.
shift
echo "
kind: ConfigMap
apiVersion: v1
metadata:
  name: the-map
data:
  altGreeting: "$1"
  enableRisky: "$2"
"
EOF

By definition, an exec plugin must be executable:

chmod a+x $MY_PLUGIN_DIR/SillyConfigMapGenerator

Review the layout

tree $DEMO

Build your app

XDG_CONFIG_HOME=$DEMO $DEMO/bin/kustomize build --enable_alpha_plugins $MYAPP

Above, if you had set

PLUGIN_ROOT=$HOME/.config/kustomize/plugin

there would be no need to use XDG_CONFIG_HOME in the kustomize command above.

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.