mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-06-29 17:41:13 +00:00
Remove kv plugins from docs.
This commit is contained in:
jregan
165
plugin/doc.go
165
plugin/doc.go
@@ -2,11 +2,17 @@
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
/*
|
||||
|
||||
Package plugin contains builtin and example
|
||||
plugins, tests and test libraries, and a code
|
||||
generator for converting a plugin to statically
|
||||
loadable code (see pluginator).
|
||||
|
||||
See ../../docs/plugins.md for a description of
|
||||
writing and testing a plugin. The information
|
||||
here is supplemental to that, and more oriented to
|
||||
how the builting plugins work.
|
||||
|
||||
|
||||
HOW PLUGINS RUN
|
||||
|
||||
@@ -25,21 +31,21 @@ Assume a file 'secGen.yaml' containing
|
||||
If this file were referenced by a kustomization
|
||||
file in its 'generators' field, kustomize would
|
||||
|
||||
* Read 'secGen.yaml'.
|
||||
* Read 'secGen.yaml'.
|
||||
|
||||
* Use the value of $XGD_CONFIG_HOME and
|
||||
'apiversion' and to find an executable
|
||||
named 'SecretGenerator' to use as
|
||||
an exec plugin, or failing that,
|
||||
* Use the value of $XGD_CONFIG_HOME and
|
||||
'apiversion' and to find an executable
|
||||
named 'SecretGenerator' to use as
|
||||
an exec plugin, or failing that,
|
||||
|
||||
* use the same info to load a Go plugin
|
||||
object file called 'SecretGenerator.so'.
|
||||
* use the same info to load a Go plugin
|
||||
object file called 'SecretGenerator.so'.
|
||||
|
||||
* Send either the file name 'secGen.yaml' as
|
||||
the first arg to the exec plugin, or send its
|
||||
contents to the go plugin's Config method.
|
||||
* Send either the file name 'secGen.yaml' as
|
||||
the first arg to the exec plugin, or send its
|
||||
contents to the go plugin's Config method.
|
||||
|
||||
* Use the plugin to generate and/or transform.
|
||||
* Use the plugin to generate and/or transform.
|
||||
|
||||
|
||||
GO PLUGINS
|
||||
@@ -50,41 +56,19 @@ which useful functions are attached.
|
||||
|
||||
It can further be used as a _kustomize_ plugin if
|
||||
the symbol is named 'KustomizePlugin' and the
|
||||
attached functions implement the Configurable,
|
||||
Generator and Transformer interfaces.
|
||||
attached functions implement the `Configurable`,
|
||||
`Generator` and `Transformer` interfaces.
|
||||
|
||||
A plugin won't load into some program foo/main.go
|
||||
A plugin won't load into some program `foo/main.go`
|
||||
if there is any package version mismatch in the
|
||||
dependencies of the plugin and the dependencies of
|
||||
foo/main.go. Control this with matching
|
||||
declarations in go.mod files. The versions of the
|
||||
declarations in `go.mod` files. The versions of the
|
||||
builtin packages "fmt", "io", "os" (not normally
|
||||
listed in go.mod) etc have the same version as the
|
||||
listed in `go.mod`) etc have the same version as the
|
||||
compiler.
|
||||
|
||||
|
||||
ONE PLUGIN PER DIRECTORY
|
||||
|
||||
For kustomize (and perhaps anyone), it's simplest
|
||||
to put each plugin into its own directory.
|
||||
|
||||
Go plugins must be in package `main`, and so
|
||||
having more than one plugin in a directory means
|
||||
their loading symbols have to differ, which makes
|
||||
it hard to standardize around how they get loaded,
|
||||
or it means one must use build tags to suppress
|
||||
full directory compilation - which creates
|
||||
difficulties using IDEs, the `go mod` tool, `go
|
||||
test ./...`, etc.
|
||||
|
||||
A one plugin per directory policy makes it easy to
|
||||
define the plugin as a module, with its own
|
||||
`go.mod` file - which is vital for resolving
|
||||
package version dependency mismatches at load
|
||||
time. It also makes it easy to create a plugin
|
||||
tarball (source, test, go.mod, plugin data files,
|
||||
etc.) for distribution.
|
||||
|
||||
|
||||
BUILTIN PLUGIN CONFIGURATION
|
||||
|
||||
@@ -96,7 +80,6 @@ follows.
|
||||
|
||||
The plugin config file looks like
|
||||
|
||||
---------------------------------------------
|
||||
apiVersion: builtin
|
||||
kind: SecretGenerator
|
||||
metadata:
|
||||
@@ -104,20 +87,14 @@ The plugin config file looks like
|
||||
otherField1: whatever
|
||||
otherField2: whatever
|
||||
...
|
||||
---------------------------------------------
|
||||
|
||||
The apiVersion must be 'builtin'. The kind is the
|
||||
CamelCase name of the plugin.
|
||||
The apiVersion must be 'builtin'.
|
||||
The kind is the CamelCase name of the plugin.
|
||||
|
||||
For non-builtins the apiVersion can be any legal
|
||||
apiVersion value, e.g. 'someteam.example.com/v1beta1'
|
||||
|
||||
The builtin source must be at:
|
||||
The source for a builtin plugin must be at:
|
||||
|
||||
repo=$GOPATH/src/sigs.k8s.io/kustomize
|
||||
${repo}/plugin/${apiVersion}/LOWERCASE(${kind})/${kind}.go
|
||||
|
||||
(dropping the ".go" for exec plugins).
|
||||
${repo}/plugin/builtin/LOWERCASE(${kind})/${kind}
|
||||
|
||||
k8s wants 'kind' values to follow CamelCase, while
|
||||
Go style doesn't like but does allow such names.
|
||||
@@ -129,36 +106,9 @@ optional associated files (possibly a go.mod file).
|
||||
|
||||
PLUGIN SOURCE
|
||||
|
||||
* Pattern
|
||||
|
||||
secretgenerator.go
|
||||
---------------------------------------------
|
||||
//go:generate go run sigs.k8s.io/kustomize/cmd/pluginator
|
||||
package main
|
||||
import ...
|
||||
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 {...}
|
||||
---------------------------------------------
|
||||
|
||||
The plugin name doesn't appear in the file itself.
|
||||
|
||||
* Compilation
|
||||
|
||||
repo=$GOPATH/src/sigs.k8s.io/kustomize
|
||||
dir=$repo/plugin/builtin
|
||||
go build -buildmode plugin \
|
||||
-o $dir/secretgenerator.so \
|
||||
$dir/secretgenerator.go
|
||||
|
||||
|
||||
See ../../docs/plugins.md
|
||||
for a description of writing and testing
|
||||
a plugin.
|
||||
|
||||
BUILTIN PLUGIN GENERATION
|
||||
|
||||
@@ -169,43 +119,40 @@ code.
|
||||
|
||||
It arises from following requirements:
|
||||
|
||||
* extension
|
||||
* extension
|
||||
kustomize does two things - generate or
|
||||
transform k8s resources. Plugins let
|
||||
users write their own G&T's without
|
||||
having to fork kustomize and learn its
|
||||
internals.
|
||||
|
||||
kustomize does two things - generate or
|
||||
transform k8s resources. Plugins let
|
||||
users write their own G&T's without
|
||||
having to fork kustomize and learn its
|
||||
internals.
|
||||
* dogfooding
|
||||
A G&T extension framework one can trust
|
||||
should be used by its authors to deliver
|
||||
builtin G&T's.
|
||||
|
||||
* dogfooding
|
||||
|
||||
A G&T extension framework one can trust
|
||||
should be used by its authors to deliver
|
||||
builtin G&T's.
|
||||
|
||||
* distribution
|
||||
|
||||
kustomize should be distributable via
|
||||
`go get` and should run where Go
|
||||
* distribution
|
||||
kustomize should be distributable via
|
||||
`go get` and should run where Go
|
||||
programs are expected to run.
|
||||
|
||||
The extension requirement led to the creation
|
||||
of a framework that accommodates writing a
|
||||
G or T as either
|
||||
The extension requirement led to the creation
|
||||
of a framework that accommodates writing a
|
||||
G or T as either
|
||||
|
||||
* an 'exec' plugin (any executable file
|
||||
runnable as a kustomize subprocess), or
|
||||
* an 'exec' plugin (any executable file
|
||||
runnable as a kustomize subprocess), or
|
||||
|
||||
* as a Go plugin - see
|
||||
https://golang.org/pkg/plugin.
|
||||
* as a Go plugin - see
|
||||
https://golang.org/pkg/plugin.
|
||||
|
||||
The dogfooding (and an implicit performance
|
||||
requirement) requires a 'builtin' G or T to
|
||||
be written as a Go plugin.
|
||||
The dogfooding (and an implicit performance
|
||||
requirement) requires a 'builtin' G or T to
|
||||
be written as a Go plugin.
|
||||
|
||||
The distribution ('go get') requirement demands
|
||||
conversion of Go plugins to statically linked
|
||||
code, hence this program.
|
||||
The distribution ('go get') requirement demands
|
||||
conversion of Go plugins to statically linked
|
||||
code, hence this program.
|
||||
|
||||
|
||||
TO GENERATE CODE
|
||||
@@ -222,7 +169,6 @@ etc.
|
||||
|
||||
Generated plugins are used in kustomize via
|
||||
|
||||
---------------------------------------------
|
||||
package whatever
|
||||
import "sigs.k8s.io/kustomize/plugin/builtin
|
||||
...
|
||||
@@ -231,7 +177,6 @@ Generated plugins are used in kustomize via
|
||||
resources, err := g.Generate()
|
||||
err = g.Transform(resources)
|
||||
// Eventually emit resources.
|
||||
---------------------------------------------
|
||||
|
||||
*/
|
||||
package plugin
|
||||
|
||||
Reference in New Issue
Block a user