Merge pull request #1141 from monopole/releaseNotes

Update 2.1 release notes.

README.md

@@ -156,8 +156,8 @@ is governed by the [Kubernetes Code of Conduct].
 [community page]: http://kubernetes.io/community/
 [declarative configuration]: docs/glossary.md#declarative-application-management
 [eschewed feature list]: docs/eschewedFeatures.md
-[imageBase]: docs/base.jpg
-[imageOverlay]: docs/overlay.jpg
+[imageBase]: docs/images/base.jpg
+[imageOverlay]: docs/images/overlay.jpg
 [kind/feature]: https://github.com/kubernetes-sigs/kustomize/labels/kind%2Ffeature
 [kubectl]: https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement
 [kubernetes style]: docs/glossary.md#kubernetes-style-object

docs/glossary.md

@@ -19,6 +19,7 @@
 [kubernetes]: #kubernetes
 [kustomize]: #kustomize
 [kustomization]: #kustomization
+[kustomizations]: #kustomization
 [off-the-shelf]: #off-the-shelf-configuration
 [overlay]: #overlay
 [overlays]: #overlay
@@ -75,7 +76,8 @@ management in k8s.
 
 ## base
 
-A _base_ is a [kustomization] that some [overlay] modifies.
+A _base_ is a [kustomization] referred to
+by some other [kustomization].
 
 Any kustomization, including an [overlay], can be a base to
 another kustomization.
@@ -135,6 +137,12 @@ In brief, kustomize should
    specific languages, etc., frustrating the other
    goals.
 
+## generator
+
+A generator makes resources that can be used as is,
+or fed into a [transformer].
+
+
 ## gitops
 
 Devops or CICD workflows that use a git repository as a
@@ -301,14 +309,13 @@ own [overlays] to do further customization.
 
 ## overlay
 
-An _overlay_ is a kustomization that modifies (and thus
-depends on) another kustomization.
+An _overlay_ is a kustomization that depends on
+another kustomization.
 
-The [kustomization] in an overlay refers to (via file
-path, URI or other method) some other kustomization,
-known as its [base].
+The [kustomizations] an overlay refers to (via file
+path, URI or other method) are called [bases].
 
-An overlay is unusable without its base.
+An overlay is unusable without its bases.
 
 An overlay may act as a base to another overlay.
 
@@ -444,6 +451,12 @@ needed to create customized resources to send to the
 
 A target can be a [base] or an [overlay].
 
+## transformer
+
+A transformer can modify a resource, or merely
+visit it and collect information about it in the
+course of a `kustomize build`.
+
 ## variant
 
 A _variant_ is the outcome, in a cluster, of applying

docs/inventory_object.md

