kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-13 10:00:56 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Merge pull request #1030 from monopole/startReleaseNotes

Browse Source 
start v2.1 release notes
This commit is contained in:
Jeff Regan
2019-04-30 07:10:21 -07:00
committed by GitHub
parent 09f2157a92 61cf67fb95
commit a43dffdeda
4 changed files with 98 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/README.md
View File

@@ -1,28 +1,43 @@
# Kustomize docs # Documentation
* [installation instructions](INSTALL.md) ## General
* [Installation instructions](INSTALL.md)
* [FAQ](FAQ.md) * [FAQ](FAQ.md)
* [kustomization.yaml](kustomization.yaml) - Example of a * [Glossary](glossary.md)
[kustomization](glossary.md#kustomization)
## 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. with explanations of each field.
* [plugins](plugins.md) Extending kustomize with custom generators and transformers. * [Plugins](plugins.md) - extending kustomize with
custom generators and transformers.
* [versioning policy](versioningPolicy.md) - How the code and the kustomization * [Workflows](workflows.md) - steps one might take in
file evolve in time. using bespoke and off-the-shelf configurations.
* [version 2.0.0](version2.0.0.md) - Release notes for Kustomize 2.0.0. ## Release notes
* [workflow](workflows.md) - Some steps one might take in using * [2.1](version2.1.0.md)
bespoke and off-the-shelf configurations.
* [glossary](glossary.md) - An attempt to disambiguiate terminology. * [2.0](version2.0.0.md)
* [eschewed features](eschewedFeatures.md) - Why certain features are (currently) ## Policies
not supported in Kustomize.
* [contributing guidelines](../CONTRIBUTING.md) - Please read before sending a PR. * [Versioning](versioningPolicy.md) - how the code and
the kustomization file evolve in time.
* [code of conduct](../code-of-conduct.md) * [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)

2
docs/glossary.md
View File

@@ -400,7 +400,7 @@ A chunk of code used by kustomize, but not necessarily
compiled into kustomize, to generate and/or transform a compiled into kustomize, to generate and/or transform a
kubernetes resource as part of a kustomization. kubernetes resource as part of a kustomization.
Details [here][plugins.md]. Details [here](plugins.md).
## resource ## resource

78
docs/plugins.md
View File

@@ -1,20 +1,20 @@
# kustomize plugins # kustomize plugins
Kustomize offers a plugin framework for people to 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 chart processor, a generator that automatically
attaches a Service and Ingress object to each 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 (e.g. a transformer that does some highly
customized processing of the container command customized processing of the container command
line). line).
## Specification in `kustomization.yaml` ## Specification in `kustomization.yaml`
A kustomization file has two new fields in v2.1: Start by adding a `generators:` and/or `transformers:`
_generators_ and _transformers_. field to your kustomization.
Each accepts a list of strings as its arguments: Each field is a string array:
> ``` > ```
> generators: > generators:
@@ -30,7 +30,7 @@ Each accepts a list of strings as its arguments:
This is exactly like the syntax of the `resources` field. This is exactly like the syntax of the `resources` field.
The value of each entry in a `resources`, `generators` 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]. YAML file, or a path or URL to a [kustomization].
[kustomization]: glossary.md#kustomization [kustomization]: glossary.md#kustomization
@@ -45,7 +45,7 @@ _Each_ object resulting from a `generators` or
`transformers` field is now further interpreted by `transformers` field is now further interpreted by
kustomize as a _plugin configuration_ object. kustomize as a _plugin configuration_ object.
## Configuration and execution ## Configuration
A kustomization file could have the following lines: A kustomization file could have the following lines:
@@ -56,7 +56,7 @@ generators:
Given this, the kustomization process would expect to Given this, the kustomization process would expect to
find a file called `chartInflator.yaml` in the 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: The file `chartInflator.yaml` could contain:
@@ -90,6 +90,11 @@ The specified order of transformers in the
`transformers` field is, however, respected, as `transformers` field is, however, respected, as
transformers aren't expected to be commutative. 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 Generator plugins are run after processing the
`resources` field (which _reads_ resources), to `resources` field (which _reads_ resources), to
_create_ additional resources. _create_ additional resources.
@@ -105,7 +110,7 @@ transformers run in the order specified.
[k8s object]: glossary.md#kubernetes-style-object [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 other [k8s object]), kustomize will first look for an
_executable_ file called _executable_ file called
@@ -126,31 +131,30 @@ kustomize build.
A `kustomize build` attempt with plugins that A `kustomize build` attempt with plugins that
omits the flag omits the flag
TODO: Change flag
> `--enable_alpha_goplugins_accept_panic_risk` > `--enable_alpha_goplugins_accept_panic_risk`
will fail with a warning about plugin use. will fail with a warning about plugin use.
_TODO: Change flag_
Flag use is an opt-in acknowledging the absence of 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 someone who blindly downloads a kustomization from
the internet and attempts to run it, without the internet and attempts to run it, without
realizing that it might attempt to run 3rd party 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 ## Writing plugins
### Exec plugins ### Exec plugins
TODO: Add ptr to example. _TODO: Add ptr to example._
A exec plugin is any executable that accepts a A exec plugin is any executable that accepts a
single argument on it's command line - the name of single argument on its command line - the name of
a YAML file containing its configuration (which it a YAML file containing its configuration.
presumably reads if it needs additional
configuration).
A generator plugin accepts nothing on `stdin`, but emits A generator plugin accepts nothing on `stdin`, but emits
generated resources to `stdout`. generated resources to `stdout`.
@@ -159,10 +163,13 @@ A transformer plugin accepts resource YAML on `stdin`,
and emits those resources, possibly transformed, to and emits those resources, possibly transformed, to
`stdout`. `stdout`.
kustomize uses an exec plugin adapter to provide
marshalled resources on `stdin` and capture
`stdout` for further processing.
### Go plugins ### Go plugins
TODO: Add ptr to example. _TODO: Add ptr to example._
[Go plugin]: https://golang.org/pkg/plugin/ [Go plugin]: https://golang.org/pkg/plugin/
@@ -173,9 +180,12 @@ A [Go plugin] for kustomize looks like this:
> >
> package main > 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 > var KustomizePlugin plugin
@@ -196,8 +206,7 @@ shown is _required_.
The plugin author should of course change the The plugin author should of course change the
contents of the `plugin` struct, and the three contents of the `plugin` struct, and the three
method bodies, and the import statements, as method bodies, and add imports as desired.
desired.
Here's a build command, which assumes the plugin Here's a build command, which assumes the plugin
source code is sitting right next to where the source code is sitting right next to where the
@@ -210,11 +219,6 @@ go build -buildmode plugin -tags=plugin \
$dir/${kind}.go $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 #### Caveats
@@ -228,15 +232,14 @@ Go plugins allow kustomize extensions that
subprocess and marshalling/unmarshalling data subprocess and marshalling/unmarshalling data
for each plugin run. 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 [ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format
Go plugin compilation creates an [ELF] formatted Go plugins work as [defined][Go plugin], but fall
`.so` file, which by definition has no information short of what many people think of when they hear
about the _provenance_ of the file. 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, One cannot know which version of Go was used,
which packages were imported (and their version), 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 the main program ELF and the plugin ELF will cause
a failure at load time. 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. suffer from the skew problem.

18
docs/version2.1.0.md Normal file
View File

@@ -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).