1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
|
# kustomize plugins
This directory holds [kustomize plugins][extending kustomize],
each in its own sub-directory.
### Directories
* `builtin`
These are plugins written as [Go plugins].
They are converted to statically linked code in the
kustomize binary by a code generator ([pluginator]) at
kustomize build time.
They are maintained as part of kustomize.
* `someteam.example.com/v1`
Example plugins, maintained
and tested by the kustomize maintainers,
but not built-in to kustomize.
Some of these might get promoted to `builtin` someday,
as happened with the [Helm Chart Inflator].
* `untested/v1`
Untested, unmaintained plugins.
These might be former examples that have been abandoned and
may soon be deleted, or they might be WIP plugins that will
someday become examples or builtins.
#### Testing
Regardless of the [style](#plugin-styles) used to write a plugin,
it should be accompanied by a Go unit test, written using the framework
maintained by the kustomize maintainers for just that purpose.
To see how this works, run any plugin test, e.g.
this plugin written in bash:
```
pushd plugin/someteam.example.com/v1/bashedconfigmap
go test -v .
popd
```
For plugins with many tests, it's possible to target just one test:
```
pushd plugin/builtin/patchstrategicmergetransformer
go test -v -run TestBadPatchStrategicMergeTransformer PatchStrategicMergeTransformer_test.go
popd
```
### Plugin styles
For more discussion, see [extending kustomize].
* a bare executable
This can be anything, e.g. a shell script, a shell
script that runs java in a JVM, or python in a python
VM, etc. They accept a YAML stream of resources on
stdin, and emit a YAML stream on stdout. They accept
configuration data in a file specified as the first
argument on their command line.
If the executable is written in Go, it can take advantage
of the same libraries as the kustomize builtin plugins.
* a [KRM function]
These are containerized executables, that are pickier
about their input. Rather than accepting a YAML stream
of k8s resources, they want one `ResourceList` object
(with the resources in that list).
* a [Go plugin]
These are built as shared object libraries. Like
a Go program, they're written in an unimportable
`main` package with its own `go.mod` file.
Go plugins cannot be reliably distributed (see docs),
and are meant only as a structured way to write a
builtin plugin intended for distribution with kustomize.
[pluginator]: ../cmd/pluginator
[Helm Chart Inflator]: ./builtin/helmchartinflationgenerator
[KRM function]: https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md
[Go plugin]: https://golang.org/pkg/plugin
[Go plugins]: https://golang.org/pkg/plugin
[extending kustomize]: https://kubectl.docs.kubernetes.io/guides/extending_kustomize/
|