@@ -10,10 +10,12 @@ inventory:
 ```
 
 ### Motivation
-If present, `Kustomize build` will make an _inventory_ object,
-which  could be a ConfigMap, or an App(to be added),
- which can be consumed by a client such as those under development in
+
+If present, `kustomize build` will make an _inventory_ object,
+which  could be a ConfigMap, or an App (to be added),
+which can be consumed by a client such as those under development in
 [cli-experimental](https://github.com/kubernetes-sigs/cli-experimental).
+
 The client can recognize this object by name and use it to do a better job
 with actions like `apply`, `prune` and `delete`.
 

docs/v_2.1.0.md

@@ -1,25 +1,179 @@
 # kustomize 2.1.0
 
-  _WIP, release target date May 20 2019_
-  _TODO: provide details; this is just a high level list_
 
- * The `inventory` field. See [inventory object](inventory_object.md).
+[Go modules]: https://github.com/golang/go/wiki/Modules
+[generator options]: ../examples/generatorOptions.md
+[imgModules]: images/goModules.png
+[imgPlugins]: images/plugins.png
+[imgPruning]: images/pruning.png
+[imgWheels]: images/abandonedTrainingWheels.png
+[kustomization]: glossary.md#kustomization
+[_kustomization_]: glossary.md#kustomization
+[base]: glossary.md#base
+[bases]: glossary.md#base
+[_base_]: glossary.md#base
+[kustomize inventory object documentation]: inventory_object.md
+[kustomize plugin documentation]: plugins.md
+[root]: glossary.md#kustomization-root
+[transformer configs]: ../examples/transformerconfigs
+[v1.0.9]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v1.0.9
+[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.0.3
+[v2.1.0]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.1.0
+[versioning policy]: versioningPolicy.md
 
- * The `generators` and `transformers` fields.
-   See [plugins](plugins.md).
+_Summary_: Go modules, inventory, plugins, eased
+loading restrictions, and about ~80 issues closed
+since [v2.0.3] (over 300 commits).
 
- * The `--load_restrictions none` flag.
 
- * Field changes / deprecations (use `kustomize fix`)
 
-   * The `resources` field generalized,
-     `bases` field deprecated.
+## Go modules
 
-   * New `envs` sub-field introduced to both
-     `configMapGenerators` and `secretGenerators`,
-     replacing the deprecated `env` field
-     (allowing mixins of k=v pairs from different files).
+![gopher with boxes][imgModules]
 
- * GO modules
+Kustomize now defines its dependencies in a top
+level `go.mod` file.  This is the first step
+towards a package structure intentially exported
+as one or more [Go modules] for use in other
+programs (kubectl, kubebuilder, etc.) and in
+kustomize plugins (see below).
 
- * Last release with completely unsupported access to `pkg`.
+
+## Inventory generation for pruning
+
+![pruning dead branches][imgPruning]
+
+Users can add an `inventory` stanza to their
+kustomization file, to add a special _inventory
+object_ to the `build` result.
+
+This object applies to the cluster along with
+everything else in the build result and can be
+used by other clients to intelligently _prune_
+orphaned cluster resources.
+
+For more information see the
+[kustomize inventory object documentation].
+
+
+## Generator and transformer plugins
+
+![kid putting knife in electrical outlet][imgPlugins]
+
+Since the beginning (as `kinflate` back in Sep
+2017), kustomize has read or generated resources,
+applied a series of pipelined transformation to
+them, and emitted the result to `stdout`.
+
+At that time, the only way to change the behavior
+of a generator (e.g. a secret generator), or
+change the behavior of a transformer (e.g. a name
+changer, or json patcher), was to modify source
+code and put out a release.
+
+[v1.0.9] introduced [generator options] as a means
+to change the behavior of the only two generators
+available at the time - Secret and ConfigMap
+generators.  It also introduced
+[transformer configs] as a way to fine tune the
+targets of transformations (e.g. to which fields
+_selectors_ should be added).  Most of the feature
+requests for kustomize revolve around changing the
+behavior of the builtin generators and
+transformers.
+
+[v2.1.0] adds a _alpha_ plugin framework, that
+encourages users to write their own generators or
+transformers, _declaring them as kubernetes
+objects just like everything else_, and apply them
+as part of the `kustomize build` process.
+
+To inform the API exposed to plugins, and to
+confirm that the plugin framework can offer plugin
+authors the same capabilities as builtin
+operations, all the builtin generators and
+tranformers have been converted to plugin form
+(with a few exceptions awaiting Go module
+refinements).  This means that adding, say, a
+`secretGenerator` or `commonAnnotations` directive
+to your kustomization will (in [v2.1.0]) trigger
+execution of
+[code committed as a plugin](../plugin/builtin).
+
+For more information, see the
+[kustomize plugin documentation].
+
+## Remove load restrictions
+
+![removed training wheels][imgWheels]
+
+The following usage:
+
+```
+kustomize build --load_restrictions none $target
+```
+
+allows a `kustomization.yaml` file used in this
+build to refer to files outside its own directory
+(i.e. outside its [root]).
+
+This is an opt-in to suppress a security feature
+that denies this precise behavior.
+
+This feature should only be used to allow multiple
+overlays (e.g. prod, staging and dev) to share a
+patch file.  To share _resources_, use a relative
+path or URL to a kustomization directory in the
+`resources` directive.
+
+
+## Field changes / deprecations
+
+* Generalized `resources` field.
+
+  The `resources` field has been generalized, and
+  can now accept what formerly could only
+  be specified in the `bases` field.
+
+  This change was made so that the `resources`,
+  `generators` and `transformers` fields all
+  accept the same argument format.
+
+  Each field's argument is a _string list_, where
+  each entry is either a _resource_ (a relative
+  path to a YAML file) or a [_kustomization_] (a
+  relative path or URL pointing to a directory
+  with a kustomization file).  A kustomization
+  directory used in this context is called a
+  [_base_].
+
+  The `bases` field still works, but is no longer
+  necessary, and will likely be deprecated in the
+  next release.  The _base_ as a concept is as
+  important as ever, it's just that two new fields
+  (`generators` and `tranformers`) and one existing
+  field (`resources`) now accept arguments
+  that were once accepted only by `bases`.
+
+  The fact that the `generators` and
+  `transformers` field accept [bases]
+  (i.e. kustomization directories) and the fact
+  that generator and transformer configuration
+  objects are normal k8s resources means that one
+  can generate or transform a generator or a
+  transformer (see [TestTransformerTransformers]).
+
+[TestTransformerTransformers]: ../pkg/target/transformerplugin_test.go
+
+* Consistent `envs` field for Secret and
+  ConfigMap generators.
+
+  An `envs` sub-field has been added to both
+  `configMapGenerator` and `secretGenerator`,
+  replacing the now deprecated (and singular)
+  `env` field.  The new field accepts lists, just
+  like its sibling fields `files` and `literals`.
+
+Optionally `kustomize edit fix` to edit your
+kustomization file (e.g. merge singular `env`
+field into a plural field).

docs/workflows.md

@@ -11,8 +11,8 @@
 [patches]: glossary.md#patch
 [rebase]: https://git-scm.com/docs/git-rebase
 [resources]: glossary.md#resource
-[workflowBespoke]: workflowBespoke.jpg
-[workflowOts]: workflowOts.jpg
+[workflowBespoke]: images/workflowBespoke.jpg
+[workflowOts]: images/workflowOts.jpg
 [kubectl-v1.14.0]:https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/
 
 # workflows

docs/zh/workflows.md

@@ -11,8 +11,8 @@
 [patches]: ../glossary.md#patch
 [rebase]: https://git-scm.com/docs/git-rebase
 [resources]: ../glossary.md#resource
-[workflowBespoke]: ../workflowBespoke.jpg
-[workflowOts]: ../workflowOts.jpg
+[workflowBespoke]: ../images/workflowBespoke.jpg
+[workflowOts]: ../images/workflowOts.jpg
 [kubectl-v1.14.0]:https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/
 
 # 工作流

examples/README.md

@@ -4,7 +4,7 @@ English | [简体中文](zh/README.md)
 
 These examples assume that `kustomize` is on your `$PATH`.
 
-They are covered by [pre-commit](../bin/pre-commit.sh)
+They are covered by [pre-commit](../travis/pre-commit.sh)
 tests, and should work with HEAD
 
 <!-- @installkustomize @test -->

examples/zh/README.md

@@ -4,7 +4,7 @@
 
 这些示例默认 `kustomize` 在您的 `$PATH` 中。
 
-这些示例通过了 [pre-commit](../../bin/pre-commit.sh) 测试，并且应该与 HEAD 一起使用。
+这些示例通过了 [pre-commit](../../travis/pre-commit.sh) 测试，并且应该与 HEAD 一起使用。
 
 ```
 go get sigs.k8s.io/kustomize

pkg/hasher/hasher.go

@@ -26,7 +26,7 @@ func SortArrayAndComputeHash(s []string) (string, error) {
 func Encode(hex string) (string, error) {
 	if len(hex) < 10 {
 		return "", fmt.Errorf(
-			"input length must be at least 10.")
+			"input length must be at least 10")
 	}
 	enc := []rune(hex[:10])
 	for i := range enc {