kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-05-17 18:25:26 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

start v2.1 release notes

Browse Source
This commit is contained in:
Jeffrey Regan
2019-04-30 06:32:50 -07:00
parent 09f2157a92
commit 61cf67fb95
4 changed files with 98 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/README.md
View File

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

12
docs/glossary.md
View File

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

84
docs/plugins.md
View File

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

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