> For the complete documentation index, see [llms.txt](https://dinush-chathurya.gitbook.io/kustomize-e-book/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dinush-chathurya.gitbook.io/kustomize-e-book/additional-topics/18-custom-kustomize-plugins.md).

# Custom Kustomize Plugins

When the built-in generators and transformers aren’t enough, writing your own Kustomize plugin unlocks powerful, reusable customizations. In this chapter, we’ll cover why and how to create custom plugins, structure them, integrate them, and manage their lifecycle in production.

***

## Why Write a Plugin?

* **Domain-Specific Logic**: Inject organization-wide labels, generate complex CRDs, or enforce policies.
* **Reusable Transformations**: Encapsulate custom patches or generators as standalone components.
* **Maintainability**: Centralize business-specific logic, avoiding copy/paste across overlays.

***

## Plugin Types

Kustomize supports three plugin kinds:

1. **Generators**\
   Produce new resources (e.g., CRDs, ConfigMaps).
2. **Transformers**\
   Modify existing resources (e.g., add labels, change images).
3. **Exec Plugins**\
   Invoke arbitrary executables to produce or transform YAML.

***

## Plugin Folder Structure

You can vendor plugins in your repo or install them in the user directory:

Vendored alongside your kustomization.yaml

```
├── plugins/
│   └── example.com/
│       ├── transformers/
│       │   └── add-label/
│       │       └── main.go
│       └── generators/
│           └── custom-cm/
│               └── main.go
├── base/
│   └── kustomization.yaml
```

Or install under `$HOME/.config/kustomize/plugin/example.com/...`.

***

## Simple Go Transformer Example

### 1. Write the Plugin

**`plugins/example.com/transformers/add-label/main.go`**

```go
package main

import (
  "sigs.k8s.io/kustomize/api/types"
  "sigs.k8s.io/kustomize/kyaml/filesys"
  "sigs.k8s.io/kustomize/kyaml/kio"
  "sigs.k8s.io/kustomize/kyaml/yaml"
)

func main() {
  fs := filesys.MakeFsOnDisk()
  input := &kio.LocalPackageReadWriter{PackagePath: ".", Fs: fs}
  transformer := &addLabelTransformer{LabelKey: "app.kubernetes.io/managed-by", LabelValue: "kustomize-plugin"}
  kio.Pipeline{
    Inputs:  []kio.Reader{input},
    Filters: []kio.Filter{transformer},
    Outputs: []kio.Writer{input},
  }.Execute()
}

type addLabelTransformer struct {
  LabelKey   string
  LabelValue string
}

func (t *addLabelTransformer) Filter(nodes []*yaml.RNode) ([]*yaml.RNode, error) {
  for _, node := range nodes {
    meta, err := node.GetMeta()
    if err != nil {
      continue
    }
    node.PipeE(yaml.SetLabel(t.LabelKey, t.LabelValue))
    _ = meta
  }
  return nodes, nil
}
```

### 2. Configure in Kustomization

```yaml
# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
transformers:
  - ../plugins/example.com/transformers/add-label
```

***

## Integrating & Versioning

* **Vendor Plugins**: Check your `plugins/` directory into Git for reproducible builds.
* **Version Lock**: Tag plugin code and reference a specific commit or release.
* **CI Testing**: Add a job that runs `kustomize build` with your plugin against sample manifests.

***

## Best Practices

* **Keep Plugins Focused**: Single responsibility per plugin (e.g., only labels, only CRDs).
* **Error Handling & Logging**: Ensure plugin failures fail the build rather than silently skip.
* **Documentation**: Each plugin should include a `README.md` with usage examples and flags.
* **Compatibility**: Test plugins against the Kustomize version used in CI/CD.
* **Security**: Review plugin code for injection or file-system access vulnerabilities.

***

## Summary

Custom Kustomize plugins let you extend the tool’s functionality to meet unique enterprise requirements. By following a clear folder structure, writing focused Go or executable code, and integrating through transformers or generators, you can build reusable, maintainable customizations that integrate seamlessly into your GitOps pipelines.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://dinush-chathurya.gitbook.io/kustomize-e-book/additional-topics/18-custom-kustomize-plugins.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.