diff --git a/docs/README.md b/docs/README.md index e8d107480..d7786c882 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,28 +1,43 @@ -# Kustomize docs +# Documentation - * [installation instructions](INSTALL.md) +## General + + * [Installation instructions](INSTALL.md) * [FAQ](FAQ.md) - * [kustomization.yaml](kustomization.yaml) - Example of a - [kustomization](glossary.md#kustomization) + * [Glossary](glossary.md) + +## Examples + + * [Examples](../examples) - detailed walkthroughs of various + workflows and concepts. + + * [kustomization.yaml](kustomization.yaml) - a + [kustomization](glossary.md#kustomization) file with explanations of each field. - * [plugins](plugins.md) Extending kustomize with custom generators and transformers. - - * [versioning policy](versioningPolicy.md) - How the code and the kustomization - file evolve in time. + * [Plugins](plugins.md) - extending kustomize with + custom generators and transformers. - * [version 2.0.0](version2.0.0.md) - Release notes for Kustomize 2.0.0. + * [Workflows](workflows.md) - steps one might take in + using bespoke and off-the-shelf configurations. - * [workflow](workflows.md) - Some steps one might take in using - bespoke and off-the-shelf configurations. +## Release notes - * [glossary](glossary.md) - An attempt to disambiguiate terminology. + * [2.1](version2.1.0.md) - * [eschewed features](eschewedFeatures.md) - Why certain features are (currently) - not supported in Kustomize. + * [2.0](version2.0.0.md) - * [contributing guidelines](../CONTRIBUTING.md) - Please read before sending a PR. +## Policies - * [code of conduct](../code-of-conduct.md) + * [Versioning](versioningPolicy.md) - how the code and + the kustomization file evolve in time. + + * [Eschewed features](eschewedFeatures.md) - why certain features + are (currently) not supported in kustomize. + + * [Contributing guidelines](../CONTRIBUTING.md) - please read + before sending a PR. + + * [Code of conduct](../code-of-conduct.md) diff --git a/docs/glossary.md b/docs/glossary.md index 005d348eb..aadd4dc42 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -167,9 +167,9 @@ categories: Example fields: _resources_, _crds_. * _generators_ - what _new_ resources should be created. - Example fields: _configMapGenerator_ (legacy), + Example fields: _configMapGenerator_ (legacy), _secretGenerator_ (legacy), _generators_ (v2.1). - + * _transformers_ - what to _do_ to the aforementioned resources. Example fields: _namePrefix_, _nameSuffix_, _images_, _commonLabels_, _patchesJson6902_, etc. and the more @@ -366,11 +366,11 @@ value, e.g. an image tag. By default, an SMP _replaces_ values. This usually desired when the target value is a simple -string, but may not be desired when the target +string, but may not be desired when the target value is a list. -To change this -default behavior, add a _directive_. Recognized +To change this +default behavior, add a _directive_. Recognized directives include _replace_ (the default), _merge_ (avoid replacing a list), _delete_ and a few more (see [these notes][strategic-merge]). @@ -400,7 +400,7 @@ A chunk of code used by kustomize, but not necessarily compiled into kustomize, to generate and/or transform a kubernetes resource as part of a kustomization. -Details [here][plugins.md]. +Details [here](plugins.md). ## resource diff --git a/docs/plugins.md b/docs/plugins.md index d1846f9f7..094dde717 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -1,20 +1,20 @@ # kustomize plugins Kustomize offers a plugin framework for people to -write their own resource generators (e.g. a helm +write their own resource _generators_ (e.g. a helm chart processor, a generator that automatically attaches a Service and Ingress object to each -Deployment) and their own resource transformers +Deployment) and their own resource _transformers_ (e.g. a transformer that does some highly customized processing of the container command line). ## Specification in `kustomization.yaml` -A kustomization file has two new fields in v2.1: -_generators_ and _transformers_. +Start by adding a `generators:` and/or `transformers:` +field to your kustomization. -Each accepts a list of strings as its arguments: +Each field is a string array: > ``` > generators: @@ -24,13 +24,13 @@ Each accepts a list of strings as its arguments: > - https://github.com/org/repo/some/kustomization > > transformers: -> - {as above} +> - {as above} > ``` This is exactly like the syntax of the `resources` field. The value of each entry in a `resources`, `generators` -or `transformers` list must be a relative path to a +or `transformers` array must be a relative path to a YAML file, or a path or URL to a [kustomization]. [kustomization]: glossary.md#kustomization @@ -45,7 +45,7 @@ _Each_ object resulting from a `generators` or `transformers` field is now further interpreted by kustomize as a _plugin configuration_ object. -## Configuration and execution +## Configuration A kustomization file could have the following lines: @@ -56,7 +56,7 @@ generators: Given this, the kustomization process would expect to find a file called `chartInflator.yaml` in the -kustomization [root](glossary.md#root). +kustomization [root](glossary.md#kustomization-root). The file `chartInflator.yaml` could contain: @@ -90,6 +90,11 @@ The specified order of transformers in the `transformers` field is, however, respected, as transformers aren't expected to be commutative. +## Execution + +Plugins are only used during a run of the +`kustomize build` command. + Generator plugins are run after processing the `resources` field (which _reads_ resources), to _create_ additional resources. @@ -105,7 +110,7 @@ transformers run in the order specified. [k8s object]: glossary.md#kubernetes-style-object -Given a configuration object (whick looks like any +Given a plugin configuration object (it looks like any other [k8s object]), kustomize will first look for an _executable_ file called @@ -126,31 +131,30 @@ kustomize build. A `kustomize build` attempt with plugins that omits the flag -TODO: Change flag - > `--enable_alpha_goplugins_accept_panic_risk` will fail with a warning about plugin use. +_TODO: Change flag_ + Flag use is an opt-in acknowledging the absence of -plugin provenance. Its meant to give pause to +plugin provenance. It's meant to give pause to someone who blindly downloads a kustomization from the internet and attempts to run it, without realizing that it might attempt to run 3rd party -code. - +code in plugin form. The plugin would have to be +installed already, but nevertheless the flag is a +reminder. ## Writing plugins ### Exec plugins -TODO: Add ptr to example. +_TODO: Add ptr to example._ A exec plugin is any executable that accepts a -single argument on it's command line - the name of -a YAML file containing its configuration (which it -presumably reads if it needs additional -configuration). +single argument on its command line - the name of +a YAML file containing its configuration. A generator plugin accepts nothing on `stdin`, but emits generated resources to `stdout`. @@ -159,10 +163,13 @@ A transformer plugin accepts resource YAML on `stdin`, and emits those resources, possibly transformed, to `stdout`. +kustomize uses an exec plugin adapter to provide +marshalled resources on `stdin` and capture +`stdout` for further processing. ### Go plugins -TODO: Add ptr to example. +_TODO: Add ptr to example._ [Go plugin]: https://golang.org/pkg/plugin/ @@ -170,13 +177,16 @@ A [Go plugin] for kustomize looks like this: > ``` > +build plugin -> +> > package main > -> import ... +> import ( +> "sigs.k8s.io/kustomize/pkg/ifc" +> "sigs.k8s.io/kustomize/pkg/resmap" +> ... +> ) > -> // go:generate go run sigs.k8s.io/kustomize/cmd/pluginator -> type plugin struct{...} +> type plugin struct {...} > > var KustomizePlugin plugin > @@ -196,8 +206,7 @@ shown is _required_. The plugin author should of course change the contents of the `plugin` struct, and the three -method bodies, and the import statements, as -desired. +method bodies, and add imports as desired. Here's a build command, which assumes the plugin source code is sitting right next to where the @@ -210,11 +219,6 @@ go build -buildmode plugin -tags=plugin \ $dir/${kind}.go ``` -For the person willing to compile not just a -plugin but all of kustomze as well, a code -generator will be provided that will convert a Go -plugin to statically linked code in your own -compiled version of kustomize. #### Caveats @@ -228,15 +232,14 @@ Go plugins allow kustomize extensions that subprocess and marshalling/unmarshalling data for each plugin run. -Go plugins work as [defined][Go plugin], but -fall short of what many people think of when they -hear the word _plugin_. - [ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format -Go plugin compilation creates an [ELF] formatted -`.so` file, which by definition has no information -about the _provenance_ of the file. +Go plugins work as [defined][Go plugin], but fall +short of what many people think of when they hear +the word _plugin_. Go plugin compilation creates +an [ELF] formatted `.so` file, which by definition +has no information about the _provenance_ of the +file. One cannot know which version of Go was used, which packages were imported (and their version), @@ -245,6 +248,5 @@ etc. Skew between the compilation conditions of the main program ELF and the plugin ELF will cause a failure at load time. -Exec plugins also lack provenance - but they don't +Exec plugins also lack provenance, but don't suffer from the skew problem. - diff --git a/docs/version2.1.0.md b/docs/version2.1.0.md new file mode 100644 index 000000000..3b47ade73 --- /dev/null +++ b/docs/version2.1.0.md @@ -0,0 +1,18 @@ +# Verision 2.1.0 + +TODO: provide details + + * The `inventory` field. + + * The `generators` and `transformers` fields. + See [plugins](plugins.md). + + * The `--load_restrictions none` flag. + + * The `resources` field generalized, `bases` field deprecated. + + * GO modules + + * The last release with completely unsupported access to `pkg`. + + * Order matters in `resources` (stretch goal).