Start directory for 'untested' plugins.

hack/testUnitKustomizePlugins.sh

@@ -55,13 +55,9 @@ if onLinuxAndNotOnRemoteCI; then
   make $(go env GOPATH)/bin/kubeval
 fi
 
-for goMod in $(find ./plugin -name 'go.mod'); do
+for goMod in $(find ./plugin -name 'go.mod' -not -path "./plugin/untested/*"); do
   d=$(dirname "${goMod}")
-  if [[ "$d" == "./plugin/someteam.example.com/v1/gogetter" ]]; then
+  scanDir $d
-    echo "Skipping broken $d"
-  else
-    scanDir $d
-  fi
 done
 
 if [ $rcAccumulator -ne 0 ]; then

plugin/README.md

@@ -1,27 +1,87 @@
-This directory and the directories below it
+# kustomize plugins
-are not _importable_ Go packages.
 
-Each directory contains a kustomize plugin,
+This directory holds [kustomize plugins][extending kustomize],
-which is either 
+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.
 
-* some random non-Go based executable, 
+ * `someteam.example.com/v1`
-  e.g. a bash script that runs java
-  in a JVM, or python in a python VM, etc.
 
-* the source code for a Go executable,
+   Example plugins, maintained
-  i.e. a `main.go` in the unimportable
+   and tested by the kustomize maintainers,
-  `main` package,
+   but not built-in to kustomize.
-  ideally declaring its dependencies
+   
-  with it's own `go.mod` file.
+   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.
 
-* the source code for a Go
+#### Testing
-  plugin, which is also an unimportable
-  `main` package ideally with its
-  own `go.mod` file, formulated to be
-  a Go plugin.  If in the `builtin`
-  sub-directory, these plugins are converted
-  to statically linkable code.
 
-To read more about plugins, see
+Regardless of the [style](#plugin-styles) used to write a plugin,
-[doc.go](/api/internal/plugins/doc.go)
+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:
+```
+cd plugin/someteam.example.com/v1/bashedconfigmap
+go test -v .
+```
+and examine the associated Go test code.
+
+### 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/