Have kustomize CLI depend on kustomize Go API v3.3.1

Differentiate the cloud builders.

.gitignore

@@ -4,7 +4,6 @@
 *.dll
 *.so
 *.dylib
-kustomize
 
 # Test binary, build with `go test -c`
 *.test

.travis.yml

@@ -1,45 +1,37 @@
 os:
-# TODO: Enable this when we can get the tests to work
-#  - windows
   - linux
   - osx
+# TODO: Uncomment when tests running on Windows.
+#  - windows
 
 addons:
   apt:
-    packages: tree
+    packages:
+    - tree
   homebrew:
-    packages: tree
-
-language: go
-
-go:
-  - 1.11.x
-
-go_import_path: sigs.k8s.io/kustomize
-
-# Maybe, maybe not.
-# sudo: false
+    packages:
+    - tree
+    update: true
 
 # Only clone the most recent commit.
 git:
   depth: 1
 
-env:
-- GOLANGCI_RELEASE="v1.10.2"
+language: go
+
+go:
+  - "1.12"
+
+go_import_path: sigs.k8s.io/kustomize
 
 before_install:
-  - source ./bin/consider-early-travis-exit.sh
-  - curl -sfL https://install.goreleaser.com/github.com/golangci/golangci-lint.sh | sh -s -- -b $GOPATH/bin ${GOLANGCI_RELEASE}
-  - go get -u github.com/monopole/mdrip
+  - source ./travis/consider-early-travis-exit.sh
 
-# Install must be set to prevent default `go get` to run.
-# The dependencies have already been vendored by `dep` so
-# we don't need to fetch them.
-install:
-  -
+# Skip the install process; let pre-commit.sh do it.
+install: true
 
 script:
-  - ./bin/pre-commit.sh
+  - ./travis/pre-commit.sh
 
 # TBD. Suppressing for now.
 notifications:

Gopkg.lock

@@ -1,389 +0,0 @@
-# This file is autogenerated, do not edit; changes may be undone by the next 'dep ensure'.
-
-
-[[projects]]
-  digest = "1:d8ebbd207f3d3266d4423ce4860c9f3794956306ded6c7ba312ecc69cdfbf04c"
-  name = "github.com/PuerkitoBio/purell"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "0bcb03f4b4d0a9428594752bd2a3b9aa0a9d4bd4"
-  version = "v1.1.0"
-
-[[projects]]
-  branch = "master"
-  digest = "1:8098cd40cd09879efbf12e33bcd51ead4a66006ac802cd563a66c4f3373b9727"
-  name = "github.com/PuerkitoBio/urlesc"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "de5bf2ad457846296e2031421a34e2568e304e35"
-
-[[projects]]
-  digest = "1:a2c1d0e43bd3baaa071d1b9ed72c27d78169b2b269f71c105ac4ba34b1be4a39"
-  name = "github.com/davecgh/go-spew"
-  packages = ["spew"]
-  pruneopts = "NUT"
-  revision = "346938d642f2ec3594ed81d874461961cd0faa76"
-  version = "v1.1.0"
-
-[[projects]]
-  digest = "1:f8e6f07329067bc182633dcb19a3df53ce5d454b551e1b5a1cac2163748648d9"
-  name = "github.com/emicklei/go-restful"
-  packages = [
-    ".",
-    "log",
-  ]
-  pruneopts = "NUT"
-  revision = "3658237ded108b4134956c1b3050349d93e7b895"
-  version = "v2.7.1"
-
-[[projects]]
-  digest = "1:ad32dc29f37281bacb5dcedff17c9461dc1739dc8a5f63a71ab491c6e92edf8d"
-  name = "github.com/evanphx/json-patch"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "afac545df32f2287a079e2dfb7ba2745a643747e"
-  version = "v3.0.0"
-
-[[projects]]
-  digest = "1:81466b4218bf6adddac2572a30ac733a9255919bc2f470b4827a317bd4ee1756"
-  name = "github.com/ghodss/yaml"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "0ca9ea5df5451ffdf184b4428c902747c2c11cd7"
-  version = "v1.0.0"
-
-[[projects]]
-  branch = "master"
-  digest = "1:260f7ebefc63024c8dfe2c9f1a2935a89fa4213637a1f522f592f80c001cc441"
-  name = "github.com/go-openapi/jsonpointer"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "3a0015ad55fa9873f41605d3e8f28cd279c32ab2"
-
-[[projects]]
-  branch = "master"
-  digest = "1:98abd61947ff5c7c6fcfec5473d02a4821ed3a2dd99a4fbfdb7925b0dd745546"
-  name = "github.com/go-openapi/jsonreference"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "3fb327e6747da3043567ee86abd02bb6376b6be2"
-
-[[projects]]
-  branch = "master"
-  digest = "1:e95b560c49fb849a61957a5fb3346ce23b3f67426e00e01179e5396cabc9a12c"
-  name = "github.com/go-openapi/spec"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "bcff419492eeeb01f76e77d2ebc714dc97b607f5"
-
-[[projects]]
-  branch = "master"
-  digest = "1:a610c604eb06f0be4b0fc667388b7a221155d77d7f9089f70ac142a4a9daf014"
-  name = "github.com/go-openapi/swag"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "811b1089cde9dad18d4d0c2d09fbdbf28dbd27a5"
-
-[[projects]]
-  digest = "1:1b3dd24f14a5280710fc7a3aa2480b6e4d20fdfc905841de9a3aa2aa2f1d4ee9"
-  name = "github.com/gogo/protobuf"
-  packages = [
-    "proto",
-    "sortkeys",
-  ]
-  pruneopts = "NUT"
-  revision = "1adfc126b41513cc696b209667c8656ea7aac67c"
-  version = "v1.0.0"
-
-[[projects]]
-  branch = "master"
-  digest = "1:e2b86e41f3d669fc36b50d31d32d22c8ac656c75aa5ea89717ce7177e134ff2a"
-  name = "github.com/golang/glog"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "23def4e6c14b4da8ac2ed8007337bc5eb5007998"
-
-[[projects]]
-  digest = "1:03e14cff610a8a58b774e36bd337fa979482be86aab01be81fb8bbd6d0f07fc8"
-  name = "github.com/golang/protobuf"
-  packages = [
-    "proto",
-    "ptypes",
-    "ptypes/any",
-    "ptypes/duration",
-    "ptypes/timestamp",
-  ]
-  pruneopts = "NUT"
-  revision = "b4deda0973fb4c70b50d226b1af49f3da59f5265"
-  version = "v1.1.0"
-
-[[projects]]
-  branch = "master"
-  digest = "1:52c5834e2bebac9030c97cc0798ac11c3aa8a39f098aeb419f142533da6cd3cc"
-  name = "github.com/google/gofuzz"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "24818f796faf91cd76ec7bddd72458fbced7a6c1"
-
-[[projects]]
-  digest = "1:3d7c1446fc5c710351b246c0dc6700fae843ca27f5294d0bd9f68bab2a810c44"
-  name = "github.com/googleapis/gnostic"
-  packages = [
-    "OpenAPIv2",
-    "compiler",
-    "extensions",
-  ]
-  pruneopts = "NUT"
-  revision = "ee43cbb60db7bd22502942cccbc39059117352ab"
-  version = "v0.1.0"
-
-[[projects]]
-  digest = "1:406338ad39ab2e37b7f4452906442a3dbf0eb3379dd1f06aafb5c07e769a5fbb"
-  name = "github.com/inconshreveable/mousetrap"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "76626ae9c91c4f2a10f34cad8ce83ea42c93bb75"
-  version = "v1.0"
-
-[[projects]]
-  digest = "1:42c47ace7ccb114261ef7e0d418d274921514ab50a3bf6bdb9e51c3dde8ce13d"
-  name = "github.com/json-iterator/go"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "ca39e5af3ece67bbcda3d0f4f56a8e24d9f2dad4"
-  version = "1.1.3"
-
-[[projects]]
-  branch = "master"
-  digest = "1:ada518b8c338e10e0afa443d84671476d3bd1d926e13713938088e8ddbee1a3e"
-  name = "github.com/mailru/easyjson"
-  packages = [
-    "buffer",
-    "jlexer",
-    "jwriter",
-  ]
-  pruneopts = "NUT"
-  revision = "3fdea8d05856a0c8df22ed4bc71b3219245e4485"
-
-[[projects]]
-  digest = "1:2f42fa12d6911c7b7659738758631bec870b7e9b4c6be5444f963cdcfccc191f"
-  name = "github.com/modern-go/concurrent"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "bacd9c7ef1dd9b15be4a9909b8ac7a4e313eec94"
-  version = "1.0.3"
-
-[[projects]]
-  digest = "1:314a5881fab303a80d6d2e35a77000f2224bb50f09ef63a9aa4c1f9eaef985d8"
-  name = "github.com/modern-go/reflect2"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "1df9eeb2bb81f327b96228865c5687bc2194af3f"
-  version = "1.0.0"
-
-[[projects]]
-  digest = "1:5cf3f025cbee5951a4ee961de067c8a89fc95a5adabead774f82822efabab121"
-  name = "github.com/pkg/errors"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "645ef00459ed84a119197bfb8d8205042c6df63d"
-  version = "v0.8.0"
-
-[[projects]]
-  digest = "1:0f156dbd01b40676bdcbc64e51535c09b50f83c9cca5faef3090f82f18bda3c2"
-  name = "github.com/spf13/cobra"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "a1f051bc3eba734da4772d60e2d677f47cf93ef4"
-  version = "v0.0.2"
-
-[[projects]]
-  digest = "1:15e5c398fbd9d2c439b635a08ac161b13d04f0c2aa587fe256b65dc0c3efe8b7"
-  name = "github.com/spf13/pflag"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "583c0c0531f06d5278b7d917446061adc344b5cd"
-  version = "v1.0.1"
-
-[[projects]]
-  branch = "master"
-  digest = "1:18108bc7e384e395b4805632a637405a3df71fa518e22f9b39b0c08b89a52b96"
-  name = "golang.org/x/net"
-  packages = [
-    "http/httpguts",
-    "http2",
-    "http2/hpack",
-    "idna",
-  ]
-  pruneopts = "NUT"
-  revision = "fe579d43d83210096a79b46dcca0e3721058393a"
-
-[[projects]]
-  digest = "1:e33513a825fcd765e97b5de639a2f7547542d1a8245df0cef18e1fd390b778a9"
-  name = "golang.org/x/text"
-  packages = [
-    "collate",
-    "collate/build",
-    "internal/colltab",
-    "internal/gen",
-    "internal/tag",
-    "internal/triegen",
-    "internal/ucd",
-    "language",
-    "secure/bidirule",
-    "transform",
-    "unicode/bidi",
-    "unicode/cldr",
-    "unicode/norm",
-    "unicode/rangetable",
-    "width",
-  ]
-  pruneopts = "NUT"
-  revision = "f21a4dfb5e38f5895301dc265a8def02365cc3d0"
-  version = "v0.3.0"
-
-[[projects]]
-  digest = "1:2d1fbdc6777e5408cabeb02bf336305e724b925ff4546ded0fa8715a7267922a"
-  name = "gopkg.in/inf.v0"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "d2d2541c53f18d2a059457998ce2876cc8e67cbf"
-  version = "v0.9.1"
-
-[[projects]]
-  digest = "1:7c95b35057a0ff2e19f707173cc1a947fa43a6eb5c4d300d196ece0334046082"
-  name = "gopkg.in/yaml.v2"
-  packages = ["."]
-  pruneopts = "NUT"
-  revision = "5420a8b6744d3b0345ab293f6fcba19c978f1183"
-  version = "v2.2.1"
-
-[[projects]]
-  branch = "master"
-  digest = "1:d895c7c24a0dd1ed2ecd061fd88dfea9e1e84d6f280ed859942a2d1aabee10ec"
-  name = "k8s.io/api"
-  packages = [
-    "admissionregistration/v1alpha1",
-    "admissionregistration/v1beta1",
-    "apps/v1",
-    "apps/v1beta1",
-    "apps/v1beta2",
-    "authentication/v1",
-    "authentication/v1beta1",
-    "authorization/v1",
-    "authorization/v1beta1",
-    "autoscaling/v1",
-    "autoscaling/v2beta1",
-    "batch/v1",
-    "batch/v1beta1",
-    "batch/v2alpha1",
-    "certificates/v1beta1",
-    "core/v1",
-    "events/v1beta1",
-    "extensions/v1beta1",
-    "networking/v1",
-    "policy/v1beta1",
-    "rbac/v1",
-    "rbac/v1alpha1",
-    "rbac/v1beta1",
-    "scheduling/v1alpha1",
-    "settings/v1alpha1",
-    "storage/v1",
-    "storage/v1alpha1",
-    "storage/v1beta1",
-  ]
-  pruneopts = "NUT"
-  revision = "53d615ae3f440f957cb9989d989d597f047262d9"
-
-[[projects]]
-  branch = "master"
-  digest = "1:dff69dd9d9fc681ae077ce5a409aca3c24894d09102ab0395ca7972f6ec01811"
-  name = "k8s.io/apimachinery"
-  packages = [
-    "pkg/api/equality",
-    "pkg/api/meta",
-    "pkg/api/resource",
-    "pkg/api/validation",
-    "pkg/apis/meta/v1",
-    "pkg/apis/meta/v1/unstructured",
-    "pkg/apis/meta/v1/validation",
-    "pkg/apis/meta/v1beta1",
-    "pkg/conversion",
-    "pkg/conversion/queryparams",
-    "pkg/fields",
-    "pkg/labels",
-    "pkg/runtime",
-    "pkg/runtime/schema",
-    "pkg/runtime/serializer",
-    "pkg/runtime/serializer/json",
-    "pkg/runtime/serializer/protobuf",
-    "pkg/runtime/serializer/recognizer",
-    "pkg/runtime/serializer/versioning",
-    "pkg/selection",
-    "pkg/types",
-    "pkg/util/errors",
-    "pkg/util/framer",
-    "pkg/util/intstr",
-    "pkg/util/json",
-    "pkg/util/mergepatch",
-    "pkg/util/net",
-    "pkg/util/runtime",
-    "pkg/util/sets",
-    "pkg/util/strategicpatch",
-    "pkg/util/validation",
-    "pkg/util/validation/field",
-    "pkg/util/wait",
-    "pkg/util/yaml",
-    "pkg/watch",
-    "third_party/forked/golang/json",
-    "third_party/forked/golang/reflect",
-  ]
-  pruneopts = "NUT"
-  revision = "13b73596e4b63e03203e86f6d9c7bcc1b937c62f"
-
-[[projects]]
-  digest = "1:ae9ced9ef7b8eb2794a4f80bc3af9d2bc38ec7d60337367bad9a655c1d641458"
-  name = "k8s.io/client-go"
-  packages = ["kubernetes/scheme"]
-  pruneopts = "NUT"
-  revision = "23781f4d6632d88e869066eaebb743857aa1ef9b"
-  version = "v7.0.0"
-
-[[projects]]
-  branch = "master"
-  digest = "1:f4fb3421360af5c51070bfe0c1c7467f8809fa70e278e129f068f5106b5c8a65"
-  name = "k8s.io/kube-openapi"
-  packages = [
-    "pkg/common",
-    "pkg/util/proto",
-  ]
-  pruneopts = "NUT"
-  revision = "b3f03f55328800731ce03a164b80973014ecd455"
-
-[solve-meta]
-  analyzer-name = "dep"
-  analyzer-version = 1
-  input-imports = [
-    "github.com/evanphx/json-patch",
-    "github.com/ghodss/yaml",
-    "github.com/go-openapi/spec",
-    "github.com/pkg/errors",
-    "github.com/spf13/cobra",
-    "gopkg.in/yaml.v2",
-    "k8s.io/api/core/v1",
-    "k8s.io/apimachinery/pkg/api/validation",
-    "k8s.io/apimachinery/pkg/apis/meta/v1",
-    "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured",
-    "k8s.io/apimachinery/pkg/apis/meta/v1/validation",
-    "k8s.io/apimachinery/pkg/runtime",
-    "k8s.io/apimachinery/pkg/runtime/schema",
-    "k8s.io/apimachinery/pkg/util/mergepatch",
-    "k8s.io/apimachinery/pkg/util/strategicpatch",
-    "k8s.io/apimachinery/pkg/util/validation",
-    "k8s.io/apimachinery/pkg/util/validation/field",
-    "k8s.io/apimachinery/pkg/util/yaml",
-    "k8s.io/client-go/kubernetes/scheme",
-    "k8s.io/kube-openapi/pkg/common",
-  ]
-  solver-name = "gps-cdcl"
-  solver-version = 1

Gopkg.toml

@@ -1,58 +0,0 @@
-# Gopkg.toml example
-#
-# Refer to https://github.com/golang/dep/blob/master/docs/Gopkg.toml.md
-# for detailed Gopkg.toml documentation.
-#
-# required = ["github.com/user/thing/cmd/thing"]
-# ignored = ["github.com/user/project/pkgX", "bitbucket.org/user/project/pkgA/pkgY"]
-#
-# [[constraint]]
-#   name = "github.com/user/project"
-#   version = "1.0.0"
-#
-# [[constraint]]
-#   name = "github.com/user/project2"
-#   branch = "dev"
-#   source = "github.com/myfork/project2"
-#
-# [[override]]
-#  name = "github.com/x/y"
-#  version = "2.4.0"
-
-# prune out unused content from vendor
-[prune]
-  go-tests = true
-  non-go = true
-  unused-packages = true
-
-[[constraint]]
-  name = "github.com/evanphx/json-patch"
-  version = "3.0.0"
-
-[[constraint]]
-  name = "github.com/ghodss/yaml"
-  version = "1.0.0"
-
-[[constraint]]
-  name = "github.com/spf13/cobra"
-  version = "0.0.2"
-
-[[constraint]]
-  branch = "master"
-  name = "k8s.io/api"
-
-[[constraint]]
-  branch = "master"
-  name = "k8s.io/apimachinery"
-
-[[constraint]]
-  name = "k8s.io/client-go"
-  version = "7.0.0"
-
-[[override]]
-  branch = "master"
-  name = "k8s.io/utils"
-
-[[override]]
-  branch = "master"
-  name = "github.com/go-openapi/spec"

Makefile

@@ -0,0 +1,37 @@
+BIN_NAME=kustomize
+
+COVER_FILE=coverage.out
+
+export GO111MODULE=on
+
+all: test build
+
+test: generate-code test-lint test-go
+
+test-go:
+	go test -v ./...
+
+test-lint:
+	golangci-lint run ./...
+
+generate-code:
+	./plugin/generateBuiltins.sh $(GOPATH)
+
+build:
+	go build -o $(BIN_NAME) cmd/kustomize/main.go
+
+install:
+	go install $(PWD)/cmd/kustomize
+
+cover:
+	# The plugin directory eludes coverage, and is therefore omitted
+	go test ./pkg/... ./k8sdeps/... ./internal/... -coverprofile=$(COVER_FILE) && \
+	go tool cover -html=$(COVER_FILE)
+
+
+clean:
+	go clean
+	rm -f $(BIN_NAME)
+	rm -f $(COVER_FILE)
+
+.PHONY: test build install clean generate-code test-go test-lint cover

README.md

@@ -7,7 +7,7 @@ untouched and usable as is.
 `kustomize` targets kubernetes; it understands and can
 patch [kubernetes style] API objects.  It's like
 [`make`], in that what it does is declared in a file,
-and it's like [`sed`], in that it emits editted text.
+and it's like [`sed`], in that it emits edited text.
 
 This tool is sponsored by [sig-cli] ([KEP]), and
 inspired by [DAM].
@@ -16,9 +16,23 @@ inspired by [DAM].
 [![Build Status](https://travis-ci.org/kubernetes-sigs/kustomize.svg?branch=master)](https://travis-ci.org/kubernetes-sigs/kustomize)
 [![Go Report Card](https://goreportcard.com/badge/github.com/kubernetes-sigs/kustomize)](https://goreportcard.com/report/github.com/kubernetes-sigs/kustomize)
 
-**Installation**: Download a binary from the [release
-page], or see these [install] notes. Then try one of
-the tested [examples].
+Download a binary from the [release page], or see
+these [instructions](docs/INSTALL.md).
+
+Browse the [docs](docs) or jump right into the
+tested [examples](examples).
+
+## kubectl integration
+
+Since [v1.14][kubectl announcement] the kustomize build system has been included in kubectl.
+
+| kubectl version | kustomize version |
+|---------|--------|
+| v1.16.0 | [v2.0.3](https://github.com/kubernetes-sigs/kustomize/tree/v2.0.3) |
+| v1.15.x | [v2.0.3](https://github.com/kubernetes-sigs/kustomize/tree/v2.0.3) |
+| v1.14.x | [v2.0.3](https://github.com/kubernetes-sigs/kustomize/tree/v2.0.3) |
+
+For examples and guides for using the kubectl integration please see the [kubectl book] or the [kubernetes documentation].
 
 ## Usage
 
@@ -119,51 +133,10 @@ The YAML can be directly [applied] to a cluster:
 
 ## Community
 
-### Filing bug reports
-
-
-##### A good report specifies
-
- * the output of `kustomize version`,
- * the input (the content of `kustomization.yaml`
-   and any files it refers to),
- * the expected YAML output.
-
-##### A _great_ report is a bug reproduction test
- 
-Kustomize has a simple test harness in the
-[target package] for specifying a kustomization's
-input and the expected output.
-See this [example of a target test].
- 
-The pattern is
- * call `NewKustTestHarness`
- * specify kustomization input data (resources,
-   patches, etc.) as inline strings,
- * call `makeKustTarget().MakeCustomizedResMap()`
- * compare the actual output to expected output
-
-In a bug reproduction test, the expected output string
-initially contains the _wrong_ (unexpected) output,
-thus unambiguously reproducing the bug.
-
-Nearby comments should explain what the output
-_should_ be, and have a TODO pointing to the related
-issue.
-
-The person who fixes the bug then has a clear
-bug reproduction and a test to modify when
-the bug is fixed.
-
-The bug reporter can then see the bug was fixed,
-and has permanent regression coverage to prevent
-its reintroduction.
- 
-### Feature requests
-
-Feature requests are welcome.
+To file bugs please read [this](docs/bugs.md).
 
 Before working on an implementation, please
+
  * Read the [eschewed feature list].
  * File an issue describing
    how the new feature would behave
@@ -192,12 +165,12 @@ 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
-[example of a target test]: https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/target/baseandoverlaysmall_test.go
-[examples]: examples/README.md
-[imageBase]: docs/base.jpg
-[imageOverlay]: docs/overlay.jpg
-[install]: docs/INSTALL.md
+[imageBase]: docs/images/base.jpg
+[imageOverlay]: docs/images/overlay.jpg
 [kind/feature]: https://github.com/kubernetes-sigs/kustomize/labels/kind%2Ffeature
+[kubectl announcement]: https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement
+[kubectl book]: https://kubectl.docs.kubernetes.io/pages/app_customization/introduction.html
+[kubernetes documentation]: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/
 [kubernetes style]: docs/glossary.md#kubernetes-style-object
 [kustomization]: docs/glossary.md#kustomization
 [overlay]: docs/glossary.md#overlay
@@ -206,7 +179,8 @@ is governed by the [Kubernetes Code of Conduct].
 [resource]: docs/glossary.md#resource
 [resources]: docs/glossary.md#resource
 [sig-cli]: https://github.com/kubernetes/community/blob/master/sig-cli/README.md
-[target package]: https://github.com/kubernetes-sigs/kustomize/tree/master/pkg/target
 [variant]: docs/glossary.md#variant
 [variants]: docs/glossary.md#variant
+[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
 [workflows]: docs/workflows.md

bin/pre-commit.sh

@@ -1,49 +0,0 @@
-#!/bin/bash
-set -e
-
-# Make sure, we run in the root of the repo and
-# therefore run the tests on all packages
-base_dir="$( cd "$(dirname "$0")/.." && pwd )"
-cd "$base_dir" || {
-  echo "Cannot cd to '$base_dir'. Aborting." >&2
-  exit 1
-}
-
-rc=0
-
-function runTest {
-  local name=$1
-  local result="SUCCESS"
-  printf "============== begin %s\n" "$name"
-  $name
-  local code=$?
-  rc=$((rc || $code))
-  if [ $code -ne 0 ]; then
-    result="FAILURE"
-  fi
-  printf "============== end %s : %s code=%d\n\n\n" "$name" "$result" $code
-}
-
-function testGoLangCILint {
-  golangci-lint run ./...
-}
-
-function testGoTest {
-  go test -v ./...
-}
-
-function testExamples {
-  mdrip --mode test --label test README.md ./examples
-}
-
-runTest testGoLangCILint
-runTest testGoTest
-runTest testExamples
-
-if [ $rc -eq 0 ]; then
-  echo "SUCCESS!"
-else
-  echo "FAILURE; exit code $rc"
-fi
-
-exit $rc

build/README.md

@@ -1,45 +0,0 @@
-[releases page]: https://github.com/kubernetes-sigs/kustomize/releases
-[`cloud-build-local`]: https://github.com/GoogleCloudPlatform/cloud-build-local
-[Google Cloud Build]: https://cloud.google.com/cloud-build
-
-Scripts and configuration files for publishing a
-`kustomize` release on the [releases page].
-
-### Build a release locally
-
-Install [`cloud-build-local`], then run
-
-```
-cloud-build-local \
-   --config=build/cloudbuild_local.yaml \
-   --dryrun=false --write-workspace=/tmp/w .
-```
-
-to build artifacts under `/tmp/w/dist`.
-
-### Publish a Release
-
-Get on an up-to-date master branch:
-```
-git checkout master
-git fetch upstream
-git rebase upstream/master
-```
-
-Define the version (see [semver principles](https://semver.org)), e.g.:
-```
-version=v1.0.3
-```
-
-Tag the repo:
-```
-git tag -a $version -m "$version release"
-```
-
-Push the tag upstream:
-```
-git push upstream $version
-```
-
-The new tag will trigger a job in [Google Cloud
-Build] to put a new release on the [releases page].

build/build.sh

@@ -1,59 +0,0 @@
-#!/bin/bash
-#
-#  Copyright 2018 The Kubernetes Authors.
-#
-#  Licensed under the Apache License, Version 2.0 (the "License");
-#  you may not use this file except in compliance with the License.
-#  You may obtain a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-#  Unless required by applicable law or agreed to in writing, software
-#  distributed under the License is distributed on an "AS IS" BASIS,
-#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#  See the License for the specific language governing permissions and
-#  limitations under the License.
-
-set -e
-set -x
-
-# Google Container Builder automatically checks out all the code under the /workspace directory,
-# but we actually want it to under the correct expected package in the GOPATH (/go)
-# - Create the directory to host the code that matches the expected GOPATH package locations
-# - Use /go as the default GOPATH because this is what the image uses
-# - Link our current directory (containing the source code) to the package location in the GOPATH
-
-OWNER="sigs.k8s.io"
-REPO="kustomize"
-
-GO_PKG_OWNER=$GOPATH/src/$OWNER
-GO_PKG_PATH=$GO_PKG_OWNER/$REPO
-
-mkdir -p $GO_PKG_OWNER
-ln -sf $(pwd) $GO_PKG_PATH
-
-# When invoked in container builder, this script runs under /workspace which is
-# not under $GOPATH, so we need to `cd` to repo under GOPATH for it to build
-cd $GO_PKG_PATH
-
-
-# NOTE: if snapshot is enabled, release is not published to GitHub and the build
-# is available under workspace/dist directory.
-SNAPSHOT=""
-
-# parse commandline args copied from the link below
-# https://stackoverflow.com/questions/192249/how-do-i-parse-command-line-arguments-in-bash?utm_medium=organic&utm_source=google_rich_qa&utm_campaign=google_rich_qa
-
-while [[ $# -gt 0 ]]
-do
-key="$1"
-
-case $key in
-    --snapshot)
-    SNAPSHOT="--snapshot"
-    shift # past argument
-    ;;
-esac
-done
-
-/goreleaser release --config=build/goreleaser.yaml --rm-dist --skip-validate ${SNAPSHOT}

build/cloudbuild.yaml

@@ -1,25 +0,0 @@
-#  Copyright 2018 The Kubernetes Authors.
-#
-#  Licensed under the Apache License, Version 2.0 (the "License");
-#  you may not use this file except in compliance with the License.
-#  You may obtain a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-#  Unless required by applicable law or agreed to in writing, software
-#  distributed under the License is distributed on an "AS IS" BASIS,
-#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#  See the License for the specific language governing permissions and
-#  limitations under the License.
-
-# TODO(droot): add instructions for running in production.
-steps:
-- name: "gcr.io/cloud-builders/git"
-  args: [fetch, --tags, --depth=100]
-- name: "gcr.io/kustomize-199618/golang_with_goreleaser:1.10-stretch"
-  args: ["bash", "build/build.sh"]
-  secretEnv: ['GITHUB_TOKEN']
-secrets:
-- kmsKeyName: projects/kustomize-199618/locations/global/keyRings/github-tokens/cryptoKeys/gh-release-token
-  secretEnv:
-   GITHUB_TOKEN: CiQAyrREbPgXJOeT7M3t+WlxkhXwlMPudixBeiyWTjmLOMLqdK4SUQA0W+xUmDJKAhyfHCcwqSEzUn9OwKC7XAYcmwe0CCKTCbPbDgmioDK24q3LVapndXNvnnHvCjhOJNEr1o+P1DCF+LlzYV2YL8lP09rrKrslPg==

build/cloudbuild_local.yaml

@@ -1,30 +0,0 @@
-#  Copyright 2018 The Kubernetes Authors.
-#
-#  Licensed under the Apache License, Version 2.0 (the "License");
-#  you may not use this file except in compliance with the License.
-#  You may obtain a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-#  Unless required by applicable law or agreed to in writing, software
-#  distributed under the License is distributed on an "AS IS" BASIS,
-#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#  See the License for the specific language governing permissions and
-#  limitations under the License.
-
-# Instructions to run locally:
-# Download google container builder: https://github.com/kubernetes-sigs/container-builder-local
-# Set you GOOS and GOARCH vars to match your system
-# Set OUTPUT to the location to write the directory containing the tar.gz
-# $ container-builder-local --config=build/cloudbuild_local.yaml --dryrun=false \
-#   --substitutions=_GOOS=$GOOS,_GOARCH=$GOARCH --write-workspace=$OUTPUT .
-# Release tar will be in $OUTPUT
-
-steps:
-- name: "gcr.io/kustomize-199618/golang_with_goreleaser:1.10-stretch"
-  args: ["bash", "build/build.sh", "--snapshot"]
-  secretEnv: ['GITHUB_TOKEN']
-secrets:
-- kmsKeyName: projects/kustomize-199618/locations/global/keyRings/github-tokens/cryptoKeys/gh-release-token
-  secretEnv:
-   GITHUB_TOKEN: CiQAyrREbPgXJOeT7M3t+WlxkhXwlMPudixBeiyWTjmLOMLqdK4SUQA0W+xUmDJKAhyfHCcwqSEzUn9OwKC7XAYcmwe0CCKTCbPbDgmioDK24q3LVapndXNvnnHvCjhOJNEr1o+P1DCF+LlzYV2YL8lP09rrKrslPg==

build/goreleaser.yaml

@@ -1,33 +0,0 @@
-# This is an example goreleaser.yaml file with some sane defaults.
-# Make sure to check the documentation at http://goreleaser.com
-project_name: kustomize
-builds:
-- main: ./kustomize.go
-  binary: kustomize
-  ldflags: -s -X sigs.k8s.io/kustomize/pkg/commands/misc.kustomizeVersion={{.Version}} -X sigs.k8s.io/kustomize/pkg/commands/misc.gitCommit={{.Commit}} -X sigs.k8s.io/kustomize/pkg/commands/misc.buildDate={{.Date}}
-  goos:
-  - darwin
-  - linux
-  - windows
-  goarch:
-   - amd64
-  env:
-  - CGO_ENABLED=0
-checksum:
-  name_template: 'checksums.txt'
-archive:
-  format: binary
-snapshot:
-  name_template: "master"
-changelog:
-  sort: asc
-  filters:
-    exclude:
-    - '^docs:'
-    - '^test:'
-    - Merge pull request
-    - Merge branch
-release:
-  github:
-    owner: kubernetes-sigs
-    name: kustomize

docs/FAQ.md

@@ -0,0 +1,58 @@
+# FAQ
+
+## security: file 'foo' is not in or below 'bar'
+
+v2.0 added a security check that prevents
+kustomizations from reading files outside their own
+directory root.
+
+This was meant to help protect the person inclined to
+download kustomization directories from the web and use
+them without inspection to control their production
+cluster
+(see [#693](https://github.com/kubernetes-sigs/kustomize/issues/693),
+[#700](https://github.com/kubernetes-sigs/kustomize/pull/700),
+[#995](https://github.com/kubernetes-sigs/kustomize/pull/995) and
+[#998](https://github.com/kubernetes-sigs/kustomize/pull/998))
+
+Resources (including configmap and secret generators)
+can _still be shared_ via the recommended best practice
+of placing them in a directory with their own
+kustomization file, and refering to this directory as a
+[`base`](glossary.md#base) from any kustomization that
+wants to use it.  This encourages modularity and
+relocatability.
+
+To disable this, use v3, and the `load_restrictor` flag:
+
+```
+kustomize build --load_restrictor none $target
+```
+
+## Some field is not transformed by kustomize
+
+Example: [#1319](https://github.com/kubernetes-sigs/kustomize/issues/1319), [#1322](https://github.com/kubernetes-sigs/kustomize/issues/1322), [#1347](https://github.com/kubernetes-sigs/kustomize/issues/1347) and etc.
+
+The fields transformed by kustomize is configured explicitly in [defaultconfig](https://github.com/kubernetes-sigs/kustomize/tree/master/pkg/transformers/config/defaultconfig). The configuration itself can be customized by including `configurations` in `kustomization.yaml`, e.g.
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+configurations:
+- kustomizeconfig.yaml
+```
+
+The configuration directive allows customization of the following transformers:
+
+```yaml
+commonAnnotations: []
+commonLabels: []
+nameprefix: []
+namespace: []
+varreference: []
+namereference: []
+images: []
+replicas: []
+```
+
+To persist the changes to default configuration, submit a PR like [#1338](https://github.com/kubernetes-sigs/kustomize/pull/1338), [#1348](https://github.com/kubernetes-sigs/kustomize/pull/1348) and etc.

docs/INSTALL.md

@@ -1,18 +1,14 @@
 [release page]: https://github.com/kubernetes-sigs/kustomize/releases
 [Go]: https://golang.org
 
-## Installation
+# Installation
 
-On macOS, you can install kustomize with Homebrew package
-manager:
+Binaries at various versions for linux, macOs and Windows
+are available on the [release page].
 
-    brew install kustomize
+Or...
 
-For all operating systems, download a binary from the
-[release page].
-
-Or try this to grab the latest official release
-using the command line:
+## Quickly curl the latest
 
 ```
 opsys=linux  # or darwin, or windows
@@ -25,9 +21,32 @@ mv kustomize_*_${opsys}_amd64 kustomize
 chmod u+x kustomize
 ```
 
-To install from head with [Go] v1.10.1 or higher:
+## Get and install source for a particular release
 
-<!-- @installkustomize @test -->
+For example
 ```
-go get sigs.k8s.io/kustomize
+# Omit the @v3.2.1 to get the default for major version 3
+GO111MODULE=on go get sigs.k8s.io/kustomize/kustomize/v3@v3.2.1
 ```
+
+Use of `GO111MODULE=on` shouldn't be necessary
+with [Go v1.13](https://golang.org/doc/go1.13#modules).
+
+### Other methods
+
+#### macOS
+
+```
+brew install kustomize
+```
+
+#### windows
+
+```
+choco install kustomize
+```
+
+For support on the chocolatey package
+and prior releases, see:
+- [Choco Package](https://chocolatey.org/packages/kustomize)
+- [Package Source](https://github.com/kenmaglio/choco-kustomize)

docs/README.md

@@ -1,28 +1,61 @@
-# Kustomize docs
- 
- * [installation instructions](INSTALL.md)
- 
- * [kustomization.yaml](kustomization.yaml) - Example of a
-   [kustomization](glossary.md#kustomization)
-   with explanations of each field.
+English | [简体中文](zh/README.md)
 
- * [versioning policy](versioningPolicy.md) - How the code and the kustomization
-   file evolve in time.
-   
- * [version 2.0.0](version2.0.0.md) - Release note of Kustomize 2.0.0.
+# Documentation
 
- * [workflow](workflows.md) - Some steps one might take in using
-   bespoke and off-the-shelf configurations.
-  
- * [glossary](glossary.md) - An attempt to disambiguiate terminology.
-   
- * [eschewed features](eschewedFeatures.md) - Why certain features are (currently)
-   not supported in Kustomize.
+ * [Installation](INSTALL.md)
 
- * [contributing guidelines](../CONTRIBUTING.md) - Please read before sending a PR.
- 
- * [code of conduct](../code-of-conduct.md)
- 
- 
- 
- 
+ * [Examples](../examples) - detailed walkthroughs of various
+    workflows and concepts.
+
+ * [Glossary](glossary.md) - the word of the day is [_root_](glossary.md#kustomization-root).
+
+ * [Kustomize Fields](fields.md) - explanations of the fields
+   in a  [kustomization](glossary.md#kustomization) file.
+
+ * [Plugins](plugins) - extending kustomize with
+   custom generators and transformers.
+
+ * [Workflows](workflows.md) - steps one might take in
+   using bespoke and off-the-shelf configurations.
+
+ * [FAQ](FAQ.md)
+
+
+## Release notes
+
+ * 3.2.1 - Patch release of kustomize in its own module.  No change in function
+   from v3.2.0.
+
+ * [3.2.0](v3.2.0.md) - TODO(jingfang)
+
+ * [3.1.1](v3.1.0.md) - TODO(jingfang)
+
+ * [3.1](v3.1.0.md) - Late July 2019. Extended patches and improved resource matching.
+
+ * [3.0](v3.0.0.md) - Late June 2019. Plugin developer release.
+
+ * [2.1](v2.1.0.md) - 18 June 2019.  Plugins, ordered resources, etc.
+
+ * [2.0](v2.0.0.md) - Mar 2019.
+   kustomize [v2.0.3] is available in [kubectl v1.14][kubectl].
+
+ * [1.0](v1.0.1.md) - May 2018.  Initial release after development
+   in the [kubectl repository].
+
+
+## Policies
+
+ * [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)
+
+[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.0.3
+[kubectl]: https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement
+[kubectl repository]: https://github.com/kubernetes/kubectl

docs/authoriing.md

@@ -0,0 +1,37 @@
+# kustomization authoring
+
+kustomize provides sub-commands for managing the contents of a kustomization file from the command line.
+
+## kustomize create
+
+The `kustomize create` command will create a new kustomization in the current directory.
+
+When run without any flags the command will create an empty `kustomization.yaml` file that can then be updated manually or with the `kustomize edit` sub-commands.
+
+```
+kustomize create --namespace=myapp --resources=deployment.yaml,service.yaml --label=app=myapp
+```
+
+### Detecting resources
+
+> NOTE: Resource detection will not follow symlinks.
+
+Flags:
+      --annotation string   Add one or more common annotations.
+      --autodetect          Search for kubernetes resources in the current directory to be added to the kustomization file.
+  -h, --help                help for create
+      --label string        Add one or more common labels.
+      --nameprefix string   Sets the value of the namePrefix field in the kustomization file.
+      --namespace string    Set the value of the namespace field in the customization file.
+      --namesuffix string   Sets the value of the nameSuffix field in the kustomization file.
+      --recursive           Enable recursive directory searching for resource auto-detection.
+      --resources string    Name of a file containing a file to add to the kustomization file.
+
+## kustomize edit
+
+With an existing kustomization file the `kustomize edit` command 
+
+* add
+* set
+* remove
+* fix

docs/bugs.md

@@ -0,0 +1,49 @@
+# Filing bugs
+
+[target package]: https://github.com/kubernetes-sigs/kustomize/tree/master/pkg/target
+[example of a target test]: https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/target/baseandoverlaysmall_test.go
+
+File issues as desired, but
+if you've found a problem with how
+`kustomize build` works, consider the
+following to improve response time.
+
+## A good report specifies
+
+ * the output of `kustomize version`,
+ * the input (the content of `kustomization.yaml`
+   and any files it refers to),
+ * the expected YAML output.
+
+## A great report is a bug reproduction test
+
+kustomize has a simple test harness in the
+[target package] for specifying a kustomization's
+input and the expected output.
+
+See this [example of a target test], and contribution
+[#971](https://github.com/kubernetes-sigs/kustomize/pull/971),
+which does exactly the right thing.
+
+The pattern is
+ * call `NewKustTestHarness`
+ * specify kustomization input data (resources,
+   patches, etc.) as inline strings,
+ * call `makeKustTarget().MakeCustomizedResMap()`
+ * compare the actual output to expected output
+
+In a bug reproduction test, the expected output
+string initially contains the _wrong_ (unexpected)
+output, thus unambiguously reproducing the bug.
+
+Nearby comments should explain what the output
+should be, and have a TODO pointing to the related
+issue.
+
+The person who fixes the bug then has a clear bug
+reproduction and a test to modify when the bug is
+fixed.
+
+The bug reporter can then see the bug was fixed,
+and has permanent regression coverage to prevent
+its reintroduction.

docs/execPluginIn30sec.md

@@ -0,0 +1 @@
+plugins/execPluginGuidedExample.md

docs/fields.md

@@ -0,0 +1,316 @@
+# Kustomization File Fields
+
+[field-name-namespace]: plugins/builtins.md#field-name-namespace
+[field-name-images]: plugins/builtins.md#field-name-images
+[field-name-namePrefix]: plugins/builtins.md#field-name-prefix
+[field-name-nameSuffix]: plugins/builtins.md#field-name-prefix
+[field-name-patches]: plugins/builtins.md#field-name-patches
+[field-name-patchesStrategicMerge]: plugins/builtins.md#field-name-patchesStrategicMerge
+[field-name-patchesJson6902]: plugins/builtins.md#field-name-patchesJson6902
+[field-name-replicas]: plugins/builtins.md#field-name-replicas
+[field-name-secretGenerator]: plugins/builtins.md#field-name-secretGenerator
+[field-name-commonLabels]: plugins/builtins.md#field-name-commonLabels
+[field-name-commonAnnotations]: plugins/builtins.md#field-name-commonAnnotations
+[field-name-configMapGenerator]: plugins/builtins.md#field-name-configMapGenerator
+
+
+An explanation of the fields in a [kustomization.yaml](glossary.md#kustomization) file.
+
+
+## Resources
+
+What existing things should be customized.
+
+| Field  | Type  | Explanation |
+|---|---|---|
+|[resources](#resources) |  list  |Files containing k8s API objects, or directories containing other kustomizations. |
+|[CRDs](#crds)| list |Custom resource definition files, to allow specification of the custom resources in the resources list. |
+
+## Generators
+
+What things should be created (and optionally subsequently customized)?
+
+| Field  | Type  | Explanation |
+|---|---|---|
+|[configMapGenerator](#configmapgenerator)| list  |Each entry in this list results in the creation of one ConfigMap resource (it's a generator of n maps).|
+|[secretGenerator](#secretgenerator)| list  |Each entry in this list results in the creation of one Secret resource (it's a generator of n secrets)|
+|[generatorOptions](#generatoroptions)|string|generatorOptions modify behavior of all ConfigMap and Secret generators|
+|[generators](#generators)|list|[plugin](plugins) configuration files|
+
+
+## Transformers
+
+What transformations (customizations) should be applied?
+
+| Field  | Type  | Explanation |
+|---|---|---|
+| [commonLabels](#commonlabels) | string | Adds labels and some corresponding label selectors to all resources. |
+| [commonAnnotations](#commonannotations) | string | Adds annotions (non-identifying metadata) to add all resources. |
+| [images](#images) | list | Images modify the name, tags and/or digest for images without creating patches. |
+| [inventory](#inventory) | struct | Specify an object who's annotations will contain a build result summary. |
+| [namespace](#namespace)   | string | Adds namespace to all resources |
+| [namePrefix](#nameprefix) | string | Prepends value to the names of all resources |
+| [nameSuffix](#namesuffix) | string | The value is appended to the names of all resources. |
+| [replicas](#replicas) | list | Replicas modifies the number of replicas of a resource. |
+| [patches](#patches) | list | Each entry should resolve to a patch that can be applied to multiple targets. |
+|[patchesStrategicMerge](#patchesstrategicmerge)| list |Each entry in this list should resolve to a partial or complete resource definition file.|
+|[patchesJson6902](#patchesjson6902)| list  |Each entry in this list should resolve to a kubernetes object and a JSON patch that will be applied to the object.|
+|[transformers](#transformers)|list|[plugin](plugins) configuration files|
+
+
+## Meta
+
+[k8s metadata]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
+
+|Field|Type|Explanation|
+|---|---|---|
+| [vars](#vars)     | string | Vars capture text from one resource's field and insert that text elsewhere. |
+| [apiVersion](#apiversion)     | string | [k8s metadata] field. |
+| [kind](#kind)     | string | [k8s metadata] field. |
+
+----
+
+### apiVersion
+
+If missing, this field's value defaults to
+```
+apiVersion: kustomize.config.k8s.io/v1beta1
+```
+
+### bases
+
+_The `bases` field was deprecated in v2.1.0._
+
+Move entries into the [resources](#resources)
+field.  This allows bases - which are still a
+[central concept](glossary.md#base) - to be
+ordered relative to other input resources.
+
+### commonLabels
+See [field-name-commonLabels].
+
+### commonAnnotations
+See [field-name-commonAnnotations].
+
+### configMapGenerator
+See [field-name-configMapGenerator].
+
+### crds
+
+Each entry in this list should be a relative path to
+a file for custom resource definition (CRD).
+
+The presence of this field is to allow kustomize be
+aware of CRDs and apply proper
+transformation for any objects in those types.
+
+Typical use case: A CRD object refers to a
+ConfigMap object.  In a kustomization, the ConfigMap
+object name may change by adding namePrefix,
+nameSuffix, or hashing. The name reference for this
+ConfigMap object in CRD object need to be updated
+with namePrefix, nameSuffix, or hashing in the
+same way.
+
+The annotations can be put into openAPI definitions are:
+ -  "x-kubernetes-annotation": ""
+ -  "x-kubernetes-label-selector": ""
+ -  "x-kubernetes-identity": ""
+ -  "x-kubernetes-object-ref-api-version": "v1",
+ -  "x-kubernetes-object-ref-kind": "Secret",
+ -  "x-kubernetes-object-ref-name-key": "name",
+
+```
+crds:
+- crds/typeA.yaml
+- crds/typeB.yaml
+```
+
+
+### generatorOptions
+
+Modifies behavior of all [ConfigMap](#configmapgenerator)
+and [Secret](#secretgenerator) generators.
+
+```
+generatorOptions:
+  # labels to add to all generated resources
+  labels:
+    kustomize.generated.resources: somevalue
+  # annotations to add to all generated resources
+  annotations:
+    kustomize.generated.resource: somevalue
+  # disableNameSuffixHash is true disables the default behavior of adding a
+  # suffix to the names of generated resources that is a hash of
+  # the resource contents.
+  disableNameSuffixHash: true
+```
+
+### generators
+
+A list of generator [plugin](plugins) configuration files.
+
+```
+generators:
+- mySecretGeneratorPlugin.yaml
+- myAppGeneratorPlugin.yaml
+```
+
+### images
+
+See [field-name-images].
+
+### inventory
+
+See [inventory object](inventory_object.md).
+
+### kind
+
+If missing, this field's value defaults to
+
+```
+kind: Kustomization
+```
+
+### namespace
+
+See [field-name-namespace].
+
+### namePrefix
+
+See [field-name-namePrefix].
+
+### nameSuffix
+
+See [field-name-nameSuffix].
+
+### patches
+
+See [field-name-patches].
+
+### patchesStrategicMerge
+
+See [field-name-patchesStrategicMerge].
+
+### patchesJson6902
+
+See [field-name-patchesJson6902].
+
+### replicas
+
+See [field-name-replicas].
+
+### resources
+
+Each entry in this list must be a path to a
+_file_, or a path (or URL) refering to another
+kustomization _directory_, e.g.
+
+```
+resource:
+- myNamespace.yaml
+- sub-dir/some-deployment.yaml
+- ../../commonbase
+- github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6
+- deployment.yaml
+- github.com/kubernets-sigs/kustomize//examples/helloWorld?ref=test-branch
+```
+
+Resources will be read and processed in
+depth-first order.
+
+Files should contain k8s resources in YAML form.
+A file may contain multiple resources separated by
+the document marker `---`.  File paths should be
+specified _relative_ to the directory holding the
+kustomization file containing the `resources`
+field.
+
+[hashicorp URL]: https://github.com/hashicorp/go-getter#url-format
+
+Directory specification can be relative, absolute,
+or part of a URL.  URL specifications should
+follow the [hashicorp URL] format.  The directory
+must contain a `kustomization.yaml` file.
+
+
+### secretGenerator
+
+See [field-name-secretGenerator].
+
+### vars
+
+Vars are used to capture text from one resource's field
+and insert that text elsewhere - a reflection feature.
+
+For example, suppose one specifies the name of a k8s Service
+object in a container's command line, and the name of a
+k8s Secret object in a container's environment variable,
+so that the following would work:
+
+```
+containers:
+  - image: myimage
+    command: ["start", "--host", "$(MY_SERVICE_NAME)"]
+    env:
+    - name: SECRET_TOKEN
+      value: $(SOME_SECRET_NAME)
+```
+
+To do so, add an entry to `vars:` as follows:
+
+```
+vars:
+- name: SOME_SECRET_NAME
+  objref:
+    kind: Secret
+    name: my-secret
+    apiVersion: v1
+- name: MY_SERVICE_NAME
+  objref:
+    kind: Service
+    name: my-service
+    apiVersion: v1
+  fieldref:
+    fieldpath: metadata.name
+- name: ANOTHER_DEPLOYMENTS_POD_RESTART_POLICY
+  objref:
+    kind: Deployment
+    name: my-deployment
+    apiVersion: apps/v1
+  fieldref:
+    fieldpath: spec.template.spec.restartPolicy
+```
+
+A var is a tuple of variable name, object
+reference and field reference within that object.
+That's where the text is found.
+
+The field reference is optional; it defaults to
+`metadata.name`, a normal default, since kustomize
+is used to generate or modify the names of
+resources.
+
+At time of writing, only string type fields are
+supported.  No ints, bools, arrays etc.  It's not
+possible to, say, extract the name of the image in
+container number 2 of some pod template.
+
+A variable reference, i.e. the string '$(FOO)',
+can only be placed in particular fields of
+particular objects as specified by kustomize's
+configuration data.
+
+The default config data for vars is at
+https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/transformers/config/defaultconfig/varreference.go
+Long story short, the default targets are all
+container command args and env value fields.
+
+Vars should _not_ be used for inserting names in
+places where kustomize is already handling that
+job.  E.g., a Deployment may reference a ConfigMap
+by name, and if kustomize changes the name of a
+ConfigMap, it knows to change the name reference
+in the Deployment.
+
+

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
@@ -31,9 +32,11 @@
 [rebase]: https://git-scm.com/docs/git-rebase
 [resource]: #resource
 [resources]: #resource
+[root]: #kustomization-root
 [rpm]: https://en.wikipedia.org/wiki/Rpm_(software)
-[strategic-merge]: https://github.com/kubernetes/community/blob/master/contributors/devel/strategic-merge-patch.md
+[strategic-merge]: https://git.k8s.io/community/contributors/devel/sig-api-machinery/strategic-merge-patch.md
 [target]: #target
+[transformer]: #transformer
 [variant]: #variant
 [variants]: #variant
 [workflow]: workflows.md
@@ -74,10 +77,11 @@ management in k8s.
 
 ## base
 
-A _base_ is a [target] that some [overlay] modifies.
+A _base_ is a [kustomization] referred to
+by some other [kustomization].
 
-Any target, including an [overlay], can be a base to
-another target.
+Any kustomization, including an [overlay], can be a base to
+another kustomization.
 
 A base has no knowledge of the overlays that refer to it.
 
@@ -134,6 +138,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
@@ -142,31 +152,103 @@ test or deploy) when that truth changes.
 
 ## kustomization
 
-A _kustomization_ is a file called `kustomization.yaml` that
-describes a configuration consumable by [kustomize].
+The term _kustomization_ refers to a
+`kustomization.yaml` file, or more generally to a
+directory (the [root]) containing the
+`kustomization.yaml` file and all the relative file
+paths that it immediately references (all the local
+data that doesn't require a URL specification).
+
+I.e. if someone gives you a _kustomization_ for use
+with [kustomize], it could be in the form of
+
+ * one file called `kustomization.yaml`,
+ * a tarball (containing that YAML file plus what it references),
+ * a git archive (ditto),
+ * a URL to a git repo (ditto), etc.
+
+A kustomization file contains [fields](fields.md)
+falling into four categories:
+
+ * _resources_ - what existing [resources] are to be customized.
+   Example fields: _resources_, _crds_.
+
+ * _generators_ - what _new_ resources should be created.
+   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
+   general _transformers_ (v2.1) field.
+
+ * _meta_ - fields which may influence all or some of
+   the above.  Example fields: _vars_, _namespace_,
+   _apiVersion_, _kind_, etc.
 
 
-Here's an [example](kustomization.yaml).
+## kustomization root
 
-A kustomization contains fields falling into these categories:
+The directory that immediately contains a
+`kustomization.yaml` file.
 
- * _Customization operators_ for modifying operands, e.g.
-   _namePrefix_, _nameSuffix_, _commonLabels_, _patches_, etc.
+When a kustomization file is processed, it may or may
+not be able to access files outside its root.
 
- * _Customization operands_:
-   * [resources] - completely specified k8s API objects,
-      e.g. `deployment.yaml`, `configmap.yaml`, etc.
-   * [bases] - paths or github URLs specifying directories
-     containing a [kustomization].  These bases may
-     be subjected to more customization, or merely
-     included in the output.
-   * [CRD]s - custom resource definition files, to allow use
-     of _custom_ resources in the _resources_ list.
-     Not an actual operand - but allows the use of new operands.
+Data files like resource YAML files, or text files
+containing _name=value_ pairs intended for a ConfigMap
+or Secret, or files representing a patch to be used in
+a patch transformation, must live _within or below_ the
+root, and as such are specified via _relative
+paths_ exclusively.
 
- * Generators, for creating more resources
-   (configmaps and secrets) which can then be
-   customized.
+A special flag (in v2.1), `--load_restrictions none`,
+is provided to relax this security feature, to, say,
+allow a patch file to be shared by more than one
+kustomization.
+
+Other kustomizations (other directories containing a
+`kustomization.yaml` file) may be referred to by URL, by
+absolute path, or by relative path.
+
+If kustomization __A__ depends on kustomization __B__, then
+
+ * __B__ may not _contain_ __A__.
+ * __B__ may not _depend on_ __A__, even transitively.
+
+__A__ may contain __B__, but in this case it might be
+simplest to have __A__ directly depend on __B__'s
+resources and eliminate __B__'s kustomization.yaml file
+(i.e. absorb __B__ into __A__).
+
+Conventionally, __B__ is in a directory that's sibling
+to __A__, or __B__ is off in a completely independent
+git repository, referencable from any kustomization.
+
+
+A common layout is
+
+> ```
+> ├── base
+> │   ├── deployment.yaml
+> │   ├── kustomization.yaml
+> │   └── service.yaml
+> └── overlays
+>     ├── dev
+>     │   ├── kustomization.yaml
+>     │   └── patch.yaml
+>     ├── prod
+>     │   ├── kustomization.yaml
+>     │   └── patch.yaml
+>     └── staging
+>         ├── kustomization.yaml
+>         └── patch.yaml
+> ```
+
+The three roots `dev`, `prod` and `staging`
+(presumably) all refer to the `base` root.  One would
+have to inspect the `kustomization.yaml` files to be
+sure.
 
 ## kubernetes
 
@@ -189,14 +271,14 @@ more than one version).
 
 ## kustomize
 
-_kustomize_ is a command line tool supporting template-free
-customization of declarative configuration targetted to
-k8s-style objects.
+_kustomize_ is a command line tool supporting
+template-free, structured customization of declarative
+configuration targetted to k8s-style objects.
 
-_Targetted to k8s means_ that kustomize may need some
-limited understanding of API resources, k8s concepts
-like names, labels, namespaces, etc. and the semantics
-of resource patching.
+_Targetted to k8s means_ that kustomize has some
+understanding of API resources, k8s concepts like
+names, labels, namespaces, etc. and the semantics of
+resource patching.
 
 kustomize is an implementation of [DAM].
 
@@ -226,14 +308,13 @@ own [overlays] to do further customization.
 
 ## overlay
 
-An _overlay_ is a [target] that modifies (and thus
-depends on) another target.
+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.
 
@@ -245,7 +326,7 @@ _production_ environment variants.
 These variants use the same overall resources, and vary
 in relatively simple ways, e.g. the number of replicas
 in a deployment, the CPU to a particular pod, the data
-source used in a configmap, etc.
+source used in a ConfigMap, etc.
 
 One configures a cluster like this:
 
@@ -260,6 +341,7 @@ One configures a cluster like this:
 Usage of the base is implicit - the overlay's
 kustomization points to the base.
 
+See also [root].
 
 ## package
 
@@ -290,14 +372,13 @@ 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 
-directives include _replace_ (the default), _merge_
-(avoid replacing a list), _delete_ and a few more
-(see [these notes][strategic-merge]).
+To change this
+default behavior, add a _directive_.  Recognized
+directives in YAML patches are _replace_ (the default)
+and _delete_ (see [these notes][strategic-merge]).
 
 Note that for custom resources, SMPs are treated as
 [json merge patches][JSONMergePatch].
@@ -318,6 +399,14 @@ A _patchJson6902_ can do almost everything a
 _patchStrategicMerge_ can do, but with a briefer
 syntax.  See this [example][patchExampleJson6902].
 
+## plugin
+
+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).
+
 ## resource
 
 A _resource_ in the context of a REST-ful API is the
@@ -325,15 +414,19 @@ target object of an HTTP operation like _GET_, _PUT_ or
 _POST_.  k8s offers a REST-ful API surface to interact
 with clients.
 
-A _resource_, in the context of kustomization file,
-is a path to a [YAML] or [JSON] file describing
-a k8s API object, like a Deployment or a
-ConfigmMap.
+A _resource_, in the context of a kustomization, is a
+[root] relative path to a [YAML] or [JSON] file
+describing a k8s API object, like a Deployment or a
+ConfigMap, or it's a path to a kustomization, or a URL
+that resolves to a kustomization.
 
 More generally, a resource can be any correct YAML file
 that [defines an object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields)
 with a _kind_ and a _metadata/name_ field.
 
+## root
+
+See [kustomization root][root].
 
 ## sub-target / sub-application / sub-package
 
@@ -348,14 +441,19 @@ The _target_ is the argument to `kustomize build`, e.g.:
 >  kustomize build $target
 > ```
 
-`$target` must be a path or a url to a directory that
-immediately contains a [kustomization].
+`$target` must be a path or a url to a [kustomization].
 
 The target contains, or refers to, all the information
 needed to create customized resources to send to the
 [apply] operation.
 
-A target is a [base] or an [overlay].
+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
 

docs/howtowindows.md

@@ -0,0 +1,54 @@
+# How To Windows
+
+This is the PowerShell script to run all go tests for Kustomize on a windows based platform which mimics /build/pre-commit.sh
+
+## Pre-Reqs:
+  - (obviously) PowerShell installed
+    - PowerShell Core is supported
+  - go installed
+  - golangci-lint installed
+  - mdrip installed
+
+This script should output to the current console and return an exit code if all tests are successful(0) or any failed(1).
+
+### If you are tryin to run these tests locally you can follow these instructions.
+
+Assume: 
+  - Running a stock Windows 10 system
+  - Local Admin rights.
+  - You can open [PowerShell as administrator](http://lmgtfy.com/?iie=1&q=How+to+open+powershell+as+administrator)
+  - You should be knowledgeable enough to pull source for packages into your GO ```src``` directory
+    -  Yes, this means you also need to know a bit about **git** usually
+
+
+#### Step 1 - Install Go
+  - [Install Go](https://golang.org/dl/) - please use the msi
+    - If you use chocolatey - it's using the zip not msi and assumptions on where go is located are made for you.
+#### Step 2 - Install Go Packages
+  - Open new PowerShell Administrative window
+    - Install golangci-lint
+      - ```go get -u github.com/golangci/golangci-lint/cmd/golangci-lint```
+    - Install mdrip
+      - ```go get github.com/monopole/mdrip```
+
+You should now be able to issue these commands and see comparable responses
+
+```
+C:\...> golangci-lint --help
+Smart, fast linters runner. Run it in cloud for every GitHub pull request on https://golangci.com
+...
+
+C:\...> mdrip --help
+Usage:  C:\_go\bin\mdrip.exe {fileName}...
+...
+```
+
+#### Step 3 - Get Source and Test
+- In your GoRoot src
+  - ```Example: C:\_go\src```
+- Navigate to the Kustomize `travis` directory
+  - ```Example: C:\_go\src\sigs.k8s.io\kustomize\travis```
+- Now Execute:
+  - ```.\Invoke-PreCommit.ps1```
+
+This should run all pre-commit tests thus defined in the script.

docs/inventory_object.md

@@ -0,0 +1,189 @@
+# inventory directive in kustomization.yaml
+
+New in v2.1.0, a kustomization file may have an `inventory` field:
+```yaml
+inventory:
+  type: ConfigMap
+  configMap:
+    name: prune-cm-name
+    namespace: some-namespace
+```
+
+### 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
+[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`.
+
+
+### Implementation
+
+The _inventory_ ConfigMap contains two special annotations:
+
+- kustomize.config.k8s.io/Inventory
+  The value of this annotation is the JSON blob
+  for an Inventory object. The Inventory is a
+  struct that contains following information
+  - all objects within this kustomization target
+  - all objects that reference within this kustomization target
+
+  Here is an example of an Inventory object
+  ```json
+  {
+    "current":
+      {
+        "apps_v1_Deployment|default|mysql":null,
+        "~G_v1_Secret|default|pass-dfg7h97cf6":
+          [
+            {
+              "group":"apps",
+              "version":"v1",
+              "kind":"Deployment",
+              "name":"mysql",
+              "namespace":"default"
+            }
+          ],
+        "~G_v1_Service|default|mysql":null
+      }
+    }
+  ```
+
+- kustomize.config.k8s.io/InventoryHash
+  The value of this annotation is a hash that is
+  computed from the list of items in the Inventory
+
+Basically, this inventory object acts a record of objects that are applied as a group.
+This object can be consumed by a client such as
+[cli-experimental](https://github.com/kubernetes-sigs/cli-experimental).
+The client can recognize the inventory annotations and take proper actions
+when running apply, prune and delete.
+
+### Example
+Take following `kustomization.yaml` as an example
+```yaml
+resources:
+- deployment.yaml
+- service.yaml
+
+
+secretGenerator:
+- name: pass
+  literals:
+  - password=secret
+
+inventory:
+  type: ConfigMap
+  configMap:
+    name: root-cm
+    namespace: default
+
+namespace: default
+```
+
+where the `deployment.yaml` is
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mysql
+  labels:
+    app: mysql
+spec:
+  revisionHistoryLimit: 2
+  selector:
+    matchLabels:
+      app: mysql
+  strategy:
+    type: Recreate
+  template:
+    metadata:
+      labels:
+        app: mysql
+    spec:
+      containers:
+      - image: mysql:5.6
+        name: mysql
+        env:
+        - name: MYSQL_ROOT_PASSWORD
+          valueFrom:
+            secretKeyRef:
+              name: pass
+              key: password
+        ports:
+        - containerPort: 3306
+          name: mysql
+        volumeMounts:
+        - name: mysql-persistent-storage
+          mountPath: /var/lib/mysql
+      volumes:
+      - name: mysql-persistent-storage
+        emptyDir: {}
+```
+
+and the `service.yaml` is
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: mysql
+  labels:
+    app: mysql
+spec:
+  ports:
+    - port: 3306
+  selector:
+    app: mysql
+```
+
+Running `kustomize build` gives 4 objects.
+Besides the Deployment `mysql`, the Service `mysql`,
+and the Secret `pass`, the output also contains a
+ConfigMap object as
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  annotations:
+    kustomize.config.k8s.io/Inventory: '{"current":{"apps_v1_Deployment|default|mysql":null,"~G_v1_Secret|default|pass-dfg7h97cf6":[{"group":"apps","version":"v1","kind":"Deployment","name":"mysql","namespace":"default"}],"~G_v1_Service|default|mysql":null}}'
+    kustomize.config.k8s.io/InventoryHash: 7mgt867b75
+  name: root-cm
+  namespace: default
+```
+
+It is clear that this ConfigMap contains an `Inventory` annotation.
+
+
+### Hash
+Note that in the ConfigMap generated from `inventory` field, there is a hash
+`b965tb9c7d`. It is the value for annotation `kustomize.config.k8s.io/InventoryHash`.
+
+This hash is computed by hashing all the keys in data field, which is the following list
+in this example.
+```yaml
+apps_v1_Deployment|default|mysql
+~G_v1_Secret|default|pass-dfg7h97cf6
+~G_v1_Service|default|mysql
+```
+When any object is added or removed from the kustomzation target, the hash changes. Thus by simply comparing the hash in the inventory objects, one can determine if the list of objects has changed.
+
+
+### How prune works
+In [cli-experimental](https://github.com/kubernetes-sigs/cli-experimental), there are different subcommands, `apply` and `prune`. Both are able to recognize an _inventory_ object and looking for its existing object on the cluster.
+
+the `apply` command
+recognizes the _inventory_ object by the annotation `kustomize.config.k8s.io/InventoryHash`. It then compares the current hash with the hash for the same object in the cluster. Since the hash reflects if there is any object added or removed, `apply` takes different actions correspondingly.
+- When there is no existing _inventory_ object in the cluster, apply creates the inventory object.
+- When the current hash is the same as the one in cluster, apply doesn't change the existing object in the cluster.
+- when the current hash is different, apply merges the inventory annotation of the existing object in the cluster and the incoming object. The hash is updated to the latest hash.
+
+
+The `prune` command parses the value of `kustomize.config.k8s.io/Inventory` of the existing _inventory_ object and computes two sets of objects based on the parsed data.
+To be simple,
+- The items in `Inventory.Current` will be kept
+- The items in `Inventory.Previous` will be pruned when they
+  are not needed.
+

docs/kustomization.yaml

@@ -1,324 +0,0 @@
-# Copyright 2018 The Kubernetes Authors.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
-# ----------------------------------------------------
-# Example kustomization.yaml content.
-#
-# This file declares the customization provided by
-# the kustomize program.
-#
-# Since customization is, by definition, _custom_,
-# there are no sensible default values for the fields
-# in this file.
-#
-# The field values used below are merely examples, not
-# to be copied literally.  The values won't work if
-# they happen to be references to external files that
-# don't exist.
-#
-# In practice, fields with no value should simply be
-# omitted from kustomization.yaml to reduce the content
-# visible in configuration reviews.
-# ----------------------------------------------------
-# apiVersion and kind of Kustomization
-apiVersion: kustomize.config.k8s.io/v1beta1
-kind: Kustomization
-
-# Adds namespace to all resources.
-namespace: my-namespace
-
-# Value of this field is prepended to the
-# names of all resources, e.g. a deployment named
-# "wordpress" becomes "alices-wordpress".
-namePrefix: alices-
-
-# Value of this field is appended to the
-# names of all resources, e.g. a deployment named
-# "wordpress" becomes "wordpress-v2".
-# The suffix is appended before content hash
-# if resource type is ConfigMap or Secret.
-nameSuffix: -v2
-
-# Labels to add to all resources and selectors.
-commonLabels:
-  someName: someValue
-  owner: alice
-  app: bingo
-
-# Annotations (non-identifying metadata)
-# to add to all resources.  Like labels,
-# these are key value pairs.
-commonAnnotations:
-  oncallPager: 800-555-1212
-
-# Each entry in this list must resolve to an existing
-# resource definition in YAML.  These are the resource
-# files that kustomize reads, modifies and emits as a
-# YAML string, with resources separated by document
-# markers ("---").
-resources:
-- some-service.yaml
-- sub-dir/some-deployment.yaml
-
-# Each entry in this list results in the creation of
-# one ConfigMap resource (it's a generator of n maps).
-# The example below creates two ConfigMaps. One with the
-# names and contents of the given files, the other with
-# key/value as data.
-# Each configMapGenerator item accepts a parameter of
-# behavior: [create|replace|merge]. This allows an overlay to modify or
-# replace an existing configMap from the parent.
-configMapGenerator:
-- name: myJavaServerProps
-  files:
-  - application.properties
-  - more.properties
-- name: myJavaServerEnvVars
-  literals:	
-  - JAVA_HOME=/opt/java/jdk
-  - JAVA_TOOL_OPTIONS=-agentlib:hprof
-
-# Each entry in this list results in the creation of
-# one Secret resource (it's a generator of n secrets).
-secretGenerator:
-- name: app-tls
-  files:
-    - secret/tls.cert
-    - secret/tls.key
-  type: "kubernetes.io/tls"
-- name: app-tls-namespaced
-  # you can define a namespace to generate secret in, defaults to: "default"
-  namespace: apps
-  files:
-    - tls.crt=catsecret/tls.cert
-    - tls.key=secret/tls.key
-  type: "kubernetes.io/tls"
-- name: env_file_secret
-  # env is a path to a file to read lines of key=val
-  # you can only specify one env file per secret.
-  env: env.txt
-  type: Opaque
-
-# generatorOptions modify behavior of all ConfigMap and Secret generators
-generatorOptions:
-  # labels to add to all generated resources
-  labels:
-    kustomize.generated.resources: somevalue
-  # annotations to add to all generated resources
-  annotations:
-    kustomize.generated.resource: somevalue
-  # disableNameSuffixHash is true disables the default behavior of adding a
-  # suffix to the names of generated resources that is a hash of
-  # the resource contents.
-  disableNameSuffixHash: true
-
-# Each entry in this list should resolve to a directory
-# containing a kustomization file, else the
-# customization fails.
-#
-# The entry could be a relative path pointing to a local directory
-# or a url pointing to a directory in a remote repo.
-# The url should follow hashicorp/go-getter URL format
-# https://github.com/hashicorp/go-getter#url-format
-#
-# The presence of this field means this file (the file
-# you a reading) is an _overlay_ that further
-# customizes information coming from these _bases_.
-#
-# Typical use case: a dev, staging and production
-# environment that are mostly identical but differing
-# crucial ways (image tags, a few server arguments,
-# etc. that differ from the common base).
-bases:
-- ../../base
-- github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6
-- github.com/Liujingfang1/mysql
-- github.com/Liujingfang1/kustomize//examples/helloWorld?ref=test-branch
-
-# Each entry in this list should resolve to
-# a partial or complete resource definition file.
-#
-# The names in these (possibly partial) resource files
-# must match names already loaded via the `resources`
-# field or via `resources` loaded transitively via the
-# `bases` entries.  These entries are used to _patch_
-# (modify) the known resources.
-#
-# Small patches that do one thing are best, e.g. modify
-# a memory request/limit, change an env var in a
-# ConfigMap, etc.  Small patches are easy to review and
-# easy to mix together in overlays.
-patchesStrategicMerge:
-- service_port_8888.yaml
-- deployment_increase_replicas.yaml
-- deployment_increase_memory.yaml
-
-# Each entry in this list should resolve to
-# a kubernetes object and a JSON patch that will be applied
-# to the object.
-# The JSON patch is documented at https://tools.ietf.org/html/rfc6902
-#
-# target field points to a kubernetes object within the same kustomization
-# by the object's group, version, kind, name and namespace.
-# path field is a relative file path of a JSON patch file.
-# The content in this patch file can be either in JSON format as
-#
-#  [
-#    {"op": "add", "path": "/some/new/path", "value": "value"},
-#    {"op": "replace", "path": "/some/existing/path", "value": "new value"}
-#  ]
-#
-# or in YAML format as
-#
-# - op: add
-#   path: /some/new/path
-#   value: value
-# - op:replace
-#   path: /some/existing/path
-#   value: new value
-#
-patchesJson6902:
-- target:
-    version: v1
-    kind: Deployment
-    name: my-deployment
-  path: add_init_container.yaml
-- target:
-    version: v1
-    kind: Service
-    name: my-service
-  path: add_service_annotation.yaml
-
-# Each entry in this list should be a relative path to
-# a file for custom resource definition(CRD) in openAPI definition.
-#
-# The presence of this field is to allow kustomize be
-# aware of CRDs and apply proper
-# transformation for any objects in those types.
-#
-# Typical use case: A CRD object refers to a ConfigMap object.
-# In kustomization, the ConfigMap object name may change by adding namePrefix, nameSuffix, or hashing
-# The name reference for this ConfigMap object in CRD object need to be
-# updated with namePrefix, nameSuffix, or hashing in the same way.
-#
-# The annotations can be put into openAPI definitions are:
-#   "x-kubernetes-annotation": ""
-#   "x-kubernetes-label-selector": ""
-#   "x-kubernetes-identity": ""
-#   "x-kubernetes-object-ref-api-version": "v1",
-#   "x-kubernetes-object-ref-kind": "Secret",
-#   "x-kubernetes-object-ref-name-key": "name",
-crds:
-- crds/typeA.json
-- crds/typeB.json
-
-# Vars are used to capture text from one resource's field
-# and insert that text elsewhere.
-#
-# For example, suppose someone specifies the name of a k8s Service
-# object in a container's command line, and the name of a
-# k8s Secret object in a container's environment variable,
-# so that the following would work:
-# ```
-#   containers:
-#     - image: myimage
-#       command: ["start", "--host", "$(MY_SERVICE_NAME)"]
-#       env:
-#         - name: SECRET_TOKEN
-#           value: $(SOME_SECRET_NAME)
-# ```
-#
-# To do so, add an entry to `vars:` as follows:
-#
-vars:
-  - name: SOME_SECRET_NAME
-    objref:
-      kind: Secret
-      name: my-secret
-      apiVersion: v1
-  - name: MY_SERVICE_NAME
-    objref:
-      kind: Service
-      name: my-service
-      apiVersion: v1
-    fieldref:
-      fieldpath: metadata.name
-  - name: ANOTHER_DEPLOYMENTS_POD_RESTART_POLICY
-    objref:
-      kind: Deployment
-      name: my-deployment
-      apiVersion: apps/v1
-    fieldref:
-      fieldpath: spec.template.spec.restartPolicy
-#
-# A var is a tuple of variable name, object reference and field
-# reference within that object.  That's where the text is found.
-#
-# The field reference is optional; it defaults to `metadata.name`,
-# a normal default, since kustomize is used to generate or
-# modify the names of resources.
-#
-# At time of writing, only string type fields are supported.
-# No ints, bools, arrays etc.  It's not possible to, say,
-# extract the name of the image in container number 2 of
-# some pod template.
-#
-# A variable reference, i.e. the string '$(FOO)', can only
-# be placed in particular fields of particular objects as
-# specified by kustomize's configuration data.
-#
-# The default config data for vars is at
-# https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/transformers/config/defaultconfig/varreference.go
-# Long story short, the default targets are all
-# container command args and env value fields.
-#
-# Vars should _not_ be used for inserting names in places
-# where kustomize is already handling that job.  E.g.,
-# a Deployment may reference a ConfigMap by name, and
-# if kustomize changes the name of a ConfigMap, it knows
-# to change the name reference in the Deployment.
-
-
-# Images modify the name, tags and/or digest for images without creating patches.
-# E.g. Given this kubernetes Deployment fragment:
-# ```
-#  containers:
-#    - name: mypostgresdb
-#      image: postgres:8
-#    - name: nginxapp
-#      image: nginx:1.7.9
-#    - name: myapp
-#      image: my-demo-app:latest
-#    - name: alpine-app
-#      image: alpine:3.7
-#```
-# one can change the `image` in the following ways:
-# 
-# - `postgres:8` to `my-registry/my-postgres:v1`,
-# - nginx tag `1.7.9` to `1.8.0`,
-# - image name `my-demo-app` to `my-app`,
-# - alpine's tag `3.7` to a digest value
-#
-# all with the following *kustomization*:
-
-images:
-  - name: postgres
-    newName: my-registry/my-postgres
-    newTag: v1
-  - name: nginx
-    newTag: 1.8.0
-  - name: my-demo-app
-    newName: my-app
-  - name: alpine
-    digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3

docs/plugins/README.md

@@ -0,0 +1,374 @@
+# kustomize plugins
+
+Quick guides:
+
+* [linux exec plugin in 60 sec](execPluginGuidedExample.md)
+* [linux Go plugin in 60 sec](goPluginGuidedExample.md)
+
+Kustomize offers a plugin framework allowing
+people to write their own resource _generators_
+and _transformers_.
+
+[generator options]: ../../examples/generatorOptions.md
+[transformer configs]: ../../examples/transformerconfigs
+
+Write a plugin when changing [generator options]
+or [transformer configs] doesn't meet your needs.
+
+[12-factor]: https://12factor.net
+
+ * A _generator_ plugin could be a helm chart
+   inflator, or a plugin that emits all the
+   components (deployment, service, scaler,
+   ingress, etc.) needed by someone's [12-factor]
+   application, based on a smaller number of free
+   variables.
+
+ * A _transformer_ plugin might perform special
+   container command line edits, or any other
+   transformation beyond those provided by the
+   builtin (`namePrefix`, `commonLabels`, etc.)
+   transformers.
+
+## Specification in `kustomization.yaml`
+
+Start by adding a `generators` and/or `transformers`
+field to your kustomization.
+
+Each field accepts a string list:
+
+> ```
+> generators:
+> - relative/path/to/some/file.yaml
+> - relative/path/to/some/kustomization
+> - /absolute/path/to/some/kustomization
+> - https://github.com/org/repo/some/kustomization
+>
+> transformers:
+> - {as above}
+> ```
+
+The value of each entry in a `generators` or
+`transformers` list must be a relative path to a
+YAML file, or a path or URL to a [kustomization].
+This is the same format as demanded by the
+`resources` field.
+
+[kustomization]: ../glossary.md#kustomization
+
+YAML files are read from disk directly.  Paths or
+URLs leading to kustomizations trigger an
+in-process kustomization run.  Each of the
+resulting objects is now further interpreted by
+kustomize as a _plugin configuration_ object.
+
+
+## Configuration
+
+A kustomization file could have the following lines:
+
+```
+generators:
+- chartInflator.yaml
+```
+
+Given this, the kustomization process would expect
+to find a file called `chartInflator.yaml` in the
+kustomization [root](../glossary.md#kustomization-root).
+
+This is the plugin's configuration file;
+it contains a YAML configuration object.
+
+The file `chartInflator.yaml` could contain:
+
+```
+apiVersion: someteam.example.com/v1
+kind: ChartInflator
+metadata:
+  name: notImportantHere
+chartName: minecraft
+```
+
+__The `apiVersion` and `kind` fields are
+used to locate the plugin.__
+
+[k8s object]: ../glossary.md#kubernetes-style-object
+
+Thus, these fields are required.  They are also
+required because a kustomize plugin configuration
+object is also a [k8s object].
+
+To get the plugin ready to generate or transform,
+it is given the entire contents of the
+configuration file.
+
+[NameTransformer]: ../../plugin/builtin/prefixsuffixtransformer/PrefixSuffixTransformer_test.go
+[ChartInflator]: ../../plugin/someteam.example.com/v1/chartinflator/ChartInflator_test.go
+[plugins]: ../../plugin/builtin
+
+For more examples of plugin configuration YAML,
+browse the unit tests below the [plugins] root,
+e.g. the tests for [ChartInflator] or
+[NameTransformer].
+
+
+## Placement
+
+Each plugin gets its own dedicated directory named
+
+[`XDG_CONFIG_HOME`]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+
+```
+$XDG_CONFIG_HOME/kustomize/plugin
+    /${apiVersion}/LOWERCASE(${kind})
+```
+
+The default value of [`XDG_CONFIG_HOME`] is
+`$HOME/.config`.
+
+The one-plugin-per-directory requirement eases
+creation of a plugin bundle (source, tests, plugin
+data files, etc.) for sharing.
+
+In the case of a [Go plugin](#go-plugins), it also
+allows one to provide a `go.mod` file for the
+single plugin, easing resolution of package
+version dependency skew.
+
+When loading, kustomize will first look for an
+_executable_ file called
+
+```
+$XDG_CONFIG_HOME/kustomize/plugin
+    /${apiVersion}/LOWERCASE(${kind})/${kind}
+```
+
+If this file is not found or is not executable,
+kustomize will look for a file called `${kind}.so`
+in the same directory and attempt to load it as a
+[Go plugin](#go-plugins).
+
+If both checks fail, the plugin load fails the overall
+`kustomize build`.
+
+## Execution
+
+Plugins are only used during a run of the
+`kustomize build` command.
+
+Generator plugins are run after processing the
+`resources` field (which itself can be viewed as a
+generator, simply reading objects from disk).
+
+The full set of resources is then passed into the
+transformation pipeline, wherein builtin
+transformations like `namePrefix` and
+`commonLabel` are applied (if they were specified
+in the kustomization file), followed by the
+user-specified transformers in the `transformers`
+field.
+
+The order specified in the `transformers` field is
+respected, as transformers cannot be expected to
+be commutative.
+
+#### No Security
+
+Kustomize plugins do not run in any kind of
+kustomize-provided sandbox.  There's no notion
+of _"plugin security"_.
+
+A `kustomize build` that tries to use plugins but
+omits the flag
+
+> `--enable_alpha_plugins`
+
+will not load plugins and will fail with a
+warning about plugin use.
+
+The use of this flag is an opt-in acknowledging
+the unstable (alpha) plugin API, the absence of
+plugin provenance, and the fact that a plugin
+is not part of kustomize.
+
+To be clear, some kustomize plugin downloaded
+from the internet might wonderfully transform
+k8s config in a desired manner, while also
+quietly doing anything the user could do to the
+system running `kustomize build`.
+
+## Authoring
+
+There are two kinds of plugins, [exec](#exec-plugins) and [Go](#go-plugins).
+
+### Exec plugins
+
+A _exec plugin_ is any executable that accepts a
+single argument on its command line - the name of
+a YAML file containing its configuration (the file name
+provided in the kustomization file).
+
+> TODO: restrictions on plugin to allow the _same exec
+> plugin_ to be targetted by  both the
+> `generators` and `transformers` fields.
+>
+> - first arg could be the fixed string
+>   `generate` or `transform`,
+>   (the name of the configuration file moves to
+>   the 2nd arg), or
+> - or by default an exec plugin behaves as a tranformer
+>   unless a flag `-g` is provided, switching the
+>   exec plugin to behave as a generator.
+
+[helm chart inflator]: ../../plugin/someteam.example.com/v1/chartinflator
+[bashed config map]: ../../plugin/someteam.example.com/v1/bashedconfigmap
+[sed transformer]: ../../plugin/someteam.example.com/v1/sedtransformer
+[hashicorp go-getter]: ../../plugin/someteam.example.com/v1/gogetter
+
+#### Examples
+
+ * [helm chart inflator] - A generator that inflates a helm chart.
+ * [bashed config map] -  Super simple configMap generation from bash.
+ * [sed transformer] - Define your unstructured edits using a
+   plugin like this one.
+ * [hashicorp go-getter] - Download kustomize layes and build it to generate resources
+
+A generator plugin accepts nothing on `stdin`, but emits
+generated resources to `stdout`.
+
+A transformer plugin accepts resource YAML on `stdin`,
+and emits those resources, presumably transformed, to
+`stdout`.
+
+kustomize uses an exec plugin adapter to provide
+marshalled resources on `stdin` and capture
+`stdout` for further processing.
+
+#### Generator Options
+
+A generator exec plugin can adjust the generator options for the resources it emits by setting one of the following internal annotations. 
+
+> NOTE: These annotations are local to kustomize and will not be included in the final output.
+
+**`kustomize.config.k8s.io/needs-hash`**
+
+Resources can be marked as needing to be processed by the internal hash transformer by including the `needs-hash` annotation. When set valid values for the annotation are `"true"` and `"false"` which respectively enable or disable hash suffixing for the resource. Omitting the annotation is equivalent to setting the value `"false"`.
+
+If this annotation is set on a resource not supported by the hash transformer the build will fail.
+
+Example:
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cm-test
+  annotations:
+    kustomize.config.k8s.io/needs-hash: "true"
+data:
+  foo: bar   
+```
+
+**`kustomize.config.k8s.io/behavior`**
+
+The `behavior` annotation will influence how conflicts are handled for resources emitted by the plugin. Valid values include "create", "merge", and "replace" with "create" being the default. 
+
+Example:
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cm-test
+  annotations:
+    kustomize.config.k8s.io/behavior: "merge"
+data:
+  foo: bar   
+```
+
+### Go plugins
+
+Be sure to read [Go plugin caveats](goPluginCaveats.md).
+
+[Go plugin]: https://golang.org/pkg/plugin/
+
+A `.go` file can be a [Go plugin] if it declares
+'main' as it's package, and exports a symbol to
+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.
+
+A Go plugin for kustomize looks like this:
+
+> ```
+> package main
+>
+> import (
+>	"sigs.k8s.io/kustomize/v3/pkg/ifc"
+>	"sigs.k8s.io/kustomize/v3/pkg/resmap"
+>   ...
+> )
+>
+> 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 {...}
+> ```
+
+Use of the identifiers `plugin`, `KustomizePlugin`
+and implementation of the method signature
+`Config` is required.
+
+Implementing the `Generator` or `Transformer`
+method allows (respectively) the plugin's config
+file to be added to the `generators` or
+`transformers` field in the kustomization file.
+Do one or the other or both as desired.
+
+[secret generator]: ../../plugin/someteam.example.com/v1/secretsfromdatabase
+[service generator]: ../../plugin/someteam.example.com/v1/someservicegenerator
+[string prefixer]: ../../plugin/someteam.example.com/v1/stringprefixer
+[date prefixer]: ../../plugin/someteam.example.com/v1/dateprefixer
+[sops encoded secrets]: https://github.com/monopole/sopsencodedsecrets
+
+#### Examples
+
+ * [service generator] - generate a service from a name and port argument.
+ * [string prefixer] - uses the value in `metadata/name` as the prefix.
+   This particular example exists to show how a plugin can
+   transform the behavior of a plugin.  See the
+   `TestTransformedTransformers` test in the `target` package.
+ * [date prefixer] - prefix the current date to resource names, a simple
+   example used to modify the string prefixer plugin just mentioned.
+ * [secret generator] - generate secrets from a toy database.
+ * [sops encoded secrets] - a more complex secret generator.
+ * [All the builtin plugins](../../plugin/builtin).
+   User authored plugins are
+   on the same footing as builtin operations.
+
+A Go plugin can be both a generator and a
+transformer.  The `Generate` method will run along
+with all the other generators before the
+`Transform` method runs.
+
+Here's a build command that sensibly assumes the
+plugin source code sits in the directory where
+kustomize expects to find `.so` files:
+
+```
+d=$XDG_CONFIG_HOME/kustomize/plugin\
+/${apiVersion}/LOWERCASE(${kind})
+
+go build -buildmode plugin \
+   -o $d/${kind}.so $d/${kind}.go
+```
+

docs/plugins/builtins.md

@@ -0,0 +1,683 @@
+<!-- 
+  TODO: Generate this file (or files) from
+        data in directories under plugin/builtin.
+        
+        This file too hard to maintain distinctly
+        from what's going on in those directories.
+        We could expand pluginator to do this, since
+        it already scans the relevant files in the
+        relevant directory to generate the static
+        factory methods for plugins.
+-->
+
+# Builtin Plugins
+
+A list of kustomize's builtin plugins (both
+generators and transformers).
+
+For each plugin, an example is given for
+
+* implicitly triggering
+the plugin via a dedicated kustomization
+file field (e.g. the `AnnotationsTransformer` is 
+triggered by the `commonAnnotations` field).
+
+* explicitly triggering the plugin
+via the `generators` or `transformers` field
+(by providing a config file specifying the
+plugin).
+
+The former method is convenient but limited in 
+power as most of the plugins arguments must
+be defaulted.  The latter method allows for
+complete plugin argument specification.
+
+
+[types.GeneratorOptions]: ../../pkg/types/generatoroptions.go
+[types.SecretArgs]: ../../pkg/types/secretargs.go
+[types.ConfigMapArgs]: ../../pkg/types/configmapargs.go
+[config.FieldSpec]: ../../pkg/transformers/config/fieldspec.go
+[types.ObjectMeta]: ../../pkg/types/objectmeta.go
+[types.Selector]: ../../pkg/types/selector.go
+[types.Replica]: ../../pkg/types/replica.go
+[types.PatchStrategicMerge]: ../../pkg/types/patchstrategicmerge.go
+[types.PatchTarget]: ../../pkg/types/patchtarget.go
+[image.Image]: ../../pkg/image/image.go
+
+## _AnnotationTransformer_
+### Usage via `kustomization.yaml`
+
+#### field name: `commonAnnotations`
+
+Adds annotions (non-identifying metadata) to add
+all resources. Like labels, these are key value
+pairs.
+
+```
+commonAnnotations:
+  oncallPager: 800-555-1212
+```
+
+### Usage via plugin
+#### Arguments
+
+> Annotations map\[string\]string
+>
+> FieldSpecs  \[\][config.FieldSpec]
+
+#### Example
+> ```
+> apiVersion: builtin
+> kind: AnnotationsTransformer
+> metadata:
+>   name: not-important-to-example
+> annotations:
+>   app: myApp
+>   greeting/morning: a string with blanks
+> fieldSpecs:
+> - path: metadata/annotations
+>   create: true
+> ```
+
+
+
+## _ConfigMapGenerator_
+
+### Usage via `kustomization.yaml`
+
+#### field name: `configMapGenerator`
+
+Each entry in this list results in the creation of
+one ConfigMap resource (it's a generator of n maps).
+
+The example below creates two ConfigMaps. One with the
+names and contents of the given files, the other with
+key/value as data.
+
+Each configMapGenerator item accepts a parameter of
+`behavior: [create|replace|merge]`.
+This allows an overlay to modify or
+replace an existing configMap from the parent.
+
+```
+configMapGenerator:
+- name: my-java-server-props
+  files:
+  - application.properties
+  - more.properties
+- name: my-java-server-env-vars
+  literals:	
+  - JAVA_HOME=/opt/java/jdk
+  - JAVA_TOOL_OPTIONS=-agentlib:hprof
+```
+
+It is also possible to
+[define a key](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file)
+to set a name different than the filename.
+
+The example below creates a ConfigMap
+with the name of file as `myFileName.ini`
+while the _actual_ filename from which the
+configmap is created is `whatever.ini`.
+
+```
+configMapGenerator:
+- name: app-whatever
+  files:
+  - myFileName.ini=whatever.ini
+```
+
+### Usage via plugin
+#### Arguments
+
+> [types.GeneratorOptions]
+>
+> [types.ConfigMapArgs]
+
+#### Example
+> ```
+> apiVersion: builtin
+> kind: ConfigMapGenerator
+> metadata:
+>   name: mymap
+> envs:
+> - devops.env
+> - uxteam.env
+> literals:
+> - FRUIT=apple
+> - VEGETABLE=carrot
+> ```
+
+
+## _ImageTagTransformer_
+### Usage via `kustomization.yaml`
+
+#### field name: `image`
+
+Images modify the name, tags and/or digest for images
+without creating patches.  E.g. Given this
+kubernetes Deployment fragment:
+
+```
+containers:
+- name: mypostgresdb
+  image: postgres:8
+- name: nginxapp
+  image: nginx:1.7.9
+- name: myapp
+  image: my-demo-app:latest
+- name: alpine-app
+  image: alpine:3.7
+```
+
+one can change the `image` in the following ways:
+ 
+ - `postgres:8` to `my-registry/my-postgres:v1`,
+ - nginx tag `1.7.9` to `1.8.0`,
+ - image name `my-demo-app` to `my-app`,
+ - alpine's tag `3.7` to a digest value
+
+all with the following *kustomization*:
+
+```
+images:
+- name: postgres
+  newName: my-registry/my-postgres
+  newTag: v1
+- name: nginx
+  newTag: 1.8.0
+- name: my-demo-app
+  newName: my-app
+- name: alpine
+  digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3
+```
+
+### Usage via plugin
+#### Arguments
+
+> ImageTag   [image.Image]
+>
+> FieldSpecs \[\][config.FieldSpec]
+
+#### Example
+> ```
+> apiVersion: builtin
+> kind: ImageTagTransformer
+> metadata:
+>   name: not-important-to-example
+> imageTag:
+>   name: nginx
+>   newTag: v2
+> ```
+
+
+
+## _LabelTransformer_
+### Usage via `kustomization.yaml`
+
+#### field name: `commonLabels`
+
+Adds labels to all resources and selectors
+
+```
+commonLabels:
+  someName: someValue
+  owner: alice
+  app: bingo
+```
+
+### Usage via plugin
+#### Arguments
+
+> Labels  map\[string\]string
+>
+> FieldSpecs \[\][config.FieldSpec]
+
+#### Example
+> ```
+> apiVersion: builtin
+> kind: LabelTransformer
+> metadata:
+>   name: not-important-to-example
+> labels:
+>   app: myApp
+>   env: production
+> fieldSpecs:
+> - path: metadata/labels
+>   create: true
+> ```
+
+
+
+
+
+
+
+
+## _NamespaceTransformer_
+### Usage via `kustomization.yaml`
+
+#### field name: `namespace`
+
+Adds namespace to all resources
+
+```
+namespace: my-namespace
+```
+
+### Usage via plugin
+#### Arguments
+
+> [types.ObjectMeta]
+>
+> FieldSpecs \[\][config.FieldSpec]
+
+#### Example
+> ```
+> apiVersion: builtin
+>  kind: NamespaceTransformer
+>  metadata:
+>    name: not-important-to-example
+>    namespace: test
+>  fieldSpecs:
+>  - path: metadata/namespace
+>    create: true
+>  - path: subjects
+>    kind: RoleBinding
+>    group: rbac.authorization.k8s.io
+>  - path: subjects
+>    kind: ClusterRoleBinding
+>    group: rbac.authorization.k8s.io
+> ```
+
+
+
+
+
+## _PatchesJson6902_
+### Usage via `kustomization.yaml`
+
+#### field name: `patchesJson6902`
+
+Each entry in this list should resolve to
+a kubernetes object and a JSON patch that will be applied
+to the object.
+The JSON patch is documented at https://tools.ietf.org/html/rfc6902
+
+target field points to a kubernetes object within the same kustomization
+by the object's group, version, kind, name and namespace.
+path field is a relative file path of a JSON patch file.
+The content in this patch file can be either in JSON format as
+
+```
+ [
+   {"op": "add", "path": "/some/new/path", "value": "value"},
+   {"op": "replace", "path": "/some/existing/path", "value": "new value"}
+ ]
+ ```
+
+or in YAML format as
+
+```
+- op: add
+  path: /some/new/path
+  value: value
+- op: replace
+  path: /some/existing/path
+  value: new value
+```
+
+```
+patchesJson6902:
+- target:
+    version: v1
+    kind: Deployment
+    name: my-deployment
+  path: add_init_container.yaml
+- target:
+    version: v1
+    kind: Service
+    name: my-service
+  path: add_service_annotation.yaml
+```
+
+The patch content can be an inline string as well:
+
+```
+patchesJson6902:
+- target:
+    version: v1
+    kind: Deployment
+    name: my-deployment
+  patch: |-
+    - op: add
+      path: /some/new/path
+      value: value
+    - op: replace
+      path: /some/existing/path
+      value: "new value"
+```
+
+### Usage via plugin
+#### Arguments
+> Target [types.PatchTarget]
+>
+> Path   string
+>
+> JsonOp string
+
+#### Example
+> ```
+> apiVersion: builtin
+> kind: PatchJson6902Transformer
+> metadata:
+>   name: not-important-to-example
+> target:
+>   group: apps
+>   version: v1
+>   kind: Deployment
+>   name: my-deploy
+> path: jsonpatch.json
+> ```
+
+
+## _PatchesStrategicMerge_
+### Usage via `kustomization.yaml`
+
+#### field name: `patchesStrategicMerge`
+
+Each entry in this list should be either a relative
+file path or an inline content
+resolving to a partial or complete resource
+definition.
+
+The names in these (possibly partial) resource
+files must match names already loaded via the
+`resources` field.  These entries are used to
+_patch_ (modify) the known resources.
+
+Small patches that do one thing are best, e.g. modify
+a memory request/limit, change an env var in a
+ConfigMap, etc.  Small patches are easy to review and
+easy to mix together in overlays.
+
+```
+patchesStrategicMerge:
+- service_port_8888.yaml
+- deployment_increase_replicas.yaml
+- deployment_increase_memory.yaml
+```
+
+The patch content can be a inline string as well.
+```
+patchesStrategicMerge:
+- |-
+  apiVersion: apps/v1
+  kind: Deployment
+  metadata:
+    name: nginx
+  spec:
+    template:
+      spec:
+        containers:
+          - name: nginx
+            image: nignx:latest
+```
+
+Note that kustomize does not support more than one patch
+for the same object that contain a _delete_ directive. To remove
+several fields / slice elements from an object create a single
+patch that performs all the needed deletions.
+
+### Usage via plugin
+
+#### Arguments
+
+> Paths \[\][types.PatchStrategicMerge]
+>
+> Patches string
+
+
+#### Example
+> ```
+> apiVersion: builtin
+> kind: PatchStrategicMergeTransformer
+> metadata:
+>   name: not-important-to-example
+> paths:
+> - patch.yaml
+> ```
+
+
+## _PatchTransformer_
+### Usage via `kustomization.yaml`
+
+#### field name: `patches`
+
+Each entry in this list should resolve to an Patch
+object, which includes a patch and a target selector. 
+The patch can be either a strategic merge patch or a
+JSON patch. it can be either a patch file or an inline
+string. The target selects
+resources by group, version, kind, name, namespace,
+labelSelector and annotationSelector. A resource
+which matches all the specified fields is selected
+to apply the patch.
+
+```
+patches:
+- path: patch.yaml
+  target:
+    group: apps
+    version: v1
+    kind: Deployment
+    name: deploy.*
+    labelSelector: "env=dev"
+    annotationSelector: "zone=west"
+- patch: |-
+    - op: replace
+      path: /some/existing/path
+      value: new value
+  target:
+    kind: MyKind
+    labelSelector: "env=dev"        
+```
+
+The `name` and `namespace` fields of the patch target selector are
+automatically anchored regular expressions. This means that the value `myapp`
+is equivalent to `^myapp$`. 
+
+### Usage via plugin
+#### Arguments
+
+> Path string
+>
+> Patch string
+>
+> Target \*[types.Selector] 
+
+#### Example
+> ```
+> apiVersion: builtin
+> kind: PatchTransformer
+> metadata:
+>   name: not-important-to-example
+> patch: '[{"op": "replace", "path": "/spec/template/spec/containers/0/image", "value": "nginx:latest"}]'
+> target:
+>   name: .*Deploy
+>   kind: Deployment
+> ```
+
+
+
+
+## _PrefixSuffixTransformer_
+### Usage via `kustomization.yaml`
+
+#### field names: `namePrefix`, `nameSuffix`
+
+Prepends or postfixes the value to the names
+of all resources.
+
+E.g. a deployment named `wordpress` could
+become `alices-wordpress` or  `wordpress-v2`
+or `alices-wordpress-v2`. 
+
+```
+namePrefix: alices-
+nameSuffix: -v2
+```
+
+The suffix is appended before the content hash if
+the resource type is ConfigMap or Secret.
+
+### Usage via plugin
+#### Arguments
+
+> Prefix     string
+>
+> Suffix     string
+>
+> FieldSpecs \[\][config.FieldSpec]
+
+#### Example
+> ```
+> apiVersion: builtin
+> kind: PrefixSuffixTransformer
+> metadata:
+>   name: not-important-to-example
+> prefix: baked-
+> suffix: -pie
+> fieldSpecs:
+>   - path: metadata/name
+> ```
+
+
+
+## _ReplicaCountTransformer_
+### Usage via `kustomization.yaml`
+
+#### field name: `replicas`
+
+Replicas modified the number of replicas for a resource.
+
+E.g. Given this kubernetes Deployment fragment:
+
+```
+kind: Deployment
+metadata:
+  name: deployment-name
+spec:
+  replicas: 3
+```
+
+one can change the number of replicas to 5
+by adding the following to your kustomization:
+
+```
+replicas:
+- name: deployment-name
+  count: 5
+```
+
+This field accepts a list, so many resources can
+be modified at the same time.
+
+As this declaration does not take in a `kind:` nor a `group:`
+it will match any `group` and `kind` that has a matching name and
+that is one of:
+- `Deployment`
+- `ReplicationController`
+- `ReplicaSet`
+- `StatefulSet`
+
+For more complex use cases, revert to using a patch.
+
+### Usage via plugin
+
+#### Arguments
+
+> Replica [types.Replica]
+>
+> FieldSpecs \[\][config.FieldSpec]
+
+#### Example
+> ```
+> apiVersion: builtin
+> kind: ReplicaCountTransformer
+> metadata:
+>   name: not-important-to-example
+> replica:
+>   name: myapp
+>   count: 23
+> fieldSpecs:
+> - path: spec/replicas
+>   create: true
+>   kind: Deployment
+> - path: spec/replicas
+>   create: true
+>   kind: ReplicationController
+> ```
+
+
+
+## _SecretGenerator_
+
+### Usage via `kustomization.yaml`
+
+#### field name: `secretGenerator`
+
+Each entry in the argument list
+results in the creation of
+one Secret resource
+(it's a generator of n secrets).
+
+```
+secretGenerator:
+- name: app-tls
+  files:
+  - secret/tls.cert
+  - secret/tls.key
+  type: "kubernetes.io/tls"
+- name: app-tls-namespaced
+  # you can define a namespace to generate
+  # a secret in, defaults to: "default"
+  namespace: apps
+  files:
+  - tls.crt=catsecret/tls.cert
+  - tls.key=secret/tls.key
+  type: "kubernetes.io/tls"
+- name: env_file_secret
+  envs:
+  - env.txt
+  type: Opaque
+```
+
+### Usage via plugin
+
+#### Arguments
+
+> [types.ObjectMeta]
+>
+> [types.GeneratorOptions]
+>
+> [types.SecretArgs]
+
+#### Example
+
+> ```
+> apiVersion: builtin
+> kind: SecretGenerator
+> metadata:
+>   name: my-secret
+>   namespace: whatever
+> behavior: merge
+> envs:
+> - a.env
+> - b.env
+> files:
+> - obscure=longsecret.txt
+> literals:
+> - FRUIT=apple
+> - VEGETABLE=carrot
+> ```

docs/plugins/execPluginGuidedExample.md

@@ -0,0 +1,229 @@
+# Exec plugin on linux in 60 seconds
+
+This is a (no reading allowed!) 60 second copy/paste guided
+example.  Full plugin docs [here](README.md).
+
+This demo writes and uses a somewhat ridiculous
+_exec_ plugin (written in bash) that generates a
+`ConfigMap`.
+
+This is a guide to try it without damaging your
+current setup.
+
+#### requirements
+
+ * linux, git, curl, Go 1.12
+
+
+## Make a place to work
+
+```
+DEMO=$(mktemp -d)
+```
+
+## Create a kustomization
+
+Make a kustomization directory to
+hold all your config:
+
+```
+MYAPP=$DEMO/myapp
+mkdir -p $MYAPP
+```
+
+Make a deployment config:
+
+```
+cat <<'EOF' >$MYAPP/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: the-deployment
+spec:
+  replicas: 3
+  template:
+    spec:
+      containers:
+      - name: the-container
+        image: monopole/hello:1
+        command: ["/hello",
+                  "--port=8080",
+                  "--date=$(THE_DATE)",
+                  "--enableRiskyFeature=$(ENABLE_RISKY)"]
+        ports:
+        - containerPort: 8080
+        env:
+        - name: THE_DATE
+          valueFrom:
+            configMapKeyRef:
+              name: the-map
+              key: today
+        - name: ALT_GREETING
+          valueFrom:
+            configMapKeyRef:
+              name: the-map
+              key: altGreeting
+        - name: ENABLE_RISKY
+          valueFrom:
+            configMapKeyRef:
+              name: the-map
+              key: enableRisky
+EOF
+```
+
+Make a service config:
+
+```
+cat <<EOF >$MYAPP/service.yaml
+kind: Service
+apiVersion: v1
+metadata:
+  name: the-service
+spec:
+  type: LoadBalancer
+  ports:
+  - protocol: TCP
+    port: 8666
+    targetPort: 8080
+EOF
+```
+
+Now make a config file for the plugin
+you're about to write.
+
+This config file is just another k8s resource
+object.  The values of its `apiVersion` and `kind`
+fields are used to _find_ the plugin code on your
+filesystem (more on this later).
+
+```
+cat <<'EOF' >$MYAPP/cmGenerator.yaml
+apiVersion: myDevOpsTeam
+kind: SillyConfigMapGenerator
+metadata:
+  name: whatever
+argsOneLiner: Bienvenue true
+EOF
+```
+
+Finally, make a kustomization file
+referencing all of the above:
+
+```
+cat <<EOF >$MYAPP/kustomization.yaml
+commonLabels:
+  app: hello
+resources:
+- deployment.yaml
+- service.yaml
+generators:
+- cmGenerator.yaml
+EOF
+```
+
+Review the files
+```
+ls -C1 $MYAPP
+```
+
+
+## Make a home for plugins
+
+Plugins must live in a particular place for
+kustomize to find them.
+
+This demo will use the ephemeral directory:
+
+```
+PLUGIN_ROOT=$DEMO/kustomize/plugin
+```
+
+The plugin config defined above in
+`$MYAPP/cmGenerator.yaml` specifies:
+
+> ```
+> apiVersion: myDevOpsTeam
+> kind: SillyConfigMapGenerator
+> ```
+
+This means the plugin must live in a directory
+named:
+
+```
+MY_PLUGIN_DIR=$PLUGIN_ROOT/myDevOpsTeam/sillyconfigmapgenerator
+
+mkdir -p $MY_PLUGIN_DIR
+```
+
+The directory name is the plugin config's
+_apiVersion_ followed by its lower-cased _kind_.
+
+A plugin gets its own directory to hold itself,
+its tests and any supplemental data files it
+might need.
+
+## Create the plugin
+
+There are two kinds of plugins, _exec_ and _Go_.
+
+Make an _exec_ plugin, installing it to the
+correct directory and file name.  The file name
+must match the plugin's _kind_ (in this case,
+`SillyConfigMapGenerator`):
+
+```
+cat <<'EOF' >$MY_PLUGIN_DIR/SillyConfigMapGenerator
+#!/bin/bash
+# Skip the config file name argument.
+shift
+today=`date +%F`
+echo "
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: the-map
+data:
+  today: $today
+  altGreeting: "$1"
+  enableRisky: "$2"
+"
+EOF
+```
+
+By definition, an _exec_ plugin must be executable:
+
+```
+chmod a+x $MY_PLUGIN_DIR/SillyConfigMapGenerator
+```
+
+## Download kustomize 3.0.0
+
+```
+mkdir -p $DEMO/bin
+gh=https://github.com/kubernetes-sigs/kustomize/releases/download
+url=$gh/v3.0.0-pre/kustomize_3.0.0-pre_linux_amd64
+curl -o $DEMO/bin/kustomize -L $url
+chmod u+x $DEMO/bin/kustomize
+```
+
+## Review the layout
+
+```
+tree $DEMO
+```
+
+## Build your app, using the plugin:
+
+```
+XDG_CONFIG_HOME=$DEMO $DEMO/bin/kustomize build --enable_alpha_plugins $MYAPP
+```
+
+Above, if you had set
+
+> ```
+> PLUGIN_ROOT=$HOME/.config/kustomize/plugin
+> ```
+
+there would be no need to use `XDG_CONFIG_HOME` in the
+_kustomize_ command above.
+

docs/plugins/goPluginCaveats.md

@@ -0,0 +1,116 @@
+[plugin package]: https://golang.org/pkg/plugin
+[Go modules]: https://github.com/golang/go/wiki/Modules
+[ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format
+[tensorflow plugin]: https://www.tensorflow.org/guide/extend/op
+
+# Go plugin Caveats
+
+A _Go plugin_ is a compilation artifact described
+by the Go [plugin package].  It is built with
+special flags and cannot run on its own.
+It must be loaded into a running Go program.
+
+> A normal program written in Go might be usable
+> as _exec plugin_, but is not a _Go plugin_.
+
+Go plugins allow kustomize extensions that run
+without the cost marshalling/unmarshalling all
+resource data to/from a subprocess for each plugin
+run.  The Go plugin API assures a certain level of
+consistency to avoid confusing downstream
+transformers.
+
+Go plugins work as described in the [plugin
+package], but fall short of common notions
+associated with the word _plugin_.
+
+## The skew problem
+
+Go plugin compilation creates an [ELF] formatted
+`.so` file, which by definition has no information
+about the provenance of the object code.
+
+Skew between the compilation conditions (versions
+of package dependencies, `GOOS`, `GOARCH`) of the
+main program ELF and the plugin ELF will cause
+plugin load failure, with non-helpful error
+messages.
+
+Exec plugins also lack provenance, but won't fail
+due to compilation skew.
+
+In either case, the only sensible way to share a
+plugin is as some kind of _bundle_ (a git repo
+URL, a git archive file, a tar file, etc.)
+containing source code, tests and associated data,
+unpackable under
+`$XDG_CONFIG_HOME/kustomize/plugin`.
+
+In the case of a Go plugin, an _end user_
+accepting a shared plugin _must compile both
+kustomize and the plugin_.
+
+This means a one-time run of
+```
+GOPATH=${whatever} GO111MODULE=on go get sigs.k8s.io/kustomize/kustomize/v3
+```
+
+and then a normal development cycle using
+
+```
+go build -buildmode plugin \
+    -o ${wherever}/${kind}.so ${wherever}/${kind}.go
+```
+with paths and the release version tag (e.g. `v3.0.0`)
+adjusted as needed.
+
+For comparison, consider what one
+must do to write a [tensorflow plugin].
+
+## Why support Go plugins?
+
+### Safety
+ 
+The Go plugin developer sees the same API offered
+to native kustomize operations, assuring certain
+semantics, invariants, checks, etc. An exec
+plugin sub-process dealing with this via
+stdin/stdout will have an easier time screwing
+things up for downstream transformers and
+consumers.
+
+Minor point: if the plugin reads files via
+the kustomize-provided file `Loader` interface, it
+will be constrained by kustomize file loading
+restrictions.  Of course, nothing but a code audit
+prevents a Go plugin from importing the `io` package
+and doing whatever it wants.
+
+### Debugging
+
+A Go plugin developer can debug the plugin _in
+situ_, setting breakpoints inside the plugin and
+elsewhere while running a plugin in feature tests.
+
+To get the best of both worlds (shareability and safety),
+a developer can write an `.go` program that functions
+as an _exec plugin_, but can be processed by `go generate`
+to emit a _Go plugin_ (or vice versa).
+
+### Unit of contribution 
+
+All the builtin generators and transformers
+are themselves Go plugins.  This means that
+the kustomize maintainers can promote a contributed
+plugin to a builtin without needing code changes
+(beyond those mandated by normal code review).
+
+### Ecosystems grow through use
+
+Tooling could ease Go plugin _sharing_, but this
+requires some critical mass of Go plugin
+_authoring_, which in turn is hampered by
+confusion around sharing.  [Go modules], once they
+are more widely adopted, will solve the
+biggest plugin sharing difficulty: ambiguous
+plugin vs host dependencies.

docs/plugins/goPluginGuidedExample.md

@@ -0,0 +1,367 @@
+# Go Plugin Guided Example for Linux
+
+[SopsEncodedSecrets repository]: https://github.com/monopole/sopsencodedsecrets
+[Go plugin]: https://golang.org/pkg/plugin
+[Go plugin caveats]: goPluginCaveats.md
+
+This is a (no reading allowed!) 60 second copy/paste guided
+example.
+
+Full plugin docs [here](README.md).
+Be sure to read the [Go plugin caveats].
+
+This demo uses a Go plugin, `SopsEncodedSecrets`,
+that lives in the [sopsencodedsecrets repository].
+This is an inprocess [Go plugin], not an
+sub-process exec plugin that happens to be written
+in Go (which is another option for Go authors).
+
+This is a guide to try it without damaging your
+current setup.
+
+#### requirements
+
+* linux, git, curl, Go 1.12
+
+For encryption
+
+* gpg
+
+Or
+
+* Google cloud (gcloud) install
+* a Google account with KMS permission
+
+## Make a place to work
+
+```shell
+# Keeping these separate to avoid cluttering the DEMO dir.
+DEMO=$(mktemp -d)
+tmpGoPath=$(mktemp -d)
+```
+
+## Install kustomize
+
+Need v3.0.0 for what follows, and you must _compile_
+it (not download the binary from the release page):
+
+```shell
+GOPATH=$tmpGoPath go install sigs.k8s.io/kustomize/v3/cmd/kustomize
+```
+
+## Make a home for plugins
+
+A kustomize plugin is fully determined by
+its configuration file and source code.
+
+[required fields]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
+
+Kustomize plugin configuration files are formatted
+as kubernetes resource objects, meaning
+`apiVersion`, `kind` and `metadata` are [required
+fields] in these config files.
+
+The kustomize program reads the config file
+(because the config file name appears in the
+`generators` or `transformers` field in the
+kustomization file), then locates the Go plugin's
+object code at the following location:
+
+> ```shell
+> $XDG_CONFIG_HOME/kustomize/plugin/$apiVersion/$lKind/$kind.so
+> ```
+
+where `lKind` holds the lowercased kind.  The
+plugin is then loaded and fed its config, and the
+plugin's output becomes part of the overall
+`kustomize build` process.
+
+The same plugin might be used multiple times in
+one kustomize build, but with different config
+files.  Also, kustomize might customize config
+data before sending it to the plugin, for whatever
+reason.  For these reasons, kustomize owns the
+mapping between plugins and config data; it's not
+left to plugins to find their own config.
+
+This demo will house the plugin it uses at the
+ephemeral directory
+
+```shell
+PLUGIN_ROOT=$DEMO/kustomize/plugin
+```
+
+and ephemerally set `XDG_CONFIG_HOME` on a command
+line below.
+
+### What apiVersion and kind?
+
+At this stage in the development of kustomize
+plugins, plugin code doesn't know or care what
+`apiVersion` or `kind` appears in the config file
+sent to it.
+
+The plugin could check these fields, but it's the
+remaining fields that provide actual configuration
+data, and at this point the successful parsing of
+these other fields are the only thing that matters
+to a plugin.
+
+This demo uses a plugin called _SopsEncodedSecrets_,
+and it lives in the [SopsEncodedSecrets repository].
+
+Somewhat arbitrarily, we'll chose to install
+this plugin with
+
+```shell
+apiVersion=mygenerators
+kind=SopsEncodedSecrets
+```
+
+### Define the plugin's home dir
+
+By convention, the ultimate home of the plugin
+code and supplemental data, tests, documentation,
+etc. is the lowercase form of its kind.
+
+```shell
+lKind=$(echo $kind | awk '{print tolower($0)}')
+```
+
+### Download the SopsEncodedSecrets plugin
+
+In this case, the repo name matches the lowercase
+kind already, so we just clone the repo and get
+the proper directory name automatically:
+
+```shell
+mkdir -p $PLUGIN_ROOT/${apiVersion}
+cd $PLUGIN_ROOT/${apiVersion}
+git clone git@github.com:monopole/sopsencodedsecrets.git
+```
+
+Remember this directory:
+
+```shell
+MY_PLUGIN_DIR=$PLUGIN_ROOT/${apiVersion}/${lKind}
+```
+
+### Try the plugin's own test
+
+Plugins may come with their own tests.
+This one does, and it hopefully passes:
+
+```shell
+cd $MY_PLUGIN_DIR
+go test SopsEncodedSecrets_test.go
+```
+
+Build the object code for use by kustomize:
+
+```shell
+cd $MY_PLUGIN_DIR
+GOPATH=$tmpGoPath go build -buildmode plugin -o ${kind}.so ${kind}.go
+```
+
+This step may succeed, but kustomize might
+ultimately fail to load the plugin because of
+dependency [skew].
+
+[skew]: https://github.com/kubernetes-sigs/kustomize/blob/master/docs/plugins/README.md#caveats
+[used in this demo]: #install-kustomize
+
+On load failure
+
+ * be sure to build the plugin with the same
+   version of Go (_go1.12_) on the same `$GOOS`
+   (_linux_) and `$GOARCH` (_amd64_) used to build
+   the kustomize being [used in this demo].
+
+ * change the plugin's dependencies in its `go.mod`
+   to match the versions used by kustomize (check
+   kustomize's `go.mod` used in its tagged commit).
+
+Lacking tools and metadata to allow this to be
+automated, there won't be a Go plugin ecosystem.
+
+Kustomize has adopted a Go plugin architecture as
+to ease accept new generators and transformers
+(just write a plugin), and to be sure that native
+operations (also constructed and tested as
+plugins) are compartmentalized, orderable and
+reusable instead of bizarrely woven throughout the
+code as a individual special cases.
+
+## Create a kustomization
+
+Make a kustomization directory to
+hold all your config:
+
+```shell
+MYAPP=$DEMO/myapp
+mkdir -p $MYAPP
+```
+
+Make a config file for the SopsEncodedSecrets plugin.
+
+Its `apiVersion` and `kind` allow the plugin to be
+found:
+
+```shell
+cat <<EOF >$MYAPP/secGenerator.yaml
+apiVersion: ${apiVersion}
+kind: ${kind}
+metadata:
+  name: mySecretGenerator
+name: forbiddenValues
+namespace: production
+file: myEncryptedData.yaml
+keys:
+- ROCKET
+- CAR
+EOF
+```
+
+This plugin expects to find more data in
+`myEncryptedData.yaml`; we'll get to that shortly.
+
+Make a kustomization file referencing the plugin
+config:
+
+```shell
+cat <<EOF >$MYAPP/kustomization.yaml
+commonLabels:
+  app: hello
+generators:
+- secGenerator.yaml
+EOF
+```
+
+Now generate the real encrypted data.
+
+### Assure you have an encryption tool installed
+
+We're going to use [sops](https://github.com/mozilla/sops) to encode a file. Choose either GPG or Google Cloud KMS as the secret provider to continue.
+
+#### GPG
+
+Try this:
+
+```shell
+gpg --list-keys
+```
+
+If it returns a list, presumably you've already created keys. If not, try import test keys from sops for dev.
+
+```shell
+curl https://raw.githubusercontent.com/mozilla/sops/master/pgp/sops_functional_tests_key.asc | gpg --import
+SOPS_PGP_FP="1022470DE3F0BC54BC6AB62DE05550BC07FB1A0A"
+```
+
+#### Google Cloude KMS
+
+Try this:
+
+```shell
+gcloud kms keys list --location global --keyring sops
+```
+
+If it succeeds, presumably you've already created keys and placed them in a keyring called sops. If not, do this:
+
+```shell
+gcloud kms keyrings create sops --location global
+gcloud kms keys create sops-key --location global \
+    --keyring sops --purpose encryption
+```
+
+Extract your keyLocation for use below:
+
+```shell
+keyLocation=$(\
+    gcloud kms keys list --location global --keyring sops |\
+    grep GOOGLE | cut -d " " -f1)
+echo $keyLocation
+```
+
+### Install `sops`
+
+```shell
+GOPATH=$tmpGoPath go install go.mozilla.org/sops/cmd/sops
+```
+
+### Create data encrypted with your private key
+
+Create raw data to encrypt:
+
+```shell
+cat <<EOF >$MYAPP/myClearData.yaml
+VEGETABLE: carrot
+ROCKET: saturn-v
+FRUIT: apple
+CAR: dymaxion
+EOF
+```
+
+Encrypt the data into file the plugin wants to read:
+
+With PGP
+
+```shell
+$tmpGoPath/bin/sops --encrypt \
+  --pgp $SOPS_PGP_FP \
+  $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml
+```
+
+Or GCP KMS
+
+```shell
+$tmpGoPath/bin/sops --encrypt \
+  --gcp-kms $keyLocation \
+  $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml
+```
+
+Review the files
+
+```shell
+tree $DEMO
+```
+
+This should look something like:
+
+> ```shell
+> /tmp/tmp.0kIE9VclPt
+> ├── kustomize
+> │   └── plugin
+> │       └── mygenerators
+> │           └── sopsencodedsecrets
+> │               ├── go.mod
+> │               ├── go.sum
+> │               ├── LICENSE
+> │               ├── README.md
+> │               ├── SopsEncodedSecrets.go
+> │               ├── SopsEncodedSecrets.so
+> │               └── SopsEncodedSecrets_test.go
+> └── myapp
+>     ├── kustomization.yaml
+>     ├── myClearData.yaml
+>     ├── myEncryptedData.yaml
+>     └── secGenerator.yaml
+> ```
+
+## Build your app, using the plugin:
+
+```shell
+XDG_CONFIG_HOME=$DEMO $tmpGoPath/bin/kustomize build --enable_alpha_plugins $MYAPP
+```
+
+This should emit a kubernetes secret, with
+encrypted data for the names `ROCKET` and `CAR`.
+
+Above, if you had set
+
+> ```shell
+> PLUGIN_ROOT=$HOME/.config/kustomize/plugin
+> ```
+
+there would be no need to use `XDG_CONFIG_HOME` in the
+_kustomize_ command above.

docs/v1.0.1.md

@@ -0,0 +1,18 @@
+# kustomize 1.0.1
+
+Initial release after move from
+[github.com/kubernetes/kubectl]
+to [github.com/kubernetes-sigs/kustomize].
+
+History
+
+ * May 2018: v1.0 after move to [github.com/kubernetes-sigs/kubectl]
+             from [github.com/kubernetes/kubectl].
+             Has kustomization file, bases, overlays, basic transforms.
+ * Apr 2018: s/kinflate/kustomize/, s/manifest/kustomization/
+ * Oct 2017: s/kexpand/kinflate/
+ * Sep 2017: kexpand [starts](https://github.com/kubernetes/kubectl/pull/65)
+             in [github.com/kubernetes/kubectl]
+ * Aug 2017: [DAM] authored by Brian Grant
+
+[DAM]: https://docs.google.com/document/d/1cLPGweVEYrVqQvBLJg6sxV-TrE5Rm2MNOBA_cxZP2WU

docs/v2.0.0.md

@@ -0,0 +1,131 @@
+# kustomize 2.0.0
+
+[security concern]: https://docs.google.com/document/d/1FYgLVdq-siB_Cef9yuQBmit0PbrE8lsyTBdGI2eA2y8/edit
+
+After security review, a field used in secret
+generation (see below) was removed from the
+definition of a kustomization file with no
+mechanism to convert it to a new form.  Also, the
+set of files accessible from a kustomization file
+has been further constrained.
+
+Per the [versioning policy](versioningPolicy.md),
+backward incompatible changes trigger an increment
+of the major version number, hence we go
+from 1.0.11 to 2.0.0. We're taking this major
+version increment opportunity to remove some
+already deprecated fields, and the code paths
+associated with them.
+
+## Backward Incompatible Changes
+
+### Kustomization Path Constraints
+
+A kustomization file can specify paths to other
+files, including resources, patches, configmap
+generation data, secret generation data and
+bases. In the case of a base, the path can be a
+git URL instead.
+
+In 1.x, these paths had to be relative to the
+current kustomization directory (the location of
+the kustomization file used in the `build`
+command).
+
+In 2.0, bases can continue to specify, via
+relative paths, kustomizations outside the current
+kustomization directory.  But non-base paths are
+constrained to terminate in or below the current
+kustomization directory. Further, bases specified
+via a git URL may not reference files outside of
+the directory used to clone the repository.
+
+### Kustomization Field Removals
+
+#### patches
+
+`patches` was deprecated and replaced by
+`patchesStrategicMerge` when `patchesJson6902` was
+introduced.  In Kustomize 2.0.0, `patches` is
+removed. Please use `patchesStrategicMerge`
+instead.
+
+#### imageTags
+
+`imageTags` is replaced by `images` since `images`
+can provide more features to change image names,
+registries, tags and digests.
+
+#### secretGenerator/commands
+
+`commands` is removed from SecretGenerator due to
+a [security concern]. One can use `files` or
+`literals`, similar to ConfigMapGenerator, to
+generate a secret.
+
+```
+secretGenerator:
+- name: app-tls
+  files:
+    - secret/tls.cert
+    - secret/tls.key
+  type: "kubernetes.io/tls"
+```
+
+## Compatible Changes (New Features)
+
+As this release is triggered by a security change,
+there are no major new features to announce. A few
+things that are worth mentioning in this release
+are:
+
+* More than _40_ issues closed since 1.0.11
+  release (including many extensions to
+  transformation rules).
+
+* Users can run `kustomize edit fix` to migrate a
+  kustomization file working with previous
+  versions to one working with 2.0.0. For example,
+  a kustomization.yaml with following content
+
+  ```
+  patches:
+    - deployment-patch.yaml
+  imageTags:
+    - name: postgres
+      newTag: v1
+  ```
+
+  will be converted to
+
+  ```
+  apiVersion: kustomize.config.k8s.io/v1beta1
+  kind: Kustomization
+  patchesStrategicMerge:
+    - deployment-patch.yaml
+  images:
+    - name: postgres
+      newTag: v1
+  ```
+
+* Kustomization filename
+
+  In previous versions, the name of a
+  kustomization file had to be
+  `kustomization.yaml`.
+  Kustomize allows `kustomization.yaml`,
+  `kustomization.yml` and
+  `Kustomization`. In a directory, only one of
+  those filenames is allowed. If there are more
+  than one found, Kustomize will exit with an
+  error. Please select the best filename for your
+  use cases.
+
+* Cancelled plans to deprecate applying prefix/suffix to namespace.
+  The deprecation warning
+
+  ```
+  Adding nameprefix and namesuffix to Namespace resource will be deprecated in next release.
+  ```
+
+  was removed.

docs/v2.1.0.md

@@ -0,0 +1,243 @@
+# kustomize 2.1.0
+
+[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
+[imgSorted]: images/sorted.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
+[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
+
+Go modules, resource ordering respected, generator and transformer plugins, eased
+loading restrictions, the notion of inventory, eased replica count modification.
+About ~90 issues closed since [v2.0.3] in ~400 commits.
+
+Download [here][v2.1.0].
+
+## Go modules
+
+![gopher with boxes][imgModules]
+
+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).
+
+## Resource ordering
+
+![sort order retained][imgSorted]
+
+Kustomize now retains the depth-first order of
+resources as read, a frequently requested
+feature.
+
+This means resource order can be controlled
+by editting kustomization files.  This is
+also vital to applying user-defined
+transformations (plugins) in a particular
+order.
+
+Nothing needs to be done to activate this;
+it happens automatically.
+
+The `build` command now accepts a `--reorder`
+flag with values `legacy` and `none`,
+with a default value of `legacy`.
+
+`legacy` means apply an ordering based on
+GVK, that currently emits `Namespace` objects
+first, and `ValidatingWebhookConfiguration`
+objects last.  This means that despite
+automatic retention of load order, your
+`build` output won't change by default.
+
+`none` means _don't_ reorder the resources before
+output.  Specify this to see output order
+respect input order.
+
+## 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 an _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 one 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_restrictor 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.
+
+## Inventory generation for pruning
+
+![pruning dead branches][imgPruning]
+
+_Alpha_
+ 
+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].
+
+
+## Field changes / deprecations
+
+###  `resources` expanded, `bases` deprecated
+
+The `resources` field has been generalized; it now
+accepts what formerly could only be specified in
+the `bases` field.
+
+This change was made to allow users fine control
+over resource processing order.  With a distinct
+`bases` field, bases had to be loaded separately
+from resources as a group.  Now, base loading may
+be interleaved as desired with the loading of
+resource files from the current
+directory. [Resource ordering](#resource-ordering)
+had to be respected before this feature could be
+introduced.
+
+The `bases` field is now deprecated, and will be
+deleted in some future major release.  Manage the
+deprecation simply moving the arguments of the
+`bases` field to the `resources` field in the
+desired order, e.g.
+
+> ```
+> resources:
+> - someResouceFile.yaml
+> - someOtherResourceFile.yaml
+> bases:
+> - ../../someBaseDir
+> ```
+
+could become
+
+> ```
+> resources:
+> - someResouceFile.yaml
+> - ../../someBaseDir
+> - someOtherResourceFile.yaml
+> ```
+
+The `kustomized edit fix` command will do this for
+you, though it will always put the bases at the
+end.
+
+As an aside, the `resources`, `generators` and
+`transformers` fields now 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 path or URL
+> pointing to a directory with a kustomization
+> file).  A kustomization directory used in this
+> context is called a [_base_].
+
+The fact that the `generators` and `transformers`
+field accept [bases] and the fact that generator
+and transformer configuration objects are just
+normal k8s resources means that one can generate
+or transform a generator or a transformer (see
+[TestTransformerTransformers]).
+
+[TestTransformerTransformers]: ../pkg/target/transformerplugin_test.go
+
+### `replicas` field
+
+The common task of patching a deployment to edit
+the number of replicas is now made easier
+with the new [replicas](fields.md#replicas) field. 
+
+### `envs` field
+
+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 use `kustomize edit fix` to merge
+singular `env` field into a plural field.

docs/v2.1.0_changelog.md

@@ -0,0 +1,242 @@
+
+e1b59c93 2.1 release notes
+2cf8371a Add --force flag to modify annotations and labels
+0fa2d9c3 Add --reorder flag.
+2d70526e Add ConfigMapGenerator and test.
+4df57686 Add SedTransformerTest
+68f6b0be Add Webhookconfiguration in default name references
+1545e07d Add a plugin loader test.
+449175e3 Add a sorting plugin.
+aafc23a6 Add annotation transformer.
+9bd456c6 Add bug report page.
+0df58838 Add builtin JSON patch transformer
+621bb7c6 Add builtin NameTransformer plugin.
+45901219 Add builtin label transformer.
+79906d73 Add builtin namespace transformer plugin
+d9b0c4c8 Add copy method to VarSet
+798b61c8 Add copy method to VarSet
+d9259397 Add documentation for the replicas transform
+2744e058 Add entry for inventory in fields.md
+3f2acc90 Add faq
+99391157 Add goplugin KV generator example.
+3b8c5ee9 Add load_restrictor flag.
+8f413f52 Add name reference of storageClass
+5e054c9d Add originalName field to resource.
+bb9b3163 Add script to run cloud build 'locally'.
+ffc16d51 Add secret generator.
+755dd3d0 Add some utilities.
+c9d903cc Add support for escaping characters in Doc
+2825888f Add test for builtin secretgenerator plugin.
+e6c1b141 Add test for transformers/image custom config
+644dc4b9 Add test showing shared patches disallowed.
+96707645 Add test showing shared patches disallowed.
+8d9897d5 Add the rmBuilder test helper.
+000f81b2 Added test to verify usage of multiline strip chomp in configMapGenerator
+5e7ddc86 Adds precommit for windows + documentation
+5e33ac4a Allow nil label and annotaion
+f38d0c69 Apply LimitRange resources before workloads
+b28aaae6 Break a bad dep.
+76d370a8 Chart last mile example
+f621543d Cleanup kusttarget.
+16fe7ced Cleanup plugin builds.
+d4842ebd Cleanup the replica plugin implementation.
+8991bcb3 Collect existing internal pkgs under one roof.
+d0cf0473 Convert image transformer test to a more readable format
+81c98c85 Convert inventory transformer to plugin, reduce k8sdeps.
+c9a5c03e Convert legacy file based test to in-memory
+2e71a3b8 Convert plugins to accept bytes instead of unstruct.
+52faa01e Cover #1155 with a test.
+fe67bcdb Cut more ties to k8sdeps
+e1389649 Cut more ties to k8sdeps
+175c754f Define a plugin compiler.
+9a850710 Delete kustomizationerror.
+6a106546 Delete the KV plugin code.
+9a4cb6c9 Delete unused code.
+cc531af6 Deprecate 'bases:' field.
+939de0cd Dogfood the plugin framework.
+267eec55 Fix 918
+3a44508d Fix error message
+0f571b91 Fix field names
+9a4692e6 Fix function comments based on best practices from Effective Go
+e207ae4c Fix incorrect default varrefs for CronJob volumeMounts
+3d0e2907 Fix markdownlint warnings
+31091a8d Fix missing varrefs for CronJob, Job, ReplicaSet
+cefb64b6 Fix path
+a9145702 Fix some comment nits.
+7295a9b3 Fix some nits.
+b92ee256 Fix some nits.
+57eecd74 Fix test broken by the change in ordering.
+e079c20c Fix typo
+559efd64 Fix typo in namereference path for cronjobs initContainers.
+a7a2589e Fix yaml in generator examples.
+9b6f8f0c Format generated code.
+2545ea10 Helm chart generator exec plugin
+02f37953 Idiom fixes.
+5000a2e5 Implement replica transformer as patch alternative
+9c36ac28 Improve comments in name transform code.
+58d9a510 Improve plugin doc.
+529db049 Introduce envs field.
+6d309b52 Introduce stacked transformers.
+abf538d8 Keep backward compatibility for image transformer
+7e12918f Keep var refernce in resources
+7130e3ff Leave defautconfig empty for images
+3e85c458 Load default config for image transformer
+4162dbc2 Maintain resources in order loaded.
+3a7c8a03 Make builtin the default pluginType
+bcc7412e Make kusttestharness shareable.
+cfb0c5ef Make plugin dir match Go conventions.
+8d4b6452 Make the replica transformer `kind` aware.
+3f8b1fe0 Make the replica transformer `kind` aware.
+c470982c Make transformer configs array-aware
+cd19d426 Merge remote-tracking branch 'upstream/master'
+0b555e1b Modify tests to present expected data in unsorted order.
+f17698a8 More release note tweaks.
+9a12b551 Move accumulator code to its own package.
+ee728d58 Move hashing code out of k8sdeps.
+fd2248e7 Move hashing transformer out of k8sdeps.
+d2c93065 Move kustomize main to cmd directory.
+4bc31f4b Move pluginator to cmd directory.
+5653ae69 One plugin per dir.
+a09b42b3 Order ValidatingWebhookConfig last.
+c63ebbdf Preserve order when merging.
+11bb176a Push suffix/prefix code to plugin.
+103c1b3a Put goplugins behind flag.
+2796e545 Put windows test script next to pre-commit.sh
+47c96548 Reduce k8ds deps
+4f429d6b Reduce time required for cloning remote bases
+b67d713b Remove dependency on ghodss/yaml
+78cdff6d Remove kv plugins from docs.
+3c58c9d1 Remove local load restrictions.
+8767495b Remove some duped code.
+b32e041b Remove some duped code.
+8c133ef0 Removes mdrip testing for Windows
+a2e4f6cf Rename ./bin dir to ./travis.
+0e4f9acb Rename ErrorIfNotEqual to ErrorIfNotEqualSets
+49d94f53 Rename the prefix/suffix transformer.
+c06b9507 Secret/configmap factory cleanup.
+3a01a63a Simplify code base.
+76a31798 Simplify plugin loader code.
+3a85fcd3 Simplify some of the plugin testing code.
+3011f180 Sort default varReference config by kind, path
+44ac9a9f Standalone ChartInflator plugin test.
+5614649d Standalone service generator test
+f311ba8d Support custom config for image transformer
+e191ff53 Switch to vgo
+a5660415 Tell homebrew to update.
+ed03818e This commit enhances the UnstructAdapter
+e0d2fa57 Translated kustomization.yaml into markdown in fields.md. Updated links to point to fields.md
+a352ff39 True and false are mysterious.
+7971ac1c Tweak secret docs.
+852e7ed5 Typo Fix
+1dd448e6 Update 2.1 release notes before release.
+0f50be87 Update ChartInflatorExec
+72fd31fd Update FAQ.md
+185ae510 Update README.md
+fa4dc14c Update all.go
+ae0510f6 Update chartinflatorexecplugin_test.go
+08b6f6f4 Update golinter to 1.17.1
+4502e8ff Update inventory_object.md
+ca478016 Update minecraft version in example.
+efcf8757 Update order of resources to include psps
+64bd0692 Update plugins.md
+0045d7b7 Update plugins.md
+54d1c557 Update plugins.md
+86534869 Update remoteBuild.md
+2ec8189c Update remoteBuild.md
+1afc6c77 Update strategic-merge link
+c1dea667 Update travis file.
+9edecffc Update v_2.1.0.md
+f2295acf Update v_2.1.0.md
+71f44d64 Update v_2.1.0.md
+bb69e9e7 Updates documentation for support and source
+2490e605 Updates in image transformer (#911)
+c6476d16 Upgrade version of minecraft used in tests.
+af2b101f Use go modules in cloud builder.
+5be42092 Vars should expand in ingress/spec/tls/secretName
+9203478a Write individual files to output path if it is a directory
+942e36e1 a few more changes
+5b18c4de add ItemId type
+6f4b104c add admission webhook types in the default cluster-scoped resource list
+9fc4d388 add builtin envfiles plugin
+a8465c95 add builtin files plugin
+388d5c2d add builtin plugins
+7fa02ce5 add document to explain inventory field (#997)
+142879ec add example for transformer plugin
+74937321 add generator plugins
+deaf0779 add generators/transformers fields in kusotmization.yaml
+ba43ecbc add goplugin for exec generators and transformers
+d5abe39d add inventory package and refactor inventory transformer
+f7cd44be add job initcontainer to varreference config
+53a22cbe add note for availability in kubectl
+2675bf4b add older release notes
+ca6228b5 add remove resource subcommand
+18f63282 add secret and configmap generator plugins
+f6e01cfd add support for exec plugins
+dd59eb38 add test case
+c724cb71 add test for empty patch file
+445f7392 add test for ensuirng the loader root is correctly passed
+a8c476f7 add the Chhinese translation of docs list & install (#1022)
+fb9e00bf add the unstructured to ENV of exec plugins
+4f1a2350 add transformer plugins
+237c54f4 add tutorial for custom images transformer
+b4dbac1b add validation transformer
+89243aed add zh dir
+b07bea40 added field tables
+3168b2a1 added link to examples
+7a54d998 added links to section headings
+e9a3f9f5 address comments
+86f0f9a4 address comments
+e5d730e1 address comments
+ad7ca697 address comments
+65886f12 address comments
+1d65f24b adds documentation for choco package
+e4159d94 allow to set image without a tag
+b4fc1e43 change field name: prune -> inventory
+404884e2 chinese helloworld doc
+7b82154c correct spelling, minor word ordering
+ca4aea17 doc/glossary updates for v2.1
+3ff5c793 docs add kubectl command
+c250f75d enable go module in the integration test (#1153)
+3e6ee23a fix README
+70def866 fix a link
+e6d1de0d fix commonLabels spec for volumeClaimTemplates
+4848987a fix configmap/secret name references for cronjobs with projected volumes
+fa552d77 fix help msg for set image cmd
+a64baed4 fix link
+1bd7afe6 fix linter
+822420e4 fix mergeFlags
+bcb697eb fix namespace transformer for cluster-scoped resources
+7765bdd9 fix some doc
+a889f97f fix some example ptrs
+56965a00 fix test
+927b497f fix tests
+61d46c26 fix the boilerplate copyright header (#1064)
+03751372 fix the bug for patching CRDs
+93908602 fix the bug for setting annotations when triggering transformers
+21a0cba4 fix the regression of building remote url (#935)
+7ab4d284 fix translation
+62d3200e fix typo in namereference where serviceaccount name would not resolve
+826affb8 generate configmap for pruning
+cd9572e0 hey
+5c471965 honor XDG_CONFIG_HOME
+2aa7e30a minimize test
+29cbec37 move parse helpers to util
+fc8063f7 pass loader root to exec plugins
+c1e2b27c pass resources to transformer plugin all together
+e287f615 readded kustomization.yaml
+f850ca63 remove extra comment
+e17d3033 reorganize the examples layout
+bfc3655b skip adding namespace when the object is empty
+440d0361 some transformer plugins
+61cf67fb start v2.1 release notes
+403ede78 tests: demonstrate issue with JSON patch when base adds name prefix
+b4efc833 translate example list
+16924d79 translate kustomization.yaml
+faaf6002 translate kustomization.yaml & update zh/README
+540e4023 typo in README
+748c88c2 update PruneString for resources
+b60fca05 update edit add secrets/configmaps to use plugins
+c836de5c update error msg
+e4956c55 update examples/README.md
+b2c87522 update validation transformer example text
+d2103dbf updated grouping and added brief descriptions of sections

docs/v3.0.0.md

@@ -0,0 +1,69 @@
+# kustomize 3.0.0
+
+This release is basically [v2.1.0](v2.1.0.md),
+with many post-v2.1.0 bugs fixed (in about 150
+commits) and a `v3` in Go package paths.
+
+[plugin]: https://github.com/kubernetes-sigs/kustomize/tree/master/docs/plugins
+
+The major version increment to `v3` puts a new
+floor on a stable API for [plugin] developers
+(both _Go_ plugin developers and _exec_ plugin
+developers who happen to use Go).
+
+### Why so soon after v2.1.0?
+
+[semantic versioning]: https://semver.org
+[Go modules doc]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher
+[versioning policy]: versioningPolicy.md
+
+We made a mistake - v2.1.0 should have been
+v3.0.0.  Per the [Go modules doc] (which have
+improved a great deal recently), a release that's
+already tagged v2 or higher should increment the
+major version when performing their first Go
+module-based release.
+
+This advice applies to kustomize, since it was
+already at major version 2 when it began using Go
+modules to state _its own_ dependencies in v2.1.0.
+
+But the more important reason for `v3` is a change
+to the kustomize [versioning policy], forced by
+the introduction of plugins.
+
+Historically, kustomize's [versioning policy]
+didn't involve Go modules and addressed _only_ the
+command line tool's behavior and the fields in a
+kustomization file.  The underlying packages were
+an implementation detail, not under semantic
+versioning, because they weren't intended for
+export (and should have all been under
+`internal`).  Thus although the v2.1.0 CLI is
+backward compatible with v2.0.3, the underlying
+package APIs are not.
+
+[minimal version selection]: https://research.swtch.com/vgo-mvs
+
+With Go modules, the `go` tool must assume that Go
+packages respect [semantic versioning], so it can
+perform [minimal version selection].
+
+With the introduction of alpha plugins, kustomize
+sub-packages - in particular `loader` and
+`resmap` - become part of an API formally exposed
+to plugin authors, and so must be semantically
+versioned.  This allows plugins defined in other
+repositories to clarify that they depend on
+kustomize v3.0.0, and not see confusing errors
+arising from incompatibilities between v2.1.0 and
+v2.0.3.  Hence, the jump to v3.
+
+Aside - the set of kustomize packages outside
+`internal` is too large, and over time, informed
+by package use, this API surface must shrink.
+Such shrinkage will trigger a major version
+increment.
+
+
+

docs/v3.1.0.md

@@ -0,0 +1,127 @@
+# kustomize 3.1.0
+
+
+## Extended patches
+Since this version, Kustomize allows applying one patch to multiple resources. This works for both Strategic Merge Patch and JSON Patch. Take a look at [patch multiple objects](../examples/patchMultipleObjects.md).
+
+## Improved Resource Matching
+
+Multiple improvements have been made to allow the user to leverage "namespace"
+instead/or with "name suffix/prefix" to segregate resources.
+
+### Patch resolution improvement
+
+The following example demonstrates how using the namespace field in the patch definition,
+will let the user define two different patches against two different Deployment having the
+same "deploy1" name but in different namespaces in the same Kustomize context/folder.
+Unless the `namespace:` field has been specified in the kustomization.yaml, no namespace
+value will be handled as Kubernetes `default` namespace.
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy1
+  namespace: main
+spec:
+  template:
+    spec:
+      containers:
+      - name: nginx
+        env:
+        - name: ANOTHERENV
+          value: TESTVALUE
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy1
+  namespace: production
+spec:
+  template:
+    spec:
+      containers:
+      - name: main
+        env:
+        - name: ANOTHERENV
+          value: PRODVALUE
+```
+
+
+### Variable resolution improvement
+
+It is possible to add namespace field to the variable declaration. In the following example,
+two `Service` objects with the same `elasticsearch` name have been declared.
+Specifying the namespace in the objRef of the corresponding varriables, allows Kustomize to
+resovlve thoses variables.
+If the namespace is not specified, Kustomize will handle it has a "wildcard" value.
+
+Extract of kustomization.yaml:
+
+```yaml
+vars:
+- name: elasticsearch-test-protocol
+  objref:
+    kind: Service
+    name: elasticsearch
+    namespace: test
+    apiVersion: v1
+  fieldref:
+    fieldpath: spec.ports[0].protocol
+- name: elasticsearch-dev-protocol
+  objref:
+    kind: Service
+    name: elasticsearch
+    namespace: dev
+    apiVersion: v1
+  fieldref:
+    fieldpath: spec.ports[0].protocol
+
+```
+
+### Simultaneous change of names and namespaces
+
+Kustomize is now able to deal with simultaneous changes of name and namespace.
+Special attention has been paid the handling of: 
+- ClusterRoleBinding/RoleBinding "subjects" field,
+- ValidatingWebhookConfiguration "webhooks" field.
+
+The user should be able to use a kustomization.yaml as shown in the example bellow
+even if ClusterRoleBind,RoleBinding and ValidatingWebookConfiguration are part of the
+resources he needs to declare.
+
+Extract of kustomization.yaml:
+
+```yaml
+namePrefix: pfx-
+nameSuffix: -sfx
+namespace: testnamespace
+
+resources:
+...
+```
+
+### Resource and Kustomize Context matching.
+
+Kustomize is now able to support more aggregation patterns.
+
+If for instance, the top level of kustomization.yaml, is simply
+combining sub-components, (as in the following example), Kustomize has improved
+resource matching capabilities. This removes some of the constraints which were
+present on the utilization of prefix/suffix and namespace transformers in the
+individual components.
+
+```yaml
+resources:
+- ../component1
+- ../component2
+- ../component3
+```
+
+## Other improvements
+
+- Image transformation has been improved. This allows the user to update the sha256 of
+  an image with another sha256.
+- Multiple default transformer configuration entries have been added, removing the need for the
+  user to add them as part of the `configurations:` section of the kustomization.yaml.
+- `kustomize` help command has been tidied up.

docs/v3.2.0.md

@@ -0,0 +1,29 @@
+# kustomize 3.2.0
+
+
+## Inline Patch
+Since this version, Kustomize allows inline patches in all three of `patchesStrategicMerge`, `patchesJson6902` and `patches`. Take a look at [inline patch](../examples/inlinePatch.md).
+
+## New Subcommand
+
+Since this version, one can create a kustomization.yaml file in a directory through a `create` subcommand.
+
+Create a new overlay from the base ../base
+```
+kustomize create --resources ../base
+```
+
+Create a new kustomization detecing resources in the current directory
+```
+kustomize create --autodetect
+```
+
+Once can also add all resources in the current directory recursively by
+
+```
+kustomize create --autodetect --recursive
+```
+
+### New Example Generator
+A new example generator of using go-getter to download resources is added. Take a look at [go-getter generator](../examples/goGetterGeneratorPlugin.md).
+

docs/v3.2.1.md

@@ -0,0 +1,13 @@
+# kustomize 3.2.1
+
+This is a patch release, with no new features from 3.2.0.
+
+It reflects a change in dependence.
+
+The kustomize binary is now built as a client, with no special
+consideration, of the set of public packages represented by the Go
+module at [https://github.com/kubernetes-sigs/kustomize].
+
+kustomize the binary is now a client of the kustomize API
+represented by the public package surface presented by
+`https://github.com/kubernetes-sigs/kustomize/v{whatever}`

docs/version2.0.0.md

@@ -1,70 +0,0 @@
-# Kustomize 2.0.0
-
-After security review, a field used in secret generation (see below) was removed from the definition of a kustomization file with no mechanism to convert it to a new form. Also, the set of files accessible from a kustomization file has been further constrained.
-
-Per the [versioning policy](versioningPolicy.md), backward incompatible changes trigger an increment of the major version number, hence we go from 1.0.11 to 2.0.0. We're taking this major version increment opportunity to remove some already deprecated fields, and the code paths associated with them.
-
-## Backward Incompatible Changes
-
-### Kustomization Path Constraints
-A kustomization file can specify paths to other files, including resources, patches, configmap generation data, secret generation data and bases. In the case of a base, the path can be a git URL instead.
-
-In 1.x, these paths had to be relative to the current kustomization directory (the location of the kustomization file used in the `build` command).
-
-In 2.0, bases can continue to specify, via relative paths, kustomizations outside the current kustomization directory.
-But non-base paths are constrained to terminate in or below the current kustomization directory. Further, bases specified via a git URL may not reference files outside of the directory used to clone the repository.
-
-### Kustomization Field Removals
-
-#### patches
-`patches` was deprecated and replaced by `patchesStrategicMerge` when `patchesJson6902` was introduced.
-In Kustomize 2.0.0, `patches` is removed. Please use `patchesStrategicMerge` instead.
-
-#### imageTags
-`imageTags` is replaced by `images` since `images` can provide more features to change image names, registries, tags and digests.
-
-#### secretGenerator/commands
-`commands` is removed from SecretGenerator due to [security concern](https://docs.google.com/document/d/1FYgLVdq-siB_Cef9yuQBmit0PbrE8lsyTBdGI2eA2y8/edit). One can use `files` or `literals`, similar to ConfigMapGenerator, to generate a secret.
-```
-secretGenerator:
-- name: app-tls
-  files:
-    - secret/tls.cert
-    - secret/tls.key
-  type: "kubernetes.io/tls"
-```
-
-## Compatible Changes (New Features)
-As this release is triggered by a security change,
-there are no major new features to announce. A few things that are worth mentioning in this release are:
-
-* More than _40_ issues closed since 1.0.11 release (including many extensions to transformation rules).
-* Users can run `kustomize edit fix` to migrate a kustomization file working with previous versions to one working with 2.0.0. For example, a kustomization.yaml with following content
-  ```
-  patches:
-    - deployment-patch.yaml
-  imageTags:
-    - name: postgres
-      newTag: v1
-  ```
-  
-  will be converted to
-  
-  ```
-  apiVersion: kustomize.config.k8s.io/v1beta1
-  kind: Kustomization
-  patchesStrategicMerge:
-    - deployment-patch.yaml
-  images:
-    - name: postgres
-      newTag: v1
-  ```
-
-* Kustomization filename
-
-  In previous versions, the canonical name of a kustomization file is `kustomization.yaml`. Kustomize 2.0.0 is extended to recognize more file names: `kustomization.yaml`, `kustomization.yml` and `Kustomization`. In a directory, only one of those filenames is allowed. If there are more than one found, Kustomize will exit with an error. Please select the best filename for your use cases.
-* No longer planning to deprecate namespace prefix/suffix. The deprecation warning
-   ```
-   Adding nameprefix and namesuffix to Namespace resource will be deprecated in next release.
-   ```
-    is removed. Since changing this behavior will break many users' workflow. Kustomize will continue with adding nameprefix and namesuffix to Namespace resources.

docs/versioningPolicy.md

@@ -1,47 +1,151 @@
 # Versioning
 
 Running `kustomize` means one is running a
-particular version of a program, reading a
-particular version of a [kustomization] file.
+particular version of a program (a CLI), using a
+particular version of underlying packages (a Go
+API), and reading a particular version of a
+[kustomization] file.
 
-## Program Versioning
+## CLI Program Versioning
 
 The command `kustomize version` prints a three
-field version tag (e.g. `1.0.11`) that aspires to
+field version tag (e.g. `v3.0.0`) that aspires to
 [semantic versioning].
 
-When enough changes have accumulated to
-warrant a new release, a [release process]
-is followed, and the fields in the version
-number are bumped per semver.
+This notion of semver applies only to the CLI.
+
+The major version changes when some backward
+incompatibility appears in how the commands
+behave.
+
+
+### Installation
+
+The best method to install kustomize is to
+download a binary from the [release page].
+
+If you want to try minor and patch upgrades in
+dependencies via `go get -u` (see `help go
+get`), try something like this:
+
+```
+GO111MODULE=on go get -u sigs.k8s.io/kustomize/kustomize/v3@v3.2.1
+```
+
+## Go API Versioning
+
+The public methods in the public packages
+of module `sigs.k8s.io/kusomize` constitue
+the _kustomize Go API_.
+
+#### Version v3 and earlier
+
+
+[import path]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher
+
+In `v3` (and preceeding major versions), the
+kustomize program and the API live the same Go
+module at `sigs.k8s.io/kustomize`, at [import path]
+`sigs.k8s.io/kustomize/v3`.
+
+This has been fine for the CLI, but it presents a
+problem for the Go API.
+
+[minimal version selection]: https://research.swtch.com/vgo-mvs
+
+The process around Go modules, in particular the
+notion of [minimal version selection], demands
+that the module respect semver.
+
+Almost all the code in module
+`sigs.k8s.io/kustomize/v3` is exposed (not in a
+directory named `internal`).  Even a minor
+refactor changing a method name or argument type
+in some deeply buried (but still public) method is
+a backward incompatible change.  As a result, Go
+API semver hasn't been followed (or we'd be at a much
+higher version number by now).
+
+Some options are
+
+- continue to ignore Go API semver and stick to
+  CLI semver (eliminating the usefullness of
+  minimal version selection),
+
+- obey semver, and increment the module's major
+  version number with every release (drastically
+  reducing the usefullness of minimal version
+  selection - since virtually all releases will
+  be major),
+
+- slow down change in the huge API in favor of
+  stability, yet somehow continue to deliver
+  features,
+
+- drastically reduce the API surface, stabilize on
+  semver there, and refactor as needed inside
+  `internal`.
+
+The last option seems the most appealing.
+
+Projects using the Go API directly only use about
+a dozen public methods in ~ten packages. These
+methods could likely be combined to one or two
+public packages intentionally designed for general
+use, analogous to, say,
+[regexp](https://golang.org/pkg/regexp) or
+[go-yaml](https://github.com/go-yaml/yaml),
+reducing the API surface.
+
+#### Version v4
+
+With `v4` (i.e. the module dependency path
+`sigs.k8s.io/kustomize/v4`)
+two things will happen.
+
+First, the _kustomize_ program itself (`main.go`
+and CLI specific code) will have moved out of
+`sigs.k8s.io/kustomize` and into the new module
+`sigs.k8s.io/kustomize/kustomize`.  This is a
+submodule in the same repo, and it will retain its
+current notion of semver (e.g. a backward
+incompatible change in command behavior will
+trigger a major version bump).  This module will
+not export packages; it's just home to a `main`
+package.
+
+Second, `sigs.k8s.io/kustomize/v4` will start to
+obey semver with a substantially reduced public
+surface, informed by current usage.  Clients
+should import packages from this module, i.e.
+from import paths prefixed by
+`sigs.k8s.io/kustomize/v4`.  The kustomize binary
+itself is an API client requiring this module.
+
+The clients and API will evolve independently.
+
 
 ## Kustomization File Versioning
 
-At the time of writing (circa release of v2.0.0):
 
- - A [kustomization] file is just a YAML file that
-   can be successfully parsed into a particular Go
-   struct defined in the `kustomize` binary.
-
- - This struct does not have a version number,
-   which is the same as saying that its version
-   number matches the program's version number,
-   since it's compiled in.
+The kustomization file is a struct that is part of
+the kustomize Go API (the `sigs.k8s.io/kustomize`
+module), but it also evolves as a k8s API object -
+it has an `apiVersion` field containing its
+own version number.
 
 ### Field Change Policy
 
 - A field's meaning cannot be changed.
-
 - A field may be deprecated, then removed.
-
 - Deprecation means triggering a _minor_ (semver)
-  version bump in the program, and
-  defining a migration path in a non-fatal
-  error message.
-
+  version bump in the kustomize Go API, and
+  defining a migration path in a non-fatal error
+  message.
 - Removal means triggering a _major_ (semver)
-  version bump, and fatal error if field encountered
-  (as with any unknown field).
+  version bump in the kustomize Go API, and fatal
+  error if field encountered (as with any unknown
+  field).  Likewise a change in `apiVersion`.
 
 ### The `edit fix` Command
 
@@ -51,30 +155,24 @@ fields, and writes it out again in the latest
 format.
 
 This is a type version upgrade mechanism that
-works within _major_ program revisions.  There is
-no downgrade capability, as there's no use case
-for it (see discussion below).
+works within _major_ API revisions.  There is no
+downgrade capability, as there's no use case for
+it (see discussion below).
 
 ### Examples
 
-At the time of writing, in v1.0.x, there were 12
-minor releases, with backward compatible
-deprecations fixable via `edit fix`.
-
 With the 2.0.0 release, there were three field
 removals:
 
-- `imageTag` was deprecated when `image` was
+- `imageTag` was deprecated when `images` was
    introduced, because the latter offers more
    general features for image data manipulation.
    `imageTag` was removed in v2.0.0.
-
 - `patches` was deprecated and replaced by
-   `PatchesStrategicMerge` when `PatchesJson6902`
+   `patchesStrategicMerge` when `patchesJson6902`
    was introduced, to make a clearer
    distinction between patch specification formats.
    `patches` was removed in v2.0.0.
-
 - `secretGenerator/commands` was removed
    due to security concerns in v2.0.0
    with no deprecation period.
@@ -92,16 +190,14 @@ process for making [changes].
 The presence of an `apiVersion` field in a k8s
 native type signals:
 
- - its reliability level (alpha vs beta vs
-   generally available),
+- its reliability level (alpha vs beta vs
+  generally available),
+- the existence of code to provide default values
+  to fields not present in a serialization,
+- the existence of code to provide both forward
+  and backward conversion between different
+  versions of types.
 
- - the existence of code to provide default values
-   to fields not present in a serialization,
-   
- - the existence of code to provide both forward
-   and backward conversion between different
-   versions of types.
-   
 The k8s API promises a lossless _conversion_
 between versions over a specific range.  This
 means that a recent client can write an object
@@ -119,18 +215,14 @@ For CRDs, there's a [proposal] on how to manage
 versioning (e.g. a remote service can offer type
 defaulting and conversions).
 
-### Kustomization file versioning
+### Differences
 
-The critical difference between k8s API versioning
-and kustomization file versioning is
-
- - A k8s API server is able to go _forward_ and
-   _backward_ in versioning, to work with older
-   clients, over [some range].
-
- - The `kustomize edit fix` command only moves
-   _forward_ within a _major_ program
-   version.
+- A k8s API server is able to go _forward_ and
+  _backward_ in versioning, to work with older
+  clients, over [some range].
+- The `kustomize edit fix` command only moves
+  _forward_ within a _major_ API
+  version.
 
 At the time of writing, the YAML in a
 kustomization file does not represent a [k8s API]
@@ -148,61 +240,26 @@ the following rules.
 
 Field names with dedicated meaning in k8s
 (`metadata`, `spec`, `status`, etc.)  aren't used.
-
 This is enforced via code review.
 
-#### Optional use of k8s `kind` and `apiVersion`
+#### Default values for k8s `kind` and `apiVersion`
 
-At the time of writing two [special] k8s
-resource fields are allowed, but not required, in
-a kustomization file: [`kind`] and [`apiVersion`].
+In `v3` or below, the two [special] k8s
+resource fields [`kind`] and [`apiVersion`] may
+be omitted from the kustomization file.
 
-If either field is present, they both must be, and
-they must have the following values:
+If either field is present, they both must be.
+If present, the value of `kind` must be:
 
-```
-kind: Kustomization
-apiVersion: kustomize.config.k8s.io/v1beta1
-```
+> ```
+> kind: Kustomization
+> ```
 
-They are allowed to exist and have specific values
-in a kustomization file only as a sort of
-domain-squatting behavior for some future API.  A
-kustomize user gains nothing from adding these
-fields to a kustomization file.
-
-### Why not require `kind` and `apiVersion`?
-
-#### Ease of use and setting proper expectations
-
-Use cases for a kustomization file don't include a
-server storing muliple k8s kinds and offering
-version downgrades.
-
-The kustomization file is more akin to a
-`Makefile`.  A kustomize command can either read a
-kustomization file, or it cannot, and in the later
-case will complain as specifically as possible
-about why (e.g. `unknown field Foo`).
-
-So requiring a `kind` and `apiVersion` would just
-be boilerplate in a user's files, and in all the
-examples and tests.
-
-Nevertheless, _a user still benefits from a
-versioning policy_ and has a `fix` command to
-upgrade files as needed.
-
-#### We can change our minds
-
-When/if the kustomization struct graduates to some
-kind of API status, with an expectation of
-"versionless" storage and downgrade capability,
-whatever it looks like at that moment can be
-locked into `/v1beta1` or `/v1` and the `kind`
-and `apiVersion` fields can be required from that
-moment forward.
+If missing, the value of `apiVersion` defaults to
 
+> ```
+> apiVersion: kustomize.config.k8s.io/v1beta1
+> ```
 
 [field change policy]: #field-change-policy
 [some range]: https://kubernetes.io/docs/reference/using-api/deprecation-policy
@@ -210,11 +267,12 @@ moment forward.
 [beta-level rules]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#alpha-beta-and-stable-versions
 [changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md
 [adapt]: https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/types/kustomization.go#L166
-[special]: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#resources
+[special]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#resources
 [k8s API]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
 [conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
-[release process]: ../build/README.md
+[release page]: https://github.com/kubernetes-sigs/kustomize/releases
+[release process]: ../releasing/README.md
 [kustomization]: glossary.md#kustomization
-[`kind`]: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#types-kinds
+[`kind`]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds
 [`apiVersion`]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning
 [semantic versioning]: https://semver.org

docs/workflows.md

@@ -11,8 +11,9 @@
 [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
 
@@ -71,6 +72,11 @@ Run kustomize, and pipe the output to [apply].
 > kustomize build ~/ldap/overlays/production | kubectl apply -f -
 > ```
 
+You can also use [kubectl-v1.14.0] to apply your [variants].
+> ```
+> kubectl apply -k ~/ldap/overlays/staging
+> kubectl apply -k ~/ldap/overlays/production
+> ```
 
 ## Off-the-shelf configuration
 
@@ -120,6 +126,12 @@ distinct repository.
 > kustomize build ~/ldap/overlays/production | kubectl apply -f -
 > ```
 
+You can also use [kubectl-v1.14.0] to apply your [variants].
+> ```
+> kubectl apply -k ~/ldap/overlays/staging
+> kubectl apply -k ~/ldap/overlays/production
+> ```
+
 #### 5) (optionally) capture changes from upstream
 
 The user can periodically [rebase] their [base] to

docs/zh/INSTALL.md

@@ -0,0 +1,39 @@
+[release 页面]: https://github.com/kubernetes-sigs/kustomize/releases
+[Go]: https://golang.org
+[golang.org]: https://golang.org
+
+## 安装
+
+在 macOS ，您可以使用软件包管理器 Homebrew 来安装 kustomize 。
+
+    brew install kustomize
+
+在 windows ，您可以使用软件包管理器 Chocolatey 来安装 kustomize 。
+
+    choco install kustomize
+
+有关软件包管理器 chocolatey 的使用以及对之前版本的支持，请参考以下链接：
+- [Choco Package](https://chocolatey.org/packages/kustomize)
+- [Package Source](https://github.com/kenmaglio/choco-kustomize)
+
+对于其他系统，请在 [release 页面] 下载相应系统的二进制文件。
+
+或者使用命令行获取最新的官方版本：
+
+```
+opsys=linux  # or darwin, or windows
+curl -s https://api.github.com/repos/kubernetes-sigs/kustomize/releases/latest |\
+  grep browser_download |\
+  grep $opsys |\
+  cut -d '"' -f 4 |\
+  xargs curl -O -L
+mv kustomize_*_${opsys}_amd64 kustomize
+chmod u+x kustomize
+```
+
+使用 [Go] v1.10.1 或更高版本安装（如果可以访问 [golang.org]）：
+
+<!-- @installkustomize @testAgainstLatestRelease -->
+```
+go install sigs.k8s.io/kustomize/v3/cmd/kustomize
+```

docs/zh/README.md

@@ -0,0 +1,50 @@
+[English](../README.md) | 简体中文
+
+# 文档
+
+ * [安装说明](INSTALL.md)
+
+ * [示例](../../examples) - 各种使用流程和概念的详细演示。
+
+ * [术语表](glossary.md) - 用于消除术语歧义。
+
+ * [Kustomize 字段](fields.md) - 介绍 [kustomization](../glossary.md#kustomization) 文件中各字段的含义。
+
+ * [插件](../plugins) - 使用自定义的资源生成器和资源转换器来拓展 kustomize 功能。
+
+ * [工作流](workflows.md) - 使用定制及使用现成配置使用的一些步骤。
+
+ * [FAQ](../FAQ.md)
+
+
+## 发行说明
+
+ * [3.1](../v3.1.0.md) - 2019年7月下旬，扩展 patches 和改进的资源匹配。
+
+ * [3.0](../v3.0.0.md) - 2019年6月下旬，插件开发者发布。
+
+ * [2.1](../v2.1.0.md) - 2019年6月18日
+ 插件、有序资源等。
+
+ * [2.0](../v2.0.0.md) - 2019年3月
+   可以在 [kubectl v1.14][kubectl] 中使用 kustomize [v2.0.3] 。
+
+ * [1.0](../v1.0.1.md) - 2018年5月
+   于 [kubectl repository] 开发后的首发版本。
+
+
+## 行为守则
+
+ * [版本控制](../versioningPolicy.md) - kustomize 代码及 kustomization 文件的版本控制策略。
+
+ * [规避功能](../eschewedFeatures.md) - 目前 Kustomize 不支持某些功能的原因。
+
+ * [贡献指南](../../CONTRIBUTING.md) - 请在提交 PR 之前阅读。
+
+ * [行为准则](../../code-of-conduct.md)
+
+>声明：部分文档可能稍微滞后于英文版本，同步工作持续进行中
+
+[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.0.3
+[kubectl]: https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement
+[kubectl repository]: https://github.com/kubernetes/kubectl

docs/zh/fields.md

@@ -0,0 +1,436 @@
+# Kustomization 文件字段
+
+介绍 [kustomization](../glossary.md#kustomization) 文件中各字段的含义。
+
+## Resources
+
+现有可定制对象。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+|[resources](#resources) | list | 包含 k8s API 对象的文件，或其他包含 kustomizations 文件的目录。 |
+|[CRDs](#crds)| list | CDR 文件，以允许在资源列表中指定自定义资源。 |
+
+## Generators
+
+生成可定制的对象。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+|[configMapGenerator](#configmapgenerator)| list  | 列表中的每个条目都将创建一个 ConfigMap （它是n个 ConfigMap 的生成器）。 |
+|[secretGenerator](#secretgenerator)| list  | 此列表中的每个条目都将创建一个 Secret 资源（它是n个 secrets 的生成器）。 |
+|[generatorOptions](#generatoroptions)| string | generatorOptions 可以修改所有 ConfigMapGenerator 和 SecretGenerator 的行为。 |
+|[generators](#generators)| list | [插件](../plugins)配置文件。 |
+
+## Transformers
+
+可用的转换。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| [commonLabels](#commonlabels) | string | 为所有资源和 selectors 增加 Labels 。 |
+| [commonAnnotations](#commonannotations) | string | 为所有资源增加 Annotations 。 |
+| [images](#images) | list | 修改镜像的名称、tag 或 image digest ，而无需使用 patches 。 |
+| [inventory](#inventory) | struct | 用于生成一个包含清单信息的对象。 |
+| [namespace](#namespace)   | string | 为所有 resources 添加 namespace 。 |
+| [namePrefix](#nameprefix) | string | 该字段的值将添加在所有资源的名称之前。 |
+| [nameSuffix](#namesuffix) | string | 该字段的值将添加在所有资源的名称后面。 |
+| [replicas](#replicas) | list | 修改资源的副本数。 |
+| [patchesStrategicMerge](#patchesstrategicmerge) | list | 此列表中的每个条目都应可以解析为部分或完整的资源定义文件。 |
+| [patchesJson6902](#patchesjson6902) | list | 列表中的每个条目都应可以解析为 kubernetes 对象和将应用于该对象的 JSON patch 。 |
+| [transformers](#transformers) | list | [插件](../plugins)配置文件。 |
+
+## Meta
+
+[k8s metadata]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| [vars](#vars) | string | 获取一个对象中的字段并插入到另外的对象中。 |
+| [apiVersion](#apiversion) | string | [k8s metadata] 字段。 |
+| [kind](#kind) | string | [k8s metadata] 字段。 |
+
+----
+
+### apiVersion
+
+该字段默认值为：
+```
+apiVersion: kustomize.config.k8s.io/v1beta1
+```
+
+### bases
+
+`bases` 字段在 v2.1.0 中已被弃用。
+
+该条目已被移动到 [resources](#resources) 字段中。
+
+### commonLabels
+
+为所有资源和 selectors 增加 Labels
+
+```
+commonLabels:
+  someName: someValue
+  owner: alice
+  app: bingo
+```
+
+### commonAnnotations
+
+为所有资源增加 Annotations ，和 labels 一样是 key:value 的键值对。
+
+```
+commonAnnotations:
+  oncallPager: 800-555-1212
+```
+
+### configMapGenerator
+
+列表中的每个条目都将创建一个 ConfigMap （它是n个 ConfigMap 的生成器）。
+
+下面的示例创建了两个 ConfigMaps：
+
+- 一个具有给定文件的名称和内容
+- 另一个包含 key/value 键值对数据
+
+每个 configMapGenerator 项都可以使用 `behavior: [create|replace|merge]` 参数。
+
+允许 overlay 从父级修改或替换现有的 configMap。
+
+```
+configMapGenerator:
+- name: myJavaServerProps
+  files:
+  - application.properties
+  - more.properties
+- name: myJavaServerEnvVars
+  literals:	
+  - JAVA_HOME=/opt/java/jdk
+  - JAVA_TOOL_OPTIONS=-agentlib:hprof
+```
+
+### crds
+
+此列表中的每个条目都应该是自定义资源定义（CRD）文件的相对路径。
+
+该字段的存在是为了让 kustomize 知道用户自定义的 CRD ，并对这些类型中的对象应用适当的转换。
+
+典型用例：CRD 引用 ConfigMap 对象
+
+在 kustomization 中，ConfigMap 对象名称可能会通过 namePrefix 、nameSuffix 或 hashing 来更改 CRD 对象中此 ConfigMap 对象的名称，
+引用时需要以相同的方式使用 namePrefix 、 nameSuffix 或 hashing 来进行更新。
+
+Annotations 可以放入 openAPI 的定义中：
+
+-  "x-kubernetes-annotation": ""
+-  "x-kubernetes-label-selector": ""
+-  "x-kubernetes-identity": ""
+-  "x-kubernetes-object-ref-api-version": "v1",
+-  "x-kubernetes-object-ref-kind": "Secret",
+-  "x-kubernetes-object-ref-name-key": "name",
+
+```
+
+crds:
+- crds/typeA.yaml
+- crds/typeB.yaml
+```
+
+
+### generatorOptions
+
+generatorOptions 修改所有 [ConfigMapGenerator](#configmapgenerator) 和 [SecretGenerator](#secretgenerator) 的行为。
+
+```
+generatorOptions:
+  # 为所有生成的资源添加 labels
+  labels:
+    kustomize.generated.resources: somevalue
+  # 为所有生成的资源添加 annotations
+  annotations:
+    kustomize.generated.resource: somevalue
+  # disableNameSuffixHash 为 true 时将禁止默认的在名称后添加哈希值后缀的行为
+  disableNameSuffixHash: true
+```
+
+### generators
+
+[插件](../plugins)生成器配置文件列表。
+
+```
+generators:
+- mySecretGeneratorPlugin.yaml
+- myAppGeneratorPlugin.yaml
+```
+
+### images
+
+修改镜像的名称、tag 或 image digest ，而无需使用 patches 。例如，对于这种 kubernetes Deployment 片段：
+
+```
+containers:
+ - name: mypostgresdb
+   image: postgres:8
+ - name: nginxapp
+   image: nginx:1.7.9
+ - name: myapp
+   image: my-demo-app:latest
+ - name: alpine-app
+   image: alpine:3.7
+```
+
+可以通过以下方式更改 `image` ：
+ 
+ - `postgres:8` to `my-registry/my-postgres:v1`,
+ - nginx tag `1.7.9` to `1.8.0`,
+ - image name `my-demo-app` to `my-app`,
+ - alpine's tag `3.7` to a digest value
+
+可以在 *kustomization* 中添加以下内容：
+
+```
+images:
+- name: postgres
+  newName: my-registry/my-postgres
+  newTag: v1
+- name: nginx
+  newTag: 1.8.0
+- name: my-demo-app
+  newName: my-app
+- name: alpine
+  digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3
+```
+
+### inventory
+
+详见 [inventory object](inventory_object.md)。
+
+### kind
+
+该字段默认值为：
+
+```
+kind: Kustomization
+```
+
+
+### namespace
+
+为所有 resources 添加 namespace 。
+
+```
+namespace: my-namespace
+```
+
+### namePrefix
+
+该字段的值将添加在所有资源的名称之前，例如 将资源名称 `wordpress` 变为 `alices-wordpress` 。
+
+```
+namePrefix: alices-
+```
+
+### nameSuffix
+
+该字段的值将添加在所有资源的名称后面，例如 将资源名称 `wordpress` 变为 `wordpress-v2` 。
+
+如果资源类型为 ConfigMap 或 Secret ，则在哈希值之前附加后缀。
+
+```
+nameSuffix: -v2
+```
+
+### patchesStrategicMerge
+
+此列表中的每个条目都应可以解析为部分或完整的资源定义文件。
+
+这些（也可能是部分的）资源文件中的 name 必须与已经通过 `resources` 加载的 name 字段匹配，或者通过 `bases` 中的 name 字段匹配。这些条目将用于 _patch_（修改）已知资源。
+
+推荐使用小的 patches，例如：修改内存的 request/limit，更改 ConfigMap 中的 env 变量等小的 patches 易于维护和查看，并且易于在 overlays 中混合使用。
+
+```
+patchesStrategicMerge:
+- service_port_8888.yaml
+- deployment_increase_replicas.yaml
+- deployment_increase_memory.yaml
+```
+
+### patchesJson6902
+
+patchesJson6902 列表中的每个条目都应可以解析为 kubernetes 对象和将应用于该对象的 JSON patch
+
+JSON patch 的文档地址：https://tools.ietf.org/html/rfc6902
+
+目标字段指向的 kubernetes 对象的 group、 version、 kind、 name 和 namespace 在同一 kustomization 内 path 字段内容是 JSON patch 文件的相对路径。
+
+patch 文件中的内容可以如下这种 JSON 格式：
+
+```
+ [
+   {"op": "add", "path": "/some/new/path", "value": "value"},
+   {"op": "replace", "path": "/some/existing/path", "value": "new value"}
+ ]
+ ```
+
+也可以使用 YAML 格式表示：
+
+```
+- op: add
+  path: /some/new/path
+  value: value
+- op: replace
+  path: /some/existing/path
+  value: new value
+```
+
+```
+patchesJson6902:
+- target:
+    version: v1
+    kind: Deployment
+    name: my-deployment
+  path: add_init_container.yaml
+- target:
+    version: v1
+    kind: Service
+    name: my-service
+  path: add_service_annotation.yaml
+```
+
+### replicas
+
+修改资源的副本数。
+
+例如：对于如下 kubernetes Deployment 片段：
+
+```
+kind: Deployment
+metadata:
+  name: deployment-name
+spec:
+  replicas: 3
+```
+
+在 kustomization 中添加以下内容，将副本数更改为5：
+
+```
+replicas:
+- name: deployment-name
+  count: 5
+```
+
+该字段内容为列表，所以可以同时修改许多资源。
+
+#### Limitation
+
+由于这个声明无法设置 `kind:` 或 `group:` 它将匹配任何可以匹配名称的 `group` 和 `kind` ，并且它是以下之一：
+- `Deployment`
+- `ReplicationController`
+- `ReplicaSet`
+- `StatefulSet`
+
+对于更复杂的用例，请使用 patch 。
+
+### resources
+
+该条目可以是指向本地目录的相对路径，也可以是指向远程仓库中的目录的 URL，例如：
+
+```
+resource:
+- myNamespace.yaml
+- sub-dir/some-deployment.yaml
+- ../../commonbase
+- github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6
+- deployment.yaml
+- github.com/kubernets-sigs/kustomize//examples/helloWorld?ref=test-branch
+```
+
+将以深度优先的顺序读取和处理资源。
+
+
+文件应包含 YAML 格式的 k8s 资源。一个资源描述文件可以含有多个由（“---”）分隔的资源。
+应该包含 `resources` 字段的 kustomization 文件的指定文件目录的相对路径。
+
+[hashicorp URL]: https://github.com/hashicorp/go-getter#url-format
+
+目录规范可以是相对、绝对或部分的 URL。URL 规范应遵循 [hashicorp URL] 格式。该目录必须包含 `kustomization.yaml` 文件。
+
+### secretGenerator
+
+此列表中的每个条目都将创建一个 Secret 资源（它是n个 secrets 的生成器）。
+
+```
+secretGenerator:
+- name: app-tls
+  files:
+  - secret/tls.cert
+  - secret/tls.key
+  type: "kubernetes.io/tls"
+- name: app-tls-namespaced
+  # you can define a namespace to generate secret in, defaults to: "default"
+  namespace: apps
+  files:
+  - tls.crt=catsecret/tls.cert
+  - tls.key=secret/tls.key
+  type: "kubernetes.io/tls"
+- name: env_file_secret
+  envs:
+  - env.txt
+  type: Opaque
+```
+
+### vars
+
+Vars 用于从一个 resource 字段中获取文本，并将该文本插入指定位置 - 反射功能。
+
+例如，假设需要在容器的 command 中指定了 Service 对象的名称，并在容器的 env 中指定了 Secret 对象的名称来确保以下内容可以正常工作：
+
+```
+containers:
+  - image: myimage
+    command: ["start", "--host", "$(MY_SERVICE_NAME)"]
+    env:
+    - name: SECRET_TOKEN
+      value: $(SOME_SECRET_NAME)
+```
+
+则可以在 `vars：` 中添加如下内容：
+
+```
+vars:
+- name: SOME_SECRET_NAME
+  objref:
+    kind: Secret
+    name: my-secret
+    apiVersion: v1
+- name: MY_SERVICE_NAME
+  objref:
+    kind: Service
+    name: my-service
+    apiVersion: v1
+  fieldref:
+    fieldpath: metadata.name
+- name: ANOTHER_DEPLOYMENTS_POD_RESTART_POLICY
+  objref:
+    kind: Deployment
+    name: my-deployment
+    apiVersion: apps/v1
+  fieldref:
+    fieldpath: spec.template.spec.restartPolicy
+```
+var 是包含该对象的变量名、对象引用和字段引用的元组。
+
+字段引用是可选的，默认为 `metadata.name`，这是正常的默认值，因为 kustomize 用于生成或修改 resources 的名称。
+
+在撰写本文档时，仅支持字符串类型字段，不支持 ints，bools，arrays 等。例如，在某些pod模板的容器编号2中提取镜像的名称是不可能的。
+
+变量引用，即字符串 '$(FOO)' ，只能放在 kustomize 配置指定的特定对象的特定字段中。
+
+关于 vars 的默认配置数据可以查看：
+https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/transformers/config/defaultconfig/varreference.go
+
+默认目标是所有容器 command args 和 env 字段。
+
+Vars _不应该_ 被用于 kustomize 已经处理过的配置中插入 names 。
+例如， Deployment 可以通过 name 引用 ConfigMap ，如果 kustomize 更改 ConfigMap 的名称，则知道更改 Deployment 中的引用的 name 。

docs/zh/glossary.md

@@ -0,0 +1,308 @@
+# 词汇表
+
+[CRD spec]: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/
+[CRD]: #custom-resource-definition
+[DAM]: #声明式应用程序管理
+[Declarative Application Management]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md
+[JSON]: https://www.json.org/
+[JSONPatch]: https://tools.ietf.org/html/rfc6902
+[JSONMergePatch]: https://tools.ietf.org/html/rfc7386
+[Resource]: #resource
+[YAML]: http://www.yaml.org/start.html
+[application]: #application
+[apply]: #apply
+[apt]: https://en.wikipedia.org/wiki/APT_(Debian)
+[base]: #base
+[bases]: #base
+[bespoke]: #bespoke-configuration
+[gitops]: #gitops
+[k8s]: #kubernetes
+[kubernetes]: #kubernetes
+[kustomize]: #kustomize
+[kustomization]: #kustomization
+[kustomizations]: #kustomization
+[off-the-shelf]: #off-the-shelf-configuration
+[overlay]: #overlay
+[overlays]: #overlay
+[patch]: #patch
+[patches]: #patch
+[patchJson6902]: #patchjson6902
+[patchExampleJson6902]: https://github.com/kubernetes-sigs/kustomize/blob/master/examples/jsonpatch.md
+[patchesJson6902]: #patchjson6902
+[proposal]: https://github.com/kubernetes/community/pull/1629
+[rebase]: https://git-scm.com/docs/git-rebase
+[资源]: #资源
+[resources]: #resource
+[root]: #kustomization-root
+[rpm]: https://en.wikipedia.org/wiki/Rpm_(software)
+[strategic-merge]: https://git.k8s.io/community/contributors/devel/sig-api-machinery/strategic-merge-patch.md
+[target]: #target
+[transformer]: #transformer
+[variant]: #variant
+[variants]: #variant
+[workflow]: workflows.md
+
+## 应用
+
+**应用**是为某种目的关联起来的一组 Kubernetes 资源，例如一个前有负载均衡器，后有数据库的 Web 服务器。用标签、命名和元数据将[资源]组织起来，可以进行**添加**或**删除**等操作。
+
+有提案（[Declarative Application Management]）描述了一种称为应用的新的 Kubernetes 资源。更加正式的描述了这一思路，并在应用程序级别提供了运维和仪表盘的支持。
+
+[Kustomize] 对 Kubernetes 资源进行配置，其中描述的应用程序资源只是另一种普通的资源。
+
+## Apply
+
+**Apply** 这个动词在 Kubernetes 的上下文中，指的是一个 Kubernetes 命令以及能够对集群施加影响的进程内 [API 端点](https://goo.gl/UbCRuf)。
+
+用户可以将对集群的运行要求用一组完整的资源列表的形式进行表达，通过 **apply** 命令进行提交。
+
+集群把新提交的资源和之前提交的状态以及当前的实际状态进行合并，形成新的状态。这就是 Kubernetes 的状态管理过程。
+
+## Base
+
+**Base** 指的是会被其它 [Kustomization] 引用的 [Kustomization]。
+
+包括 [Overlay] 在内的任何 Kustomization，都可以作为其它 Kustomization 的 Base。
+
+Base 对引用自己的 Overlay 并无感知。
+
+Base 和 [Overlay] 可以作为 Git 仓库中的唯一内容，用于简单的 [GitOps] 管理。对仓库的变更可以触发构建、测试以及部署过程。
+
+## 定制配置
+
+**定制**配置是由组织为满足自身需要，在内部创建和管理的 [Kustomization] 和[资源]。
+
+和**定制配置**关联的 [Workflow] 比关联到通用配置的 [Workflow] 要简单一些，原因是通用配置是共享的，需要周期性的跟踪他人作出的变更。
+
+## Custom resource definition
+
+可以通过定制 CRD ([CRD spec]) 的方式对 Kubernetes API 进行扩展。
+
+CRD 定义的[资源]是一种全新的资源，可以和 ConfigMap、Deployment 之类的原生资源以相同的方式来使用。
+
+Kustomize 能够生成自定义资源，但是要完成这个目标，必须给出对应的 CRD，这样才能正确的对这种结构进行处理。
+
+## 声明式应用程序管理
+
+Kustomize 鼓励对声明式应用程序管理（[Declarative Application Management]）的支持，这种方式是一系列 Kubernetes 集群管理的最佳实践。Kustomize 应该可以：
+
+- 适用于任何配置，例如自有配置、共享配置、无状态、有状态等。
+- 支持通用配置，以及创建变体（例如开发、预发布、生产）。
+- 开放使用原生 Kubernetes API，而不是隐藏它们。
+- 不会给版本控制系统和集成的评审和审计工作造成困难。
+- 用 Unix 的风格和其它工具进行协作。
+- 避免使用模板、领域特定的语言等额外的学习内容。
+
+## 生成器
+
+生成器生成的资源，可以直接使用，也可以输出给转换器（[Transformer]）。
+
+## GitOps
+
+一种 DevOps 或者 CICD 流程，这种流程以 Git 作为唯一的事实，并且在这种事实发生变化时采取措施（例如构建、测试和部署）。
+
+## Kustomization
+
+**Kustomization** 这个词可以指 `kustomization.yaml` 这个文件，更常见的情况是一个包含了 `kustomization.yaml` 及其所有直接引用文件的相对路径（所有不需要 URL 的本地数据）。
+
+也就是说，如果在 [Kustomize] 的上下文中说到 **Kustomization**，可能是以下的情况之一：
+
+- 一个叫做 `kustomization.yaml` 的文件。
+- 一个压缩包（包含 YAML 文件以及它的引用文件）。
+- 一个 Git 压缩包。
+- 一个 Git 仓库的 URL。
+
+一个 Kustomization 文件包含的[字段](fields.md)，分为四个类别：
+
+- `resources`：待定制的现存[资源]，示例字段：`resources`、`crds`。
+- `generator`：将要创建的**新**资源，示例字段：`configMapGenerator`（传统）、`secretGenerator`（传统）、`generators`（v2.1）
+- `transformer`：对前面提到的新旧资源进行**处理**的方式。示例字段：`namePrefix`、`nameSuffix`、`images`、`commonLabels`、`patchesJson6902` 等。在 v2.1 中还有更多的 `transformer`。
+- `meta`：会对上面几种字段产生影响。示例字段：`vars`、`namespace`、`apiVersion`、`kind` 等。
+
+## Kustomization root
+
+直接包含 `kustomization.yaml` 文件的目录。
+
+处理 Kustomization 文件时，可能访问到该目录以内或以外的文件。
+
+像 YAML 资源这样的数据文件，或者用于生成 ConfigMap 或 Secret 的包含 `name=value` 的文本文件，或者用于补丁转换的补丁文件，必须**在这个目录的内部**，需要显式的使用**相对路径**来表达。
+
+v2.1 中有一个特殊选项 `--load_restrictions none` 能够放宽这个限制，从而让不同的 Kustomization 可以共享补丁文件。
+
+可以用 URL、绝对路径或者相对路径引用其它的 Kustomization（包含 `kustomization.yaml` 文件的其它目录）。
+
+如果 `A` Kustomization 依赖 `B` Kustomization，那么：
+
+- `B` 不能包含 `A`。
+- `B` 不能依赖 `A`，间接依赖也不可以。
+
+`A` 可以包含 `B`，但是这样的话，最简单的方式可能是让 `A` 直接依赖 `B` 的资源，并去除 `B` 的 `kustomization.yaml` 文件（就是把 `B` 合并到 `A`）。
+
+通常情况下，`B` 和 `A` 处于同级目录，或者 `B` 放在一个完全独立的 Git 仓库里，可以从任意的 Kustomization 进行引用。
+
+常见布局大致如下：
+
+> ```
+> ├── base
+> │   ├── deployment.yaml
+> │   ├── kustomization.yaml
+> │   └── service.yaml
+> └── overlays
+>     ├── dev
+>     │   ├── kustomization.yaml
+>     │   └── patch.yaml
+>     ├── prod
+>     │   ├── kustomization.yaml
+>     │   └── patch.yaml
+>     └── staging
+>         ├── kustomization.yaml
+>         └── patch.yaml
+> ```
+
+`dev`、`prod` 以及 `staging` 是否依赖于 `base`，要根据 `kustomization.yaml` 具体判断。
+
+## Kubernetes
+
+[Kubernetes](https://kubernetes.io) 是一个开源软件，为容器化应用提供了自动部署、伸缩和管理的能力。
+
+它经常会被简写为 `k8s`。
+
+## Kubernetes 风格的对象
+
+[必要字段]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
+
+用 YAML 或者 JSON 文件表达一个对象，其中包含一些[必要字段]。`kind` 字段用于标识对象类型，`metadata/name` 字段用于区分实例，`apiVersion` 表示的是版本（如果有多个版本的话）。
+
+## Kustomize
+
+`kustomize` 是一个面向 Kubernetes 的命令行工具，用一种无模板、结构化的的方式为为声明式配置提供定制支持。
+
+`面向 Kubernetes` 的意思是 Kustomize 对 API 资源、Kubernetes 概念（例如名称、标签、命名空间等）、以及资源补丁是有支持的。
+
+Kustomize 是 [DAM] 的一个实现。
+
+## 通用配置
+
+通用配置是一种用于共享的 Kustomization 以及资源。
+
+例如创建一个这样的 Github 仓库：
+
+> ```
+> github.com/username/someapp/
+>   kustomization.yaml
+>   deployment.yaml
+>   configmap.yaml
+>   README.md
+> ```
+
+其他人可以 `fork` 这个仓库，并把它们的 Fork `clone` 到本地进行定制。
+
+用户可以用这个克隆回来的版本作为 [Base]，在此基础上定制 [Overlay] 来满足自身需求。
+
+## Overlay
+
+`Overlay` 是一个 依赖于其它 Kustomization 的 Kustomization。
+
+Overlay 引用（通过文件路径、URI 或者别的什么方式）的 [Kustomization] 被称为 [Base]。
+
+Overlay 无法脱离 Base 独立生效。
+
+Overlay 可以作为其它 Overlay 的 Base。
+
+通常 Overlay 都是不止一个的，因为实际情况中就需要为单一 Base 创建不同的[变体]，例如 `development`、`QA`、`production` 等。
+
+总的说来，这些变体使用的资源基本是一致的，只有一些简单的差异，例如 Deployment 的实例数量、特定 Pod 的 CPU 资源、ConfigMap 中的数据源定义等。
+
+可以这样把配置提交到集群：
+
+> ```
+>  kustomize build someapp/overlays/staging |\
+>      kubectl apply -f -
+>
+>  kustomize build someapp/overlays/production |\
+>      kubectl apply -f -
+> ```
+
+对 Base 的使用是隐性的——Overlay 的依赖是指向 Base 的。
+
+请参考 [root]。
+
+## 包
+
+在 Kustomize 中，`包`是没有意义的，Kustomize 并无意成为 [apt]、[rpm] 那样的传统包管理工具。
+
+## Patch
+
+修改资源的通用指令。
+
+有两种功能类似但是实现不同的补丁方式：[strategic merge patch](#patchstrategicmerge) 和 [JSON patch](#patchjson6902)。
+
+## patchStrategicMerge
+
+`patchStrategicMerge` 是 [strategic-merge] 风格的补丁（SMP）。
+
+SMP 看上去像个不完整的 Kubernetes 资源 YAML。SMP 中包含 `TypeMeta` 字段，用于表明这个补丁的目标[资源]的 `group/version/kind/name`，剩余的字段是一个嵌套的结构，用于指定新的字段值，例如镜像标签。
+
+缺省情况下，SMP 会**替换**目标值。如果目标值是一个字符串，这种行为是合适的，但是如果目标值是个列表，可能就不合适了。
+
+可以加入 `directive` 来修改这种行为，，可以接受的 `directive` 包括 `replace`（缺省）、`merge`（不替换列表）、`delete` 等（[相关说明][strategic-merge]）。
+
+注意对自定义资源来说，SMP 会被当作 [json merge patches][JSONMergePatch].
+
+有趣的事实：所有的资源文件都可以当作 SMP 使用，相同 `group/version/kind/name` 资源中的匹配字段会被替换，其它内容则保持不变。
+
+## patchJson6902
+
+`patchJson6902` 引用一个 Kubernetes 资源，并用 [JSONPatch] 指定了修改这一资源的方法。
+
+`patchJson6902` 几乎可以做到所有 `patchStrategicMerge` 的功能，但是语法更加简单，参考[示例][patchExampleJson6902]
+
+## 插件
+
+Kustomize 可以使用的一段代码，但是无需编译到 Kustomize 内部，可以作为 Kustomization 的一部分，生成或转换 Kubernetes 资源。
+
+[插件](../plugins)的细节。
+
+## 资源
+
+在 REST-ful API 的上下文中，资源是 `GET`、`PUT` 或者 `POST` 等 HTTP 操作的目标。Kubernetes 提供了 REST-ful API 界面，用于和客户端进行交互。
+
+在 Kustomization 的上下文中，资源是一个相对于 [root] 的相对路径，指向 [YAML] 或者 [JSON] 文件，描述了一个 Kubernetes API 对象，例如 Deployment 或者 ConfigMap，或者一个 Kustomization、或者一个指向 Kustomization 的 URL。
+
+或者说任何定义了[对象](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields)的格式正确的 YAML 文件，其中包含了 `kind` 和 `metadata/name` 字段，都是资源。
+
+## Root
+
+参看 [kustomization root][root].
+
+## sub-target / sub-application / sub-package
+
+不存在 `sub-xxx`，只有 [Base] 和 [Overlay]。
+
+## Target
+
+`target` 是 `kustomize build` 的参数，例如：
+
+> ```
+>  kustomize build $target
+> ```
+
+`$target` 必须是一个指向 [Kustomization] 的路径或者 URL。
+
+要创建用于进行 [Apply] 操作的资源，`target` 中必须包含或者引用所有相关信息。
+
+[Base] 或者 [Overlay] 都可以作为 `target`。
+
+## Transformer
+
+转换器能够修改资源，或者在 `kustomize build` 的过程中获取资源的信息。
+
+## 变体
+
+在集群中把 [Overlay] 应用到 [Base] 上的产物称为**变体**。
+
+比如 `staging` 和 `production` 两个 Overlay，都修改了同样的 Base，来创建各自的变体。
+
+`staging` 变体包含了一组用来保障测试过程的资源，或者一些想要看到生产环境下一个版本的外部用户。
+
+`production` 变体用于承载生产流量，可能使用大量的副本，分配更多的 CPU 和内存。

docs/zh/workflows.md

@@ -0,0 +1,127 @@
+[OTS]: ../glossary.md#off-the-shelf-configuration
+[apply]: ../glossary.md#apply
+[applying]: ../glossary.md#apply
+[base]: ../glossary.md#base
+[fork]: https://guides.github.com/activities/forking/
+[variants]: ../glossary.md#variant
+[kustomization]: ../glossary.md#kustomization
+[off-the-shelf]: ../glossary.md#off-the-shelf-configuration
+[overlays]: ../glossary.md#overlay
+[patch]: ../glossary.md#patch
+[patches]: ../glossary.md#patch
+[rebase]: https://git-scm.com/docs/git-rebase
+[resources]: ../glossary.md#resource
+[workflowBespoke]: ../images/workflowBespoke.jpg
+[workflowOts]: ../images/workflowOts.jpg
+[kubectl-v1.14.0]:https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/
+
+# 工作流
+
+工作流是 kustomize 运行和维护配置的步骤。
+
+## 配置定制（Bespoke configuration）
+
+在这个工作流方式中，所有的配置文件（ YAML 资源）都为用户所有，存储在用户的私有 repo 中。其他用户是无法使用的。
+
+![bespoke config workflow image][workflowBespoke]
+
+#### 1) 创建一个目录用于版本控制
+
+我们希望将一个名为 _ldap_ 的 Kubernetes 集群应用的配置保存在自己的 repo 中。
+这里使用 git 进行版本控制。
+
+> ```
+> git init ~/ldap
+> ```
+
+#### 2) 创建一个 [base]
+
+> ```
+> mkdir -p ~/ldap/base
+> ```
+
+在这个目录中创建并提交 [kustomization] 文件及一组资源配置。
+
+#### 3) 创建 [overlays]
+
+> ```
+> mkdir -p ~/ldap/overlays/staging
+> mkdir -p ~/ldap/overlays/production
+> ```
+
+每个目录都包含需要一个 [kustomization] 文件以及一或多个 [patches]。
+
+在 _staging_ 目录可能会有一个用于在 configmap 中打开一个实验标记的补丁。
+
+在 _production_ 目录可能会有一个在 deployment 中增加副本数的补丁。
+
+#### 4) 生成 [variants]
+
+运行 kustomize，将生成的配置用于 kubernetes 应用发布。
+
+> ```
+> kustomize build ~/ldap/overlays/staging | kubectl apply -f -
+> kustomize build ~/ldap/overlays/production | kubectl apply -f -
+> ```
+
+也可以在 [kubectl-v1.14.0] 版，使用 ```kubectl``` 命令发布你的 [variants] 。
+> ```
+> kubectl apply -k ~/ldap/overlays/staging
+> kubectl apply -k ~/ldap/overlays/production
+> ```
+
+## 使用现成的配置（Off-the-shelf configuration）
+
+在这个工作流方式中，可从别人的 repo 中 fork kustomize 配置，并根据自己的需求来配置。
+
+
+![off-the-shelf config workflow image][workflowOts]
+
+#### 1) 寻找并且 [fork] 一个 [OTS] 配置
+
+#### 2) 将其克隆为你自己的 [base]
+
+这个 [base] 目录维护在上游为 [OTS] 配置的 repo ，在这个例子使用 `ladp` 的 repo 。
+
+> ```
+> mkdir ~/ldap
+> git clone https://github.com/$USER/ldap ~/ldap/base
+> cd ~/ldap/base
+> git remote add upstream git@github.com:$USER/ldap
+> ```
+
+#### 3) 创建 [overlays]
+
+如配置定制方法一样，创建并完善 _overlays_ 目录中的内容。
+
+所有的 [overlays] 都依赖于 [base] 。
+
+> ```
+> mkdir -p ~/ldap/overlays/staging
+> mkdir -p ~/ldap/overlays/production
+> ```
+
+用户可以将 `overlays` 维护在不同的 repo 中。
+
+#### 4) 生成 [variants]
+
+> ```
+> kustomize build ~/ldap/overlays/staging | kubectl apply -f -
+> kustomize build ~/ldap/overlays/production | kubectl apply -f -
+> ```
+
+也可以在 [kubectl-v1.14.0] 版，使用 ```kubectl``` 命令发布你的 [variants] 。
+> ```
+> kubectl apply -k ~/ldap/overlays/staging
+> kubectl apply -k ~/ldap/overlays/production
+> ```
+
+#### 5) （可选）从上游更新
+
+用户可以定期从上游 repo 中 [rebase] 他们的 [base] 以保证及时更新。
+
+> ```
+> cd ~/ldap/base
+> git fetch upstream
+> git rebase upstream/master
+> ```

examples/README.md

@@ -1,49 +1,72 @@
+English | [简体中文](zh/README.md)
+
 # Examples
 
-These examples assume that `kustomize` is on your `$PATH`.
+To run these examples, your `$PATH` must contain `kustomize`.
+See the [installation instructions](../docs/INSTALL.md).
 
-They are covered by [pre-commit](../bin/pre-commit.sh)
-tests, and should work with HEAD
+These examples are [tested](../travis/pre-commit.sh)
+to work with the latest _released_ version of kustomize.
 
-<!-- @installkustomize @test -->
-```
-go get sigs.k8s.io/kustomize
-```
+Basic Usage
 
- * [hello world](helloWorld/README.md) - Deploy multiple
+  * [configGenerations](configGeneration.md) -
+   Rolling update when ConfigMapGenerator changes.
+
+  * [combineConfigs](combineConfigs.md) -
+   Mixing configuration data from different owners
+   (e.g. devops/SRE and developers).
+
+  * [generatorOptions](generatorOptions.md) -
+   Modifying behavior of all ConfigMap and Secret generators.
+
+  * [vars](wordpress/README.md) - Injecting k8s runtime data into
+     container arguments (e.g. to point wordpress to a SQL service) by vars.
+
+  * [image names and tags](image.md) - Updating image names and tags without applying a patch.
+
+  * [remote target](remoteBuild.md) - Building a kustomization from a github URL
+
+  * [json patch](jsonpatch.md) - Apply a json patch in a kustomization
+
+  * [patch multiple objects](patchMultipleObjects.md) - Apply a patch to multiple objects
+
+Advanced Usage
+
+- generator plugins:
+
+   * [last mile helm](chart.md) - Make last mile modifications to
+     a helm chart.
+
+   * [secret generation](secretGeneratorPlugin.md) - Generating secrets from a plugin.
+
+   * [remote sources](goGetterGeneratorPlugin.md) - Generating from remote sources.
+
+- transformer plugins:
+   * [validation transformer](validationTransformer/README.md) -
+   validate resources through a transformer
+
+- customize builtin transformer configurations
+
+   * [transformer configs](transformerconfigs/README.md) - Customize transformer configurations
+
+
+Multi Variant Examples
+
+  * [hello world](helloWorld/README.md) - Deploy multiple
    (differently configured) variants of a simple Hello
    World server.
 
- * [LDAP](ldap/README.md) - Deploy multiple
-   (differently configured) variants of a LDAP server.
+  * [LDAP](ldap/README.md) - Deploy multiple
+     (differently configured) variants of a LDAP server.
 
- * [mySql](mySql/README.md) - Create a MySQL production
-   configuration from scratch.
-
- * [springboot](springboot/README.md) - Create a Spring Boot
+  * [springboot](springboot/README.md) - Create a Spring Boot
    application production configuration from scratch.
 
- * [combineConfigs](combineConfigs.md) -
-   Mixing configuration data from different owners
-   (e.g. devops/SRE and developers).
-   
- * [configGenerations](configGeneration.md) -
-   Rolling update when ConfigMapGenerator changes
- 
- * [generatorOptions](generatorOptions.md) - Modifying behavior of all ConfigMap and Secret generators.  
+  * [mySql](mySql/README.md) - Create a MySQL production
+   configuration from scratch.
 
- * [breakfast](breakfast.md) - Customize breakfast for
-   Alice and Bob.
-   
- * [vars](wordpress/README.md) - Injecting k8s runtime data into container arguments (e.g. to point wordpress to a SQL service) by vars.
- 
- * [image names and tags](image.md) - Updating image names and tags without applying a patch.
+  * [breakfast](breakfast.md) - Customize breakfast for
+     Alice and Bob.
 
- * [multibases](multibases/README.md) - Composing three variants (dev, staging, production) with a common base.
-
- * [remote target](remoteBuild.md) - Building a kustomization from a github URL
- 
- * [json patch](jsonpatch.md) - Apply a json patch in a kustomization
- 
- * [transformer configs](transformerconfigs/README.md) - Customize transformer configurations
- 
+  * [multibases](multibases/README.md) - Composing three variants (dev, staging, production) with a common base.

examples/breakfast.md

@@ -6,14 +6,14 @@
 
 Define a place to work:
 
-<!-- @makeWorkplace @test -->
+<!-- @makeWorkplace @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 ```
 
 Make a place to put the base breakfast configuration:
 
-<!-- @baseDir @test -->
+<!-- @baseDir @testAgainstLatestRelease -->
 ```
 mkdir -p $DEMO_HOME/breakfast/base
 ```
@@ -21,7 +21,7 @@ mkdir -p $DEMO_HOME/breakfast/base
 Make a `kustomization` to define what goes into
 breakfast.  This breakfast has coffee and pancakes:
 
-<!-- @baseKustomization @test -->
+<!-- @baseKustomization @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/breakfast/base/kustomization.yaml
 resources:
@@ -34,7 +34,7 @@ Here's a _coffee_ type.  Give it a `kind` and `metdata/name` field
 to conform to [kubernetes API object style]; no other
 file or definition is needed:
 
-<!-- @coffee @test -->
+<!-- @coffee @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/breakfast/base/coffee.yaml
 kind: Coffee
@@ -50,7 +50,7 @@ The `name` field merely distinguishes this instance of
 coffee from others (if there were any).
 
 Likewise, define _pancakes_:
-<!-- @pancakes @test -->
+<!-- @pancakes @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/breakfast/base/pancakes.yaml
 kind: Pancakes
@@ -64,14 +64,14 @@ EOF
 Make a custom [variant] of breakfast for Alice, who
 likes her coffee hot:
 
-<!-- @aliceOverlay @test -->
+<!-- @aliceOverlay @testAgainstLatestRelease -->
 ```
 mkdir -p $DEMO_HOME/breakfast/overlays/alice
 
 cat <<EOF >$DEMO_HOME/breakfast/overlays/alice/kustomization.yaml
 commonLabels:
   who: alice
-bases:
+resources:
 - ../../base
 patchesStrategicMerge:
 - temperature.yaml
@@ -87,14 +87,14 @@ EOF
 
 And likewise a [variant] for Bob, who wants _five_ pancakes, with strawberries:
 
-<!-- @bobOverlay @test -->
+<!-- @bobOverlay @testAgainstLatestRelease -->
 ```
 mkdir -p $DEMO_HOME/breakfast/overlays/bob
 
 cat <<EOF >$DEMO_HOME/breakfast/overlays/bob/kustomization.yaml
 commonLabels:
   who: bob
-bases:
+resources:
 - ../../base
 patchesStrategicMerge:
 - topping.yaml
@@ -111,14 +111,14 @@ EOF
 
 One can now generate the configs for Alice’s breakfast:
 
-<!-- @generateAlice @test -->
+<!-- @generateAlice @testAgainstLatestRelease -->
 ```
 kustomize build $DEMO_HOME/breakfast/overlays/alice
 ```
 
 Likewise for Bob:
 
-<!-- @generateBob @test -->
+<!-- @generateBob @testAgainstLatestRelease -->
 ```
 kustomize build $DEMO_HOME/breakfast/overlays/bob
 ```

examples/chart.md

@@ -0,0 +1,255 @@
+# kustomization of a helm chart
+
+[last mile]: https://testingclouds.wordpress.com/2018/07/20/844/
+[stable chart]: https://github.com/helm/charts/tree/master/stable
+[Helm charts]: https://github.com/helm/charts
+[_minecraft_]: https://github.com/helm/charts/tree/master/stable/minecraft
+[plugin]: ../docs/plugins
+
+[Helm charts] aren't natively read by kustomize, but
+kustomize has a [plugin] system that allows one to
+access helm charts.
+
+One pattern combining kustomize and helm is
+the [last mile] modification, where
+one uses an inflated chart as a base, then
+modifies it on the way to the cluster using
+kustomize.
+
+The plugin used in the example below is coded to work
+only for charts found in the [stable chart] repo.  The
+example arbitrarily uses [_minecraft_], but should work
+for any chart.
+
+The following example assumes you have `helm`
+on your `$PATH`.
+
+Make a place to work:
+
+<!-- @makeWorkplace @helmtest -->
+```
+DEMO_HOME=$(mktemp -d)
+mkdir -p $DEMO_HOME/base
+mkdir -p $DEMO_HOME/dev
+mkdir -p $DEMO_HOME/prod
+```
+
+## Use a remote chart
+
+Define a kustomization representing your _development_
+variant (aka environment).
+
+This could involve any number of kustomizations (see
+other examples), but in this case just add the name
+prefix `dev-` to all resources:
+
+<!-- @writeKustDev @helmtest -->
+```
+cat <<'EOF' >$DEMO_HOME/dev/kustomization.yaml
+namePrefix:  dev-
+resources:
+- ../base
+EOF
+```
+
+Likewise define a _production_ variant, with a name
+prefix `prod-`:
+
+<!-- @writeKustProd @helmtest -->
+```
+cat <<'EOF' >$DEMO_HOME/prod/kustomization.yaml
+namePrefix:  prod-
+resources:
+- ../base
+EOF
+```
+
+These two variants refer to a common base.
+
+Define this base:
+
+<!-- @writeKustDev @helmtest -->
+```
+cat <<'EOF' >$DEMO_HOME/base/kustomization.yaml
+generators:
+- chartInflator.yaml
+EOF
+```
+
+The base refers to a generator configuration file
+called `chartInflator.yaml`.
+
+This file lets one specify the name of a [stable chart],
+and other things like a path to a values file, defaulting
+to the `values.yaml` that comes with the chart.
+
+Create the config file `chartInflator.yaml`, specifying
+the arbitrarily chosen chart name _minecraft_:
+
+<!-- @writeGeneratorConfig @helmtest -->
+```
+cat <<'EOF' >$DEMO_HOME/base/chartInflator.yaml
+apiVersion: someteam.example.com/v1
+kind: ChartInflator
+metadata:
+  name: notImportantHere
+chartName: minecraft
+EOF
+```
+
+Because this particular YAML file is listed in the
+`generators:` stanza of a kustomization file, it is
+treated as the binding between a generator plugin -
+identified by the _apiVersion_ and _kind_ fields - and
+other fields that configure the plugin.
+
+Download the plugin to your `DEMO_HOME` and make it
+executable:
+
+<!-- @installPlugin @helmtest -->
+```
+plugin=plugin/someteam.example.com/v1/chartinflator/ChartInflator
+curl -s --create-dirs -o \
+"$DEMO_HOME/kustomize/$plugin" \
+"https://raw.githubusercontent.com/\
+kubernetes-sigs/kustomize/master/$plugin"
+
+chmod a+x $DEMO_HOME/kustomize/$plugin
+```
+
+Check the directory layout:
+
+<!-- @tree -->
+```
+tree $DEMO_HOME
+```
+
+Expect something like:
+
+> ```
+> /tmp/whatever
+> ├── base
+> │   ├── chartInflator.yaml
+> │   └── kustomization.yaml
+> ├── dev
+> │   └── kustomization.yaml
+> ├── kustomize
+> │   └── plugin
+> │       └── someteam.example.com
+> │           └── v1
+> │               └── chartinflator
+> │                  └── ChartInflator
+> └── prod
+>    └── kustomization.yaml
+> ```
+
+Define a helper function to run kustomize with the
+correct environment and flags for plugins:
+
+<!-- @defineKustomizeIt @helmtest -->
+```
+function kustomizeIt {
+  XDG_CONFIG_HOME=$DEMO_HOME \
+  kustomize build --enable_alpha_plugins \
+    $DEMO_HOME/$1
+}
+```
+
+Finally, build the `prod` variant.  Notice that all
+resource  names now have the `prod-` prefix:
+
+<!-- @doProd @helmtest -->
+```
+clear
+kustomizeIt prod
+```
+
+Compare `dev` to `prod`:
+
+<!-- @doCompare -->
+```
+diff <(kustomizeIt dev) <(kustomizeIt prod) | more
+```
+
+To see the unmodified but inflated chart, run kustomize
+on the base.  Every invocation here is re-downloading
+and re-inflating the chart.
+
+<!-- @showBase @helmtest -->
+```
+kustomizeIt base
+```
+
+
+## Use a local chart
+
+The example above fetches a new copy of the chart
+to a temporary directory with each kustomize
+build, because a local chart home isn't specified
+in the configuration.
+
+To suppress fetching, specify a _chart home_
+explicitly, and just make sure the chart is already
+there.
+
+To demo this so that it won't interfere with your
+existing helm environment, do this:
+
+<!-- @helmInit @helmtest -->
+```
+helmHome=$DEMO_HOME/dothelm
+chartHome=$DEMO_HOME/base/charts
+
+function doHelm {
+  helm --home $helmHome $@
+}
+
+# Create helm config files in a new location.
+# The init command is extremely chatty
+doHelm init --client-only >& /dev/null
+```
+
+Now download a chart; again use _minecraft_
+(but you could use anything):
+
+<!-- @fetchChart @helmtest -->
+```
+doHelm fetch --untar \
+    --untardir $chartHome \
+    stable/minecraft
+```
+
+The tree has more stuff now; helm config data
+and a complete copy of the chart:
+<!-- @tree -->
+```
+tree $DEMO_HOME
+```
+
+
+Add a `chartHome` field to the generator config file so
+that it knows where to find the local chart:
+
+<!-- @modifyGenConfig @helmtest -->
+```
+echo "chartHome: $chartHome" >>$DEMO_HOME/base/chartInflator.yaml
+```
+
+Change the values file, to show that the results
+generated below are from the _locally_ stored chart:
+
+<!-- @valueChange @helmtest -->
+```
+sed -i 's/CHANGEME!/SOMETHINGELSE/' $chartHome/minecraft/values.yaml
+sed -i 's/LoadBalancer/NodePort/' $chartHome/minecraft/values.yaml
+```
+
+Finally, built it
+
+<!-- @finalProd @helmtest -->
+```
+kustomizeIt prod
+```
+
+and observe the change from `LoadBalancer` to `NodePort`, and 
+the change in the encoded password.

examples/combineConfigs.md

@@ -128,7 +128,7 @@ defined in the [helloworld] demo.
 
 It will all live in this work directory:
 
-<!-- @makeWorkplace @test -->
+<!-- @makeWorkplace @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 ```
@@ -139,7 +139,7 @@ DEMO_HOME=$(mktemp -d)
 
 Make a place to put the base configuration:
 
-<!-- @baseDir @test -->
+<!-- @baseDir @testAgainstLatestRelease -->
 ```
 mkdir -p $DEMO_HOME/base
 ```
@@ -150,7 +150,7 @@ environments. Here we're only defining a java
 properties file, and a `kustomization` file that
 references it.
 
-<!-- @baseKustomization @test -->
+<!-- @baseKustomization @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/base/common.properties
 color=blue
@@ -171,14 +171,14 @@ EOF
 Make an abbreviation for the parent of the overlay
 directories:
 
-<!-- @overlays @test -->
+<!-- @overlays @testAgainstLatestRelease -->
 ```
 OVERLAYS=$DEMO_HOME/overlays
 ```
 
 Create the files that define the _development_ overlay:
 
-<!-- @developmentFiles @test -->
+<!-- @developmentFiles @testAgainstLatestRelease -->
 ```
 mkdir -p $OVERLAYS/development
 
@@ -191,7 +191,7 @@ dbpassword=mothersMaidenName
 EOF
 
 cat <<EOF >$OVERLAYS/development/kustomization.yaml
-bases:
+resources:
 - ../../base
 namePrefix: dev-
 nameSuffix: -v1
@@ -206,7 +206,7 @@ EOF
 
 One can now generate the configMaps for development:
 
-<!-- @runDev @test -->
+<!-- @runDev @testAgainstLatestRelease -->
 ```
 kustomize build $OVERLAYS/development
 ```
@@ -260,7 +260,7 @@ deletes unused configMaps.
 Next, create the files for the _production_ overlay:
 
 
-<!-- @productionFiles @test -->
+<!-- @productionFiles @testAgainstLatestRelease -->
 ```
 mkdir -p $OVERLAYS/production
 
@@ -273,7 +273,7 @@ dbpassword=thisShouldProbablyBeInASecretInstead
 EOF
 
 cat <<EOF >$OVERLAYS/production/kustomization.yaml
-bases:
+resources:
 - ../../base
 namePrefix: prod-
 configMapGenerator:
@@ -287,7 +287,7 @@ EOF
 
 One can now generate the configMaps for production:
 
-<!-- @runProd @test -->
+<!-- @runProd @testAgainstLatestRelease -->
 ```
 kustomize build $OVERLAYS/production
 ```

examples/configGeneration.md

@@ -26,7 +26,7 @@ In this demo, the same [hello_world](helloWorld/README.md) is used while the Con
 ### Establish base and staging
 
 Establish the base with a configMapGenerator
-<!-- @establishBase @test -->
+<!-- @establishBase @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 
@@ -53,7 +53,7 @@ EOF
 ```
 
 Establish the staging with a patch applied to the ConfigMap
-<!-- @establishStaging @test -->
+<!-- @establishStaging @testAgainstLatestRelease -->
 ```
 OVERLAYS=$DEMO_HOME/overlays
 mkdir -p $OVERLAYS/staging
@@ -66,7 +66,7 @@ commonLabels:
   org: acmeCorporation
 commonAnnotations:
   note: Hello, I am staging!
-bases:
+resources:
 - ../../base
 patchesStrategicMerge:
 - map.yaml
@@ -91,7 +91,7 @@ configured with data from a configMap.
 The deployment refers to this map by name:
 
 
-<!-- @showDeployment @test -->
+<!-- @showDeployment @testAgainstLatestRelease -->
 ```
 grep -C 2 configMapKeyRef $BASE/deployment.yaml
 ```
@@ -117,7 +117,7 @@ collected](https://github.com/kubernetes-sigs/kustomize/issues/242).
 
 The _staging_ [variant] here has a configMap [patch]:
 
-<!-- @showMapPatch @test -->
+<!-- @showMapPatch @testAgainstLatestRelease -->
 ```
 cat $OVERLAYS/staging/map.yaml
 ```
@@ -128,7 +128,7 @@ resource spec.
 
 The ConfigMap it modifies is declared from a configMapGenerator.
 
-<!-- @showMapBase @test -->
+<!-- @showMapBase @testAgainstLatestRelease -->
 ```
 grep -C 4 configMapGenerator $BASE/kustomization.yaml
 ```
@@ -141,7 +141,7 @@ _not_ what gets used in the cluster.  By design,
 kustomize modifies names of ConfigMaps declared from ConfigMapGenerator.  To see the names
 ultimately used in the cluster, just run kustomize:
 
-<!-- @grepStagingName @test -->
+<!-- @grepStagingName @testAgainstLatestRelease -->
 ```
 kustomize build $OVERLAYS/staging |\
     grep -B 8 -A 1 staging-the-map
@@ -159,7 +159,7 @@ The suffix to the configMap name is generated from a
 hash of the maps content - in this case the name suffix
 is _k25m8k5k5m_:
 
-<!-- @grepStagingHash @test -->
+<!-- @grepStagingHash @testAgainstLatestRelease -->
 ```
 kustomize build $OVERLAYS/staging | grep k25m8k5k5m
 ```
@@ -167,7 +167,7 @@ kustomize build $OVERLAYS/staging | grep k25m8k5k5m
 Now modify the map patch, to change the greeting
 the server will use:
 
-<!-- @changeMap @test -->
+<!-- @changeMap @testAgainstLatestRelease -->
 ```
 sed -i.bak 's/pineapple/kiwi/' $OVERLAYS/staging/map.yaml
 ```
@@ -181,7 +181,7 @@ kustomize build $OVERLAYS/staging |\
 
 Run kustomize again to see the new configMap names:
 
-<!-- @grepStagingName @test -->
+<!-- @grepStagingName @testAgainstLatestRelease -->
 ```
 kustomize build $OVERLAYS/staging |\
     grep -B 8 -A 1 staging-the-map
@@ -192,7 +192,7 @@ in three new names ending in _cd7kdh48fd_ - one in the
 configMap name itself, and two in the deployment that
 uses the map:
 
-<!-- @countHashes @test -->
+<!-- @countHashes @testAgainstLatestRelease -->
 ```
 test 3 == \
   $(kustomize build $OVERLAYS/staging | grep cd7kdh48fd | wc -l); \

examples/configureBuiltinPlugin.md

@@ -0,0 +1,333 @@
+[builtin operations]: ../docs/plugins/builtins.md
+[builtin plugins]: ../docs/plugins/builtins.md
+[plugins]: ../docs/plugins
+[plugin]: ../docs/plugins
+[fields]: ../docs/fields.md
+[fields in a kustomization file]: ../docs/fields.md
+[TransformerConfig]: ../pkg/transformers/config/transformerconfig.go
+[kustomization]: ../docs/glossary.md#kustomization
+
+# Customizing kustomize
+
+The [fields in a kustomization file] allow the user to
+specify which resource files to use as input, how to
+_generate_ new resources, and how to _transform_ those
+resources - add labels, patch them, etc.
+
+These fields are simple (low argument count) directives.
+For example, the `commonAnnotations` field demands only a
+list of _name:value_ pairs.
+
+If using a field triggers behavior that pleases the user,
+everyone's happy.
+
+If not, the user can ask for new behavior to be implemented
+in kustomize proper (and wait), or the user can write a
+transformer or generator [plugin].  This latter option
+generally means writing code; a Go plugin, a Go binary,
+a C++ binary, a `bash` script - something.
+
+There's a third option.  If one merely wants to tweak
+behavior that already exists in kustomize, one may be able
+to do so by just writing some YAML.
+
+## Configure the builtin plugins
+
+All of kustomize's [builtin operations] are implemented 
+and usable as plugins.
+
+Using the fields is convenient and brief, but necessarily
+specifies only part of the entire plugin specification.  The
+unspecified part is defaulted to what are hopefully
+generally appealing values.
+
+If, instead, one invokes the plugins directly using the
+`transformers` or `generators` field, one can (indeed
+_must_) specify the entire plugin configuration.
+
+## Example: field vs plugin
+
+Define a place to work:
+
+<!-- @makeWorkplace @testAgainstLatestRelease -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+### Using the `commonLabels` and `commonAnnotations` fields
+ 
+In this simple example, we'll use just two resources: a deployment and a service.
+
+Define them:
+
+<!-- @makeRes1 @testAgainstLatestRelease -->
+```
+cat <<EOF >$DEMO_HOME/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deployment
+spec:
+  replicas: 10
+  template:
+    spec:
+      containers:
+      - name: the-container
+        image: monopole/hello:1
+EOF
+```
+
+<!-- @makeRes2 @testAgainstLatestRelease -->
+```
+cat <<EOF >$DEMO_HOME/service.yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: service
+spec:
+  type: LoadBalancer
+  ports:
+  - protocol: TCP
+    port: 8666
+    targetPort: 8080
+EOF
+```
+
+Now make a kustomization file that causes them
+to be read and transformed:
+
+<!-- @makeKustomization @testAgainstLatestRelease -->
+```
+cat <<'EOF' >$DEMO_HOME/kustomization.yaml
+namePrefix: hello-
+commonLabels:
+  app: hello
+commonAnnotations:
+  area: "51"
+  greeting: Take me to your leader
+resources:
+- deployment.yaml
+- service.yaml
+EOF
+```
+
+And run kustomize:
+
+<!-- @checkLabel @testAgainstLatestRelease -->
+```
+kustomize build $DEMO_HOME
+```
+
+The output will be something like
+
+> ```
+> apiVersion: v1
+> kind: Service
+> metadata:
+>   annotations:
+>     area: "51"
+>     greeting: Take me to your leader
+>   labels:
+>     app: hello
+>   name: hello-service
+> spec:
+>   ports:
+>   - port: 8666
+>     protocol: TCP
+>     targetPort: 8080
+>   selector:
+>     app: hello
+>   type: LoadBalancer
+> ---
+> apiVersion: apps/v1
+> kind: Deployment
+> metadata:
+>   annotations:
+>     area: "51"
+>     greeting: Take me to your leader
+>   labels:
+>     app: hello
+>   name: hello-deployment
+> spec:
+>   replicas: 10
+>   selector:
+>     matchLabels:
+>       app: hello
+>   template:
+>     metadata:
+>       annotations:
+>         area: "51"
+>         greeting: Take me to your leader
+>       labels:
+>         app: hello
+>     spec:
+>       containers:
+>       - image: monopole/hello:1
+>         name: the-container
+> ```
+
+Let's say we are unhappy with this result.
+
+We only want the annotations
+to be applied down in the pod templates,
+and don't want to see them in the metadata
+for Service or Deployment.
+
+We like that the label _app: hello_ ended up in
+
+ - Service `spec.selector`
+ - Deployment `spec.selector.matchLabels`
+ - Deployment `spec.template.metadata.labels`
+
+as this binds the Service (load balancer) to the pods,
+and the Deployment itself to its own pods -
+but we again don't care to see these labels in
+the metadata for the Service and the Deployment.
+
+
+### Configuring the builtin plugins instead
+
+To fine tune this, invoke the same transformations
+using the plugin approach.
+
+Change the kustomization file:
+
+<!-- @makeKustomization @testAgainstLatestRelease -->
+```
+cat <<'EOF' >$DEMO_HOME/kustomization.yaml
+namePrefix: hello-
+transformers:
+- myAnnotator.yaml
+- myLabeller.yaml
+resources:
+- deployment.yaml
+- service.yaml
+EOF
+```
+
+Then make the two plugin configuration files
+(`myAnnotator.yaml`, `myLabeller.yaml`)
+referred to by the `transformers` field above.
+For details about the fields to specify, see
+the documentation for the [builtin plugins].
+
+<!-- @makeAnnotatorPluginConfig @testAgainstLatestRelease -->
+```
+cat <<EOF >$DEMO_HOME/myAnnotator.yaml
+apiVersion: builtin
+kind: AnnotationsTransformer
+metadata:
+  name: notImportantHere
+annotations:
+  area: 51
+  greeting: take me to your leader
+fieldSpecs:
+- kind: Deployment
+  path: spec/template/metadata/annotations
+  create: true
+EOF
+```
+
+<!-- @makeLabelPluginConfig @testAgainstLatestRelease -->
+```
+cat <<EOF >$DEMO_HOME/myLabeller.yaml
+apiVersion: builtin
+kind: LabelTransformer
+metadata:
+  name: notImportantHere
+labels:
+  app: hello
+fieldSpecs:
+- kind: Service
+  path: spec/selector
+  create: true
+- kind: Deployment
+  path: spec/selector/matchLabels
+  create: true
+- kind: Deployment
+  path: spec/template/metadata/labels
+  create: true
+EOF
+```
+
+Finally, run kustomize again:
+
+<!-- @checkLabel @testAgainstLatestRelease -->
+```
+kustomize build $DEMO_HOME
+```
+
+The output should resemble the following,
+with fewer labels and annotations.
+
+> ```
+> apiVersion: v1
+> kind: Service
+> metadata:
+>   name: hello-service
+> spec:
+>   ports:
+>   - port: 8666
+>     protocol: TCP
+>     targetPort: 8080
+>   selector:
+>     app: hello
+>   type: LoadBalancer
+> ---
+> apiVersion: apps/v1
+> kind: Deployment
+> metadata:
+>   name: hello-deployment
+> spec:
+>   replicas: 10
+>   selector:
+>     matchLabels:
+>       app: hello
+>   template:
+>     metadata:
+>       annotations:
+>         area: "51"
+>         greeting: take me to your leader
+>       labels:
+>         app: hello
+>     spec:
+>       containers:
+>       - image: monopole/hello:1
+>         name: the-container
+> ```
+
+
+## The old way to do this
+
+The original (and still functional) way to customize
+kustomize is to specify a `configurations` field in the
+kustomization file.
+
+This field, normally omitted because it overrides hardcoded
+data, accepts a list of file path arguments.  The files, in
+turn, specify which fields in which k8s objects should be
+affected by particular builtin transformations.  It's a
+global configuration cutting across transformations, and
+doesn't effect generators at all.
+
+At `build` time, the configuration files are unmarshalled
+into one instance of [TransformerConfig].  This
+object, _plus_ the field values for `namePrefix`, etc.  are
+fed into the transformation code to build the output.
+
+The best way to write these custom configuration files is to
+generate the files from the hardcoded values built into
+kustomize via these commands:
+
+> ```
+> mkdir /tmp/junk
+> kustomize config save -d /tmp/junk
+> ```
+
+One can then edit those file or files, and specify the
+resulting edited files in a `configurations:`
+field in a kustomization file used in a `build`.
+
+Using plugins _completely ignores_ both hard coded
+tranformer configuration, and any configuration loaded by
+the `configuration` field.

examples/generatorOptions.md

@@ -13,7 +13,7 @@ DEMO_HOME=$(mktemp -d)
 
 Create a kustomization and add a ConfigMap generator to it.
 
-<!-- @createCMGenerator @test -->
+<!-- @createCMGenerator @testAgainstLatestRelease -->
 ```
 cat > $DEMO_HOME/kustomization.yaml << EOF
 configMapGenerator:
@@ -25,7 +25,7 @@ EOF
 ```
 
 Add following generatorOptions
-<!-- @addGeneratorOptions @test -->
+<!-- @addGeneratorOptions @testAgainstLatestRelease -->
 ```
 cat >> $DEMO_HOME/kustomization.yaml << EOF
 generatorOptions:
@@ -39,7 +39,7 @@ EOF
 Run `kustomize build` and make sure that the generated ConfigMap
  
  - doesn't have name suffix
-    <!-- @verify @test -->
+    <!-- @verify @testAgainstLatestRelease -->
     ```
     test 1 == \
     $(kustomize build $DEMO_HOME | grep "name: my-configmap$" | wc -l); \

examples/goGetterGeneratorPlugin.md

@@ -0,0 +1,132 @@
+# Remote Sources
+
+Kustomize supports building a [remote target], but the URLs are limited to common [Git repository specs].
+
+To extend the supported format, Kustomize has a [plugin] system that allows one to integrate third-party tools such as [hashicorp/go-getter] to "download things from a string URL suing a variety of protocols", extract the content and generated resources as part of kustomize build.
+
+[remote target]: https://github.com/kubernetes-sigs/kustomize/blob/master/examples/remoteBuild.md
+[Git repository specs]: https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/git/repospec_test.go
+[plugin]: ../docs/plugins
+[hashicorp/go-getter]: https://github.com/hashicorp/go-getter
+
+## Make a place to work
+
+<!-- @makeWorkplace @test -->
+```sh
+DEMO_HOME=$(mktemp -d)
+mkdir -p $DEMO_HOME/base
+```
+
+## Use a remote kustomize layer
+
+Define a kustomization representing your _local_ variant (aka environment).
+
+This could involve any number of kustomizations (see other examples), but in this case just add the name prefix `my-` to all resources:
+
+<!-- @writeKustLocal @test -->
+```sh
+cat <<'EOF' >$DEMO_HOME/kustomization.yaml
+namePrefix:  my-
+resources:
+- base/
+EOF
+```
+
+It refer a remote base defined as below:
+
+<!-- @writeKustLocal @test -->
+```sh
+cat <<'EOF' >$DEMO_HOME/base/kustomization.yaml
+generators:
+- goGetter.yaml
+EOF
+```
+
+The base refers to a generator configuration file called `goGetter.yaml`.
+
+This file lets one specify the source URL, and other things like sub path in the package, defaulting to base directory, and command to run under the path, defaulting to `kustomize build`.
+
+Create the config file `goGetter.yaml`, specifying the arbitrarily chosen name _example_:
+
+<!-- @writeGeneratorConfig @test -->
+```sh
+cat <<'EOF' >$DEMO_HOME/base/goGetter.yaml
+apiVersion: someteam.example.com/v1
+kind: GoGetter
+metadata:
+  name: example
+url: github.com/kustless/kustomize-examples.git
+EOF
+```
+
+Because this particular YAML file is listed in the `generators:` stanza of a kustomization file, it is treated as the binding between a generator plugin - identified by the _apiVersion_ and _kind_ fields - and other fields that configure the plugin.
+
+Download the plugin to your `DEMO_HOME` and make it executable:
+
+<!-- @installPlugin @test -->
+```sh
+plugin=plugin/someteam.example.com/v1/gogetter/GoGetter
+curl -s --create-dirs -o \
+"$DEMO_HOME/kustomize/$plugin" \
+"https://raw.githubusercontent.com/\
+kubernetes-sigs/kustomize/master/$plugin"
+
+chmod a+x $DEMO_HOME/kustomize/$plugin
+```
+
+Define a helper function to run kustomize with the correct environment and flags for plugins:
+
+<!-- @defineKustomizeIt @test -->
+```sh
+function kustomizeIt {
+  XDG_CONFIG_HOME=$DEMO_HOME \
+  kustomize build --enable_alpha_plugins \
+    $DEMO_HOME/$1
+}
+```
+
+Finally, build the local variant.  Notice that all
+resource  names now have the `my-` prefix:
+
+<!-- @doLocal @test -->
+```sh
+clear
+kustomizeIt
+```
+
+Compare local variant to remote base:
+
+<!-- @doCompare @test-->
+```sh
+diff <(kustomizeIt) <(kustomizeIt base) | more
+
+...
+<   name: my-remote-cm
+---
+>   name: remote-cm
+```
+
+To see the unmodified but extracted sources, run kustomize on the base.  Every invocation here is re-downloading and re-building the package.
+
+<!-- @showBase @test -->
+```sh
+kustomizeIt base
+```
+
+## Use non-kustomize remote sources
+
+Sometimes the remote sources does not include `kustomization.yaml`. To use that in the plugin, set command to override the default build.
+
+<!-- @setCommand @test -->
+```sh
+echo "command: cat resources.yaml" >>$DEMO_HOME/base/goGetter.yaml
+```
+
+Finally, built it
+
+<!-- @finalLocal @test -->
+```sh
+kustomizeIt
+```
+
+and observe the output includes raw `resources.yaml` instead of building result of remote `kustomization.yaml`.

examples/helloWorld/README.md

@@ -22,7 +22,7 @@ Steps:
 
 First define a place to work:
 
-<!-- @makeWorkplace @test -->
+<!-- @makeWorkplace @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 ```
@@ -44,7 +44,7 @@ To keep this document shorter, the base resources are
 off in a supplemental data directory rather than
 declared here as HERE documents.  Download them:
 
-<!-- @downloadBase @test -->
+<!-- @downloadBase @testAgainstLatestRelease -->
 ```
 BASE=$DEMO_HOME/base
 mkdir -p $BASE
@@ -57,7 +57,7 @@ curl -s -o "$BASE/#1.yaml" "https://raw.githubusercontent.com\
 
 Look at the directory:
 
-<!-- @runTree @test -->
+<!-- @runTree @testAgainstLatestRelease -->
 ```
 tree $DEMO_HOME
 ```
@@ -78,7 +78,7 @@ One could immediately apply these resources to a
 cluster:
 
 > ```
-> kubectl apply -f $DEMO_HOME/base
+> kubectl apply -k $DEMO_HOME/base
 > ```
 
 to instantiate the _hello_ service.  `kubectl`
@@ -88,7 +88,7 @@ would only recognize the resource files.
 
 The `base` directory has a [kustomization] file:
 
-<!-- @showKustomization @test -->
+<!-- @showKustomization @testAgainstLatestRelease -->
 ```
 more $BASE/kustomization.yaml
 ```
@@ -96,7 +96,7 @@ more $BASE/kustomization.yaml
 Optionally, run `kustomize` on the base to emit
 customized resources to `stdout`:
 
-<!-- @buildBase @test -->
+<!-- @buildBase @testAgainstLatestRelease -->
 ```
 kustomize build $BASE
 ```
@@ -106,14 +106,14 @@ kustomize build $BASE
 A first customization step could be to change the _app
 label_ applied to all resources:
 
-<!-- @addLabel @test -->
+<!-- @addLabel @testAgainstLatestRelease -->
 ```
 sed -i.bak 's/app: hello/app: my-hello/' \
     $BASE/kustomization.yaml
 ```
 
 See the effect:
-<!-- @checkLabel @test -->
+<!-- @checkLabel @testAgainstLatestRelease -->
 ```
 kustomize build $BASE | grep -C 3 app:
 ```
@@ -127,7 +127,7 @@ Create a _staging_ and _production_ [overlay]:
  * Web server greetings from these cluster
    [variants] will differ from each other.
 
-<!-- @overlayDirectories @test -->
+<!-- @overlayDirectories @testAgainstLatestRelease -->
 ```
 OVERLAYS=$DEMO_HOME/overlays
 mkdir -p $OVERLAYS/staging
@@ -139,7 +139,7 @@ mkdir -p $OVERLAYS/production
 In the `staging` directory, make a kustomization
 defining a new name prefix, and some different labels.
 
-<!-- @makeStagingKustomization @test -->
+<!-- @makeStagingKustomization @testAgainstLatestRelease -->
 ```
 cat <<'EOF' >$OVERLAYS/staging/kustomization.yaml
 namePrefix: staging-
@@ -148,7 +148,7 @@ commonLabels:
   org: acmeCorporation
 commonAnnotations:
   note: Hello, I am staging!
-bases:
+resources:
 - ../../base
 patchesStrategicMerge:
 - map.yaml
@@ -162,7 +162,7 @@ greeting from _Good Morning!_ to _Have a pineapple!_
 
 Also, enable the _risky_ flag.
 
-<!-- @stagingMap @test -->
+<!-- @stagingMap @testAgainstLatestRelease -->
 ```
 cat <<EOF >$OVERLAYS/staging/map.yaml
 apiVersion: v1
@@ -180,7 +180,7 @@ EOF
 In the production directory, make a kustomization
 with a different name prefix and labels.
 
-<!-- @makeProductionKustomization @test -->
+<!-- @makeProductionKustomization @testAgainstLatestRelease -->
 ```
 cat <<EOF >$OVERLAYS/production/kustomization.yaml
 namePrefix: production-
@@ -189,7 +189,7 @@ commonLabels:
   org: acmeCorporation
 commonAnnotations:
   note: Hello, I am production!
-bases:
+resources:
 - ../../base
 patchesStrategicMerge:
 - deployment.yaml
@@ -202,7 +202,7 @@ EOF
 Make a production patch that increases the replica
 count (because production takes more traffic).
 
-<!-- @productionDeployment @test -->
+<!-- @productionDeployment @testAgainstLatestRelease -->
 ```
 cat <<EOF >$OVERLAYS/production/deployment.yaml
 apiVersion: apps/v1
@@ -228,7 +228,7 @@ EOF
 
 Review the directory structure and differences:
 
-<!-- @listFiles @test -->
+<!-- @listFiles @testAgainstLatestRelease -->
 ```
 tree $DEMO_HOME
 ```
@@ -288,12 +288,12 @@ something like
 
 The individual resource sets are:
 
-<!-- @buildStaging @test -->
+<!-- @buildStaging @testAgainstLatestRelease -->
 ```
 kustomize build $OVERLAYS/staging
 ```
 
-<!-- @buildProduction @test -->
+<!-- @buildProduction @testAgainstLatestRelease -->
 ```
 kustomize build $OVERLAYS/production
 ```

examples/image.md

@@ -3,14 +3,14 @@
 
 Define a place to work:
 
-<!-- @makeWorkplace @test -->
+<!-- @makeWorkplace @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 ```
 
 Make a `kustomization` containing a pod resource
 
-<!-- @createKustomization @test -->
+<!-- @createKustomization @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/kustomization.yaml
 resources:
@@ -20,7 +20,7 @@ EOF
 
 Declare the pod resource
 
-<!-- @createDeployment @test -->
+<!-- @createDeployment @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/pod.yaml
 apiVersion: v1
@@ -46,7 +46,7 @@ The image `busybox` and tag `1.29.0` can be changed by adding `images` in `kusto
 
 
 Add `images`:
-<!-- @addImages @test -->
+<!-- @addImages @testAgainstLatestRelease -->
 ```
 cd $DEMO_HOME
 kustomize edit set image busybox=alpine:3.6
@@ -61,14 +61,14 @@ The following `images` will be added to `kustomization.yaml`:
 > ```
 
 Now build this `kustomization`
-<!-- @kustomizeBuild @test -->
+<!-- @kustomizeBuild @testAgainstLatestRelease -->
 ```
 kustomize build $DEMO_HOME
 ```
 
 Confirm that this replaces _both_ busybox images and tags for `alpine:3.6`:
 
-<!-- @confirmImages @test -->
+<!-- @confirmImages @testAgainstLatestRelease -->
 ```
 test 2 = \
   $(kustomize build $DEMO_HOME | grep alpine:3.6 | wc -l); \

examples/inlinePatch.md

@@ -0,0 +1,265 @@
+[Strategic Merge Patch]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md
+[JSON Patch]: https://tools.ietf.org/html/rfc6902
+
+# Demo: Inline Patch
+
+A kustomization file supports patching in three ways:
+- patchesStrategicMerge: A list of patch files where each file is parsed as a [Stragetic Merge Patch].
+- patchesJSON6902: A list of patches and associated targetes, where each file is parsed as a [JSON Patch] and can only be applied to one target resource.
+- patches: A list of patches and their associated targets. The patch can be applied to multiple objects. It auto detects whether the patch is a [Strategic Merge Patch] or [JSON Patch].
+
+Since 3.2.0, all three support inline patch, where the patch content is put inside the kustomization file as a single string. With this feature, no separate patch files need to be created.
+
+Make a base kustomization containing a Deployment resource.
+<!-- @createKustomization @test -->
+```
+DEMO_HOME=$(mktemp -d)
+
+BASE=$DEMO_HOME/base
+mkdir $BASE
+
+cat <<EOF >$BASE/kustomization.yaml
+resources:
+- deployments.yaml
+EOF
+
+cat <<EOF >$BASE/deployments.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy
+spec:
+  template:
+    metadata:
+      labels:
+        foo: bar
+    spec:
+      containers:
+        - name: nginx
+          image: nginx
+          args:
+          - one
+          - two
+EOF
+```
+
+
+## Inline Patch for PatchesStrategicMerge
+
+Create an overlay and add an inline patch in `patchesStrategicMerge` field to the kustomization file
+to change the image from `nginx` to `nginx:latest`.
+
+<!-- @addSMPatch @test -->
+```
+SMP_OVERLAY=$DEMO_HOME/smp
+mkdir $SMP_OVERLAY
+cat <<EOF >$SMP_OVERLAY/kustomization.yaml
+resources:
+- ../base
+
+patchesStrategicMerge:
+- |-
+  apiVersion: apps/v1
+  kind: Deployment
+  metadata:
+    name: deploy
+  spec:
+    template:
+      spec:
+        containers:
+        - name: nginx
+          image: nginx:latest
+          
+EOF
+```
+
+Running `kustomize build $SMP_OVERLAY`, in the output confirm that image is updated successfully.
+
+<!-- @confirmSMPatch @test -->
+```
+test 1 == \
+  $(kustomize build $SMP_OVERLAY | grep "image: nginx:latest" | wc -l); \
+  echo $?
+```
+
+The output is
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy
+spec:
+  template:
+    metadata:
+      labels:
+        foo: bar
+    spec:
+      containers:
+        - name: nginx
+          image: nginx:latest
+          args:
+          - one
+          - two
+```
+
+`$patch: delete` and `$patch: replace` also work in the inline patch. Change the inline patch to delete the container `nginx`.
+
+<!-- @addDeleteSMPatch @test -->
+```
+cat <<EOF >$SMP_OVERLAY/kustomization.yaml
+resources:
+- ../base
+
+patchesStrategicMerge:
+- |-
+  apiVersion: apps/v1
+  kind: Deployment
+  metadata:
+    name: deploy
+  spec:
+    template:
+      spec:
+        containers:
+        - name: nginx
+          $patch: delete
+          
+EOF
+```
+Running `kustomize build $SMP_OVERLAY`, in the output confirm that the `nginx` container has been deleted.
+
+<!-- @confirmDeleteSMPatch @test -->
+```
+test 0 == \
+  $(kustomize build $SMP_OVERLAY | grep "image: nginx" | wc -l); \
+  echo $?
+```
+
+The output is
+```
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy
+spec:
+  template:
+    metadata:
+      labels:
+        foo: bar
+    spec:
+      containers: []
+```
+
+## Inline Patch for PatchesJson6902
+
+Create an overlay and add an inline patch in `patchesJSON6902` field to the kustomization file
+to change the image from `nginx` to `nginx:latest`.
+
+<!-- @addJSONPatch @test -->
+```
+JSON_OVERLAY=$DEMO_HOME/json
+mkdir $JSON_OVERLAY
+cat <<EOF >$JSON_OVERLAY/kustomization.yaml
+resources:
+- ../base
+
+patchesJSON6902:
+- target:
+    group: apps
+    version: v1
+    kind: Deployment
+    name: deploy
+  patch: |-
+    - op: replace
+      path: /spec/template/spec/containers/0/image
+      value: nginx:latest
+EOF
+```
+
+Running `kustomize build $JSON_OVERLAY`, in the output confirm that image is updated successfully.
+
+<!-- @confirmJSONPatch @test -->
+```
+test 1 == \
+  $(kustomize build $JSON_OVERLAY | grep "image: nginx:latest" | wc -l); \
+  echo $?
+```
+
+The output is
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy
+spec:
+  template:
+    metadata:
+      labels:
+        foo: bar
+    spec:
+      containers:
+        - name: nginx
+          image: nginx:latest
+          args:
+          - one
+          - two
+```
+
+## Inline Patch for Patches
+
+Create an overlay and add an inline patch in `patches` field to the kustomization file
+to change the image from `nginx` to `nginx:latest`.
+
+<!-- @addPatch @test -->
+```
+PATCH_OVERLAY=$DEMO_HOME/patch
+mkdir $PATCH_OVERLAY
+cat <<EOF > $PATCH_OVERLAY/kustomization.yaml
+resources:
+- ../base
+
+patches:
+- target:
+    kind: Deployment
+    name: deploy
+  patch: |-
+    apiVersion: apps/v1
+    kind: Deployment
+    metadata:
+      name: deploy
+    spec:
+      template:
+        spec:
+          containers:
+          - name: nginx
+            image: nginx:latest
+EOF
+```
+
+Running `kustomize build $PATCH_OVERLAY`, in the output confirm that image is updated successfully.
+
+<!-- @confirmPatch @test -->
+```
+test 1 == \
+  $(kustomize build $PATCH_OVERLAY | grep "image: nginx:latest" | wc -l); \
+  echo $?
+```
+
+The output is
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy
+spec:
+  template:
+    metadata:
+      labels:
+        foo: bar
+    spec:
+      containers:
+        - name: nginx
+          image: nginx:latest
+          args:
+          - one
+          - two
+```

examples/integration_tests.sh

@@ -28,7 +28,7 @@
 # before running it.
 #
 # At time of writing, its 'call point' was in
-# https://github.com/kubernetes/test-infra/blob/master/jobs/config.json
+# https://github.com/kubernetes/test-infra/blob/master/config/jobs/kubernetes-sigs/kustomize/kustomize-config.yaml
 
 function exitWith {
   local msg=$1
@@ -53,7 +53,7 @@ function setUpEnv {
     exitWith "Script must be run from $expectedRepo"
   fi
 
-  go install . || \
+  GO111MODULE=on go install ./cmd/kustomize || \
     { exitWith "Failed to install kustomize."; }
 
   PATH=$GOPATH/bin:$PATH

examples/jsonpatch.md

@@ -6,7 +6,7 @@ The example below modifies an `Ingress` object with such a patch.
 
 Make a `kustomization` containing an ingress resource.
 
-<!-- @createIngress @test -->
+<!-- @createIngress @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 
@@ -16,7 +16,7 @@ resources:
 EOF
 
 cat <<EOF >$DEMO_HOME/ingress.yaml
-apiVersion: extensions/v1beta1
+apiVersion: networking.k8s.io/v1beta1
 kind: Ingress
 metadata:
   name: my-ingress
@@ -36,7 +36,7 @@ Declare a JSON patch file to update two fields of the Ingress object:
 - change host from `foo.bar.com` to `foo.bar.io`
 - change servicePort from `80` to `8080`
 
-<!-- @addJsonPatch @test -->
+<!-- @addJsonPatch @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/ingress_patch.json
 [
@@ -48,7 +48,7 @@ EOF
 
 You can also write the patch in YAML format. This example also shows the "add" operation:
 
-<!-- @addYamlPatch @test -->
+<!-- @addYamlPatch @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/ingress_patch.yaml
 - op: replace
@@ -67,12 +67,12 @@ EOF
 
 Apply the patch by adding _patchesJson6902_ field in kustomization.yaml
 
-<!-- @applyJsonPatch @test -->
+<!-- @applyJsonPatch @testAgainstLatestRelease -->
 ```
 cat <<EOF >>$DEMO_HOME/kustomization.yaml
 patchesJson6902:
 - target:
-    group: extensions
+    group: networking.k8s.io
     version: v1beta1
     kind: Ingress
     name: my-ingress
@@ -81,14 +81,14 @@ EOF
 ```
 
 Running `kustomize build $DEMO_HOME`, in the output confirm that host has been updated correctly.
-<!-- @confirmHost @test -->
+<!-- @confirmHost @testAgainstLatestRelease -->
 ```
 test 1 == \
   $(kustomize build $DEMO_HOME | grep "host: foo.bar.io" | wc -l); \
   echo $?
 ```
 Running `kustomize build $DEMO_HOME`, in the output confirm that the servicePort has been updated correctly.
-<!-- @confirmServicePort @test -->
+<!-- @confirmServicePort @testAgainstLatestRelease -->
 ```
 test 1 == \
   $(kustomize build $DEMO_HOME | grep "servicePort: 8080" | wc -l); \
@@ -97,12 +97,12 @@ test 1 == \
 
 If the patch is YAML-formatted, it will be parsed correctly:
 
-<!-- @applyYamlPatch @test -->
+<!-- @applyYamlPatch @testAgainstLatestRelease -->
 ```
 cat <<EOF >>$DEMO_HOME/kustomization.yaml
 patchesJson6902:
 - target:
-    group: extensions
+    group: networking.k8s.io
     version: v1beta1
     kind: Ingress
     name: my-ingress
@@ -110,7 +110,7 @@ patchesJson6902:
 EOF
 ```
 
-<!-- @confirmYamlPatch @test -->
+<!-- @confirmYamlPatch @testAgainstLatestRelease -->
 ```
 test 1 == \
   $(kustomize build $DEMO_HOME | grep "path: /test" | wc -l); \

examples/ldap/README.md

@@ -18,7 +18,7 @@ Steps:
 
 First define a place to work:
 
-<!-- @makeWorkplace @test -->
+<!-- @makeWorkplace @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 ```
@@ -38,7 +38,7 @@ To keep this document shorter, the base resources are
 off in a supplemental data directory rather than
 declared here as HERE documents.  Download them:
 
-<!-- @downloadBase @test -->
+<!-- @downloadBase @testAgainstLatestRelease -->
 ```
 BASE=$DEMO_HOME/base
 mkdir -p $BASE
@@ -53,7 +53,7 @@ curl -s -o "$BASE/#1" "$CONTENT/base\
 
 Look at the directory:
 
-<!-- @runTree @test -->
+<!-- @runTree @testAgainstLatestRelease -->
 ```
 tree $DEMO_HOME
 ```
@@ -84,7 +84,7 @@ would only recognize the resource files.
 
 The `base` directory has a [kustomization] file:
 
-<!-- @showKustomization @test -->
+<!-- @showKustomization @testAgainstLatestRelease -->
 ```
 more $BASE/kustomization.yaml
 ```
@@ -92,7 +92,7 @@ more $BASE/kustomization.yaml
 Optionally, run `kustomize` on the base to emit
 customized resources to `stdout`:
 
-<!-- @buildBase @test -->
+<!-- @buildBase @testAgainstLatestRelease -->
 ```
 kustomize build $BASE
 ```
@@ -101,14 +101,14 @@ kustomize build $BASE
 
 A first customization step could be to set the name prefix to all resources:
 
-<!-- @namePrefix @test -->
+<!-- @namePrefix @testAgainstLatestRelease -->
 ```
 cd $BASE
 kustomize edit set nameprefix "my-"
 ```
 
 See the effect:
-<!-- @checkNameprefix @test -->
+<!-- @checkNameprefix @testAgainstLatestRelease -->
 ```
 kustomize build $BASE | grep -C 3 "my-"
 ```
@@ -121,7 +121,7 @@ Create a _staging_ and _production_ [overlay]:
  * _Production_ has a higher replica count and a persistent disk.
  * [variants] will differ from each other.
 
-<!-- @overlayDirectories @test -->
+<!-- @overlayDirectories @testAgainstLatestRelease -->
 ```
 OVERLAYS=$DEMO_HOME/overlays
 mkdir -p $OVERLAYS/staging
@@ -132,7 +132,7 @@ mkdir -p $OVERLAYS/production
 
 Download the staging customization and patch.
 
-<!-- @downloadStagingKustomization @test -->
+<!-- @downloadStagingKustomization @testAgainstLatestRelease -->
 ```
 curl -s -o "$OVERLAYS/staging/#1" "$CONTENT/overlays/staging\
 /{config.env,deployment.yaml,kustomization.yaml}"
@@ -159,7 +159,7 @@ as well as 2 replica
 #### Production Kustomization
 
 Download the production customization and patch.
-<!-- @downloadProductionKustomization @test -->
+<!-- @downloadProductionKustomization @testAgainstLatestRelease -->
 ```
 curl -s -o "$OVERLAYS/production/#1" "$CONTENT/overlays/production\
 /{deployment.yaml,kustomization.yaml}"
@@ -196,7 +196,7 @@ The production customization adds 6 replica as well as a consistent disk.
 
 Review the directory structure and differences:
 
-<!-- @listFiles @test -->
+<!-- @listFiles @testAgainstLatestRelease -->
 ```
 tree $DEMO_HOME
 ```
@@ -258,12 +258,12 @@ The difference output should look something like
 
 The individual resource sets are:
 
-<!-- @buildStaging @test -->
+<!-- @buildStaging @testAgainstLatestRelease -->
 ```
 kustomize build $OVERLAYS/staging
 ```
 
-<!-- @buildProduction @test -->
+<!-- @buildProduction @testAgainstLatestRelease -->
 ```
 kustomize build $OVERLAYS/production
 ```

examples/ldap/overlays/production/kustomization.yaml

@@ -1,4 +1,4 @@
-bases:
+resources:
   - ../../base
 patchesStrategicMerge:
   - deployment.yaml

examples/ldap/overlays/staging/kustomization.yaml

@@ -1,9 +1,9 @@
-bases:
-  - ../../base
+resources:
+- ../../base
 patchesStrategicMerge:
-  - deployment.yaml
-nameprefix: staging-
+ - deployment.yaml
+namePrefix: staging-
 configMapGenerator:
-  - name: env-config
-    files:
-      - config.env
+- name: env-config
+  files:
+  - config.env

examples/multibases/README.md

@@ -1,22 +1,32 @@
 # Demo: multibases with a common base
 
-`kustomize` encourages defining multiple variants - e.g. dev, staging and prod, as overlays on a common base.
+`kustomize` encourages defining multiple variants -
+e.g. dev, staging and prod,
+as overlays on a common base.
 
-It's possible to create an additional overlay to compose these variants together - just declare the overlays as the bases of a new kustomization.
+It's possible to create an additional overlay to
+compose these variants together - just declare the
+overlays as the bases of a new kustomization.
 
-This is also a means to apply a common label or annotation across the variants, if for some reason the base isn't under your control. It also allows one to define a left-most namePrefix across the variants - something that cannot be done by modifying the common base.
+This is also a means to apply a common label or
+annotation across the variants, if for some reason
+the base isn't under your control. It also allows
+one to define a left-most namePrefix across the
+variants - something that cannot be
+done by modifying the common base.
 
-The following demonstrates this using a base that's just one pod.
+The following demonstrates this using a base
+that is just a single pod.
 
 Define a place to work:
 
-<!-- @makeWorkplace @test -->
+<!-- @makeWorkplace @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 ```
 
 Define a common base:
-<!-- @makeBase @test -->
+<!-- @makeBase @testAgainstLatestRelease -->
 ```
 BASE=$DEMO_HOME/base
 mkdir $BASE
@@ -41,49 +51,49 @@ EOF
 ```
 
 Define a dev variant overlaying base:
-<!-- @makeDev @test -->
+<!-- @makeDev @testAgainstLatestRelease -->
 ```
 DEV=$DEMO_HOME/dev
 mkdir $DEV
 
 cat <<EOF >$DEV/kustomization.yaml
-bases:
+resources:
 - ./../base
 namePrefix: dev-
 EOF
 ```
 
 Define a staging variant overlaying base:
-<!-- @makeStaging @test -->
+<!-- @makeStaging @testAgainstLatestRelease -->
 ```
 STAG=$DEMO_HOME/staging
 mkdir $STAG
 
 cat <<EOF >$STAG/kustomization.yaml
-bases:
+resources:
 - ./../base
 namePrefix: stag-
 EOF
 ```
 
 Define a production variant overlaying base:
-<!-- @makeProd @test -->
+<!-- @makeProd @testAgainstLatestRelease -->
 ```
 PROD=$DEMO_HOME/production
 mkdir $PROD
 
 cat <<EOF >$PROD/kustomization.yaml
-bases:
+resources:
 - ./../base
 namePrefix: prod-
 EOF
 ```
 
 Then define a _Kustomization_ composing three variants together:
-<!-- @makeTopLayer @test -->
+<!-- @makeTopLayer @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/kustomization.yaml
-bases:
+resources:
 - ./dev
 - ./staging
 - ./production
@@ -109,7 +119,7 @@ Now the workspace has following directories
 
 Confirm that the `kustomize build` output contains three pod objects from dev, staging and production variants.
 
-<!-- @confirmVariants @test -->
+<!-- @confirmVariants @testAgainstLatestRelease -->
 ```
 test 1 == \
   $(kustomize build $DEMO_HOME | grep cluster-a-dev-myapp-pod | wc -l); \

examples/multibases/dev/kustomization.yaml

@@ -1,4 +1,3 @@
-bases:
-- ./../base
-
-namePrefix: dev-
+resources:
+- ../base
+namePrefix: dev-

examples/multibases/kustomization.yaml

@@ -1,6 +1,5 @@
-bases:
-- ./dev
-- ./staging
-- ./production
-
+resources:
+- dev
+- staging
+- production
 namePrefix: cluster-a-

examples/multibases/multi-namespace.md

@@ -2,17 +2,19 @@
 
 `kustomize` supports defining multiple variants with different namespace, as overlays on a common base.
 
-It's possible to create an additional overlay to compose these variants together - just declare the overlays as the bases of a new kustomization. The following demonstrates this using a base that's just one pod.
+It's possible to create an additional overlay to compose these variants
+together - just declare the overlays as the bases of a new kustomization. The
+following demonstrates this using a base that's just one pod.
 
 Define a place to work:
 
-<!-- @makeWorkplace @test -->
+<!-- @makeWorkplace @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 ```
 
 Define a common base:
-<!-- @makeBase @test -->
+<!-- @makeBase @testAgainstLatestRelease -->
 ```
 BASE=$DEMO_HOME/base
 mkdir $BASE
@@ -37,16 +39,15 @@ EOF
 ```
 
 Define a variant in namespace-a overlaying base:
-<!-- @makeNamespaceA @test -->
+<!-- @makeNamespaceA @testAgainstLatestRelease -->
 ```
 NSA=$DEMO_HOME/namespace-a
 mkdir $NSA
 
 cat <<EOF >$NSA/kustomization.yaml
-bases:
-- ./../base
 resources:
 - namespace.yaml
+- ../base
 namespace: namespace-a
 EOF
 
@@ -59,16 +60,15 @@ EOF
 ```
 
 Define a variant in namespace-b overlaying base:
-<!-- @makeNamespaceB @test -->
+<!-- @makeNamespaceB @testAgainstLatestRelease -->
 ```
 NSB=$DEMO_HOME/namespace-b
 mkdir $NSB
 
 cat <<EOF >$NSB/kustomization.yaml
-bases:
-- ./../base
 resources:
 - namespace.yaml
+- ../base
 namespace: namespace-b
 EOF
 
@@ -81,12 +81,12 @@ EOF
 ```
 
 Then define a _Kustomization_ composing two variants together:
-<!-- @makeTopLayer @test -->
+<!-- @makeTopLayer @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/kustomization.yaml
-bases:
-- ./namespace-a
-- ./namespace-b
+resources:
+- namespace-a
+- namespace-b
 EOF
 ```
 
@@ -107,9 +107,9 @@ Now the workspace has following directories
 
 Confirm that the `kustomize build` output contains two pod objects from namespace-a and namespace-b.
 
-<!-- @confirmVariants @test -->
+<!-- @confirmVariants @testAgainstLatestRelease -->
 ```
 test 2 == \
   $(kustomize build $DEMO_HOME| grep -B 4 "namespace: namespace-[ab]" | grep "name: myapp-pod" | wc -l); \
   echo $?  
-```
+```

examples/multibases/production/kustomization.yaml

@@ -1,4 +1,3 @@
-bases:
-- ./../base
-
+resources:
+- ../base
 namePrefix: prod-

examples/multibases/staging/kustomization.yaml

@@ -1,4 +1,3 @@
-bases:
-- ./../base
-
+resources:
+- ../base
 namePrefix: staging-

examples/mySql/README.md

@@ -11,7 +11,7 @@ In the production environment we want:
 - MySQL to use persistent disk for storing data.
 
 First make a place to work:
-<!-- @makeDemoHome @test -->
+<!-- @makeDemoHome @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 ```
@@ -25,7 +25,7 @@ as HERE documents.
 
 Download them:
 
-<!-- @downloadResources @test -->
+<!-- @downloadResources @testAgainstLatestRelease -->
 ```
 curl -s  -o "$DEMO_HOME/#1.yaml" "https://raw.githubusercontent.com\
 /kubernetes-sigs/kustomize\
@@ -40,14 +40,14 @@ a file called `kustomization.yaml`.
 
 Start this file:
 
-<!-- @kustomizeYaml @test -->
+<!-- @kustomizeYaml @testAgainstLatestRelease -->
 ```
 touch $DEMO_HOME/kustomization.yaml
 ```
 
 ### Add the resources
 
-<!-- @addResources @test -->
+<!-- @addResources @testAgainstLatestRelease -->
 ```
 cd $DEMO_HOME
 
@@ -73,7 +73,7 @@ Arrange for the MySQL resources to begin with prefix
 _prod-_ (since they are meant for the _production_
 environment):
 
-<!-- @customizeLabel @test -->
+<!-- @customizeLabel @testAgainstLatestRelease -->
 ```
 cd $DEMO_HOME
 
@@ -91,7 +91,7 @@ cat kustomization.yaml
 This `namePrefix` directive adds _prod-_ to all
 resource names.
 
-<!-- @genNamePrefixConfig @test -->
+<!-- @genNamePrefixConfig @testAgainstLatestRelease -->
 ```
 kustomize build $DEMO_HOME
 ```
@@ -134,7 +134,7 @@ selector.
 `kustomize` does not have `edit set label` command to add
 a label, but one can always edit `kustomization.yaml` directly:
 
-<!-- @customizeLabels @test -->
+<!-- @customizeLabels @testAgainstLatestRelease -->
 ```
 sed -i.bak 's/app: helloworld/app: prod/' \
     $DEMO_HOME/kustomization.yaml
@@ -153,7 +153,7 @@ environment. So we want to use Persistent Disk in
 production. kustomize lets you apply `patchesStrategicMerge` to the
 resources.
 
-<!-- @createPatchFile @test -->
+<!-- @createPatchFile @testAgainstLatestRelease -->
 ```
 cat <<'EOF' > $DEMO_HOME/persistent-disk.yaml
 apiVersion: apps/v1beta2 # for versions before 1.9.0 use apps/v1beta2
@@ -173,7 +173,7 @@ EOF
 
 Add the patch file to `kustomization.yaml`:
 
-<!-- @specifyPatch @test -->
+<!-- @specifyPatch @testAgainstLatestRelease -->
 ```
 cat <<'EOF' >> $DEMO_HOME/kustomization.yaml
 patchesStrategicMerge:
@@ -199,7 +199,7 @@ The output of the following command can now be applied
 to the cluster (i.e. piped to `kubectl apply`) to
 create the production environment.
 
-<!-- @finalInflation @test -->
+<!-- @finalInflation @testAgainstLatestRelease -->
 ```
 kustomize build $DEMO_HOME  # | kubectl apply -f -
 ```

examples/patchMultipleObjects.md

@@ -0,0 +1,188 @@
+[Strategic Merge Patch]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md
+[JSON patches]: https://tools.ietf.org/html/rfc6902
+[label selector]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
+
+
+# Demo: applying a patch to multiple resources
+
+A kustomization file supports customizing resources via both
+[Strategic Merge Patch] and [JSON patches]. Now one patch can be
+applied to multiple resources.
+
+This can be done by specifying a patch and a target selector as follows:
+```
+patches:
+- path: <PatchFile>
+  target:
+    group: <Group>
+    version: <Version>
+    kind: <Kind>
+    name: <Name>
+    namespace: <Namespace>
+    labelSelector: <LabelSelector>
+    annotationSelector: <AnnotationSelector>
+```
+Both `labelSelector` and `annotationSelector` should follow the convention in [label selector].
+Kustomize selects the targets which match all the fields in `target` to apply the patch.
+
+The example below shows how to inject a sidecar container for all deployment resources.
+
+Make a `kustomization` containing a Deployment resource.
+
+<!-- @createDeployment @testAgainstLatestRelease -->
+```
+DEMO_HOME=$(mktemp -d)
+
+cat <<EOF >$DEMO_HOME/kustomization.yaml
+resources:
+- deployments.yaml
+EOF
+
+cat <<EOF >$DEMO_HOME/deployments.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy1
+spec:
+  template:
+    metadata:
+      labels:
+        old-label: old-value
+    spec:
+      containers:
+        - name: nginx
+          image: nginx
+          args:
+          - one
+          - two
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy2
+spec:
+  template:
+    metadata:
+      labels:
+        key: value
+    spec:
+      containers:
+        - name: busybox
+          image: busybox
+EOF
+```
+
+Declare a Strategic Merge Patch file to inject a sidecar container:
+
+<!-- @addPatch @testAgainstLatestRelease -->
+```
+cat <<EOF >$DEMO_HOME/patch.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: not-important
+spec:
+  template:
+    spec:
+      containers:
+        - name: istio-proxy
+          image: docker.io/istio/proxyv2
+          args:
+          - proxy
+          - sidecar
+EOF
+```
+
+Apply the patch by adding _patches_ field in kustomization.yaml
+
+<!-- @applyPatch @testAgainstLatestRelease -->
+```
+cat <<EOF >>$DEMO_HOME/kustomization.yaml
+patches:
+- path: patch.yaml
+  target:
+    kind: Deployment
+EOF
+```
+
+Running `kustomize build $DEMO_HOME`, in the output confirm that both Deployment resources are patched correctly.
+
+<!-- @confirmPatch @testAgainstLatestRelease -->
+```
+test 2 == \
+  $(kustomize build $DEMO_HOME | grep "image: docker.io/istio/proxyv2" | wc -l); \
+  echo $?
+```
+
+The output is as follows:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy1
+spec:
+  template:
+    metadata:
+      labels:
+        old-label: old-value
+    spec:
+      containers:
+      - args:
+        - proxy
+        - sidecar
+        image: docker.io/istio/proxyv2
+        name: istio-proxy
+      - args:
+        - one
+        - two
+        image: nginx
+        name: nginx
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy2
+spec:
+  template:
+    metadata:
+      labels:
+        key: value
+    spec:
+      containers:
+      - args:
+        - proxy
+        - sidecar
+        image: docker.io/istio/proxyv2
+        name: istio-proxy
+      - image: busybox
+        name: busybox
+```
+
+## Target selector
+- Select resources with name matching `name*`
+  ```yaml
+  target:
+    name: name*
+  ```
+- Select all Deployment resources
+  ```yaml
+  target:
+    kind: Deployment
+  ```
+- Select resources matching label `app=hello`
+  ```yaml
+  target:
+    labelSelector: app=hello
+  ```
+- Select resources matching annotation `app=hello`
+  ```yaml
+  target:
+    annotationSelector: app=hello
+  ```
+- Select all Deployment resources matching label `app=hello`
+  ```yaml
+  target:
+    kind: Deployment
+    labelSelector: app=hello
+  ```

examples/remoteBuild.md

@@ -1,46 +1,54 @@
 # remote targets
 
-`kustomize build` can be run against a url. The effect is the same as cloing the repo, checking out the specified ref,
-then running `kustomize build` against the desired directory in the local copy.
+`kustomize build` can be run on a URL.
 
-Take `github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6` as an example.
-According to [multibases](multibases/README.md) demo, this kustomization contains three Pod objects with names as
-`cluster-a-dev-myapp-pod`, `cluster-a-stag-myapp-pod`, `cluster-a-prod-myapp-pod`.
-Running `kustomize build` against the url gives the same output.
+The effect is the same as cloning the repo, checking out a particular
+_ref_ (commit hash, branch name, release tag, etc.),
+then running `kustomize build` against the desired
+directory in the local copy.
+
+To try this immediately, run a build against the kustomization
+in the [multibases](multibases/README.md) example.  There's
+one pod in the output:
+
+<!-- @remoteOverlayBuild @testAgainstLatestRelease -->
 
-<!-- @remoteBuild @test -->
 ```
-target=github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6
+target="github.com/kubernetes-sigs/kustomize//examples/multibases/dev/?ref=v1.0.6"
+test 1 == \
+  $(kustomize build $target | grep dev-myapp-pod | wc -l); \
+  echo $?
+```
+
+Run against the overlay in that example to get three pods
+(the overlay combines the dev, staging and prod bases for
+someone who wants to send them all at the same time):
+
+<!-- @remoteBuild @testAgainstLatestRelease -->
+```
+target="https://github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6"
 test 3 == \
   $(kustomize build $target | grep cluster-a-.*-myapp-pod | wc -l); \
   echo $?
 ```
 
-Overlays can be remote as well:
+A base can be a URL:
 
-<!-- @remoteOverlayBuild @test -->
-
-```
-target=github.com/kubernetes-sigs/kustomize//examples/multibases/dev/?ref=v1.0.6
-test 1 == \
-  $(kustomize build $target | grep cluster-a-dev-myapp-pod | wc -l); \
-  echo $?
-```
-
-A base can also be specified as a URL:
-
-<!-- @createOverlay @test -->
+<!-- @createOverlay @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 
 cat <<EOF >$DEMO_HOME/kustomization.yaml
-bases:
+resources:
 - github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6
 namePrefix: remote-
 EOF
 ```
-Running `kustomize build $DEMO_HOME` and confirm the output contains three Pods and all have `remote-` prefix.
-<!-- @remoteBases @test -->
+
+Build this to confirm that all three pods from the base
+have the `remote-` prefix.
+
+<!-- @remoteBases @testAgainstLatestRelease -->
 ```
 test 3 == \
   $(kustomize build $DEMO_HOME | grep remote-.*-myapp-pod | wc -l); \
@@ -48,6 +56,7 @@ test 3 == \
 ```
 
 ## URL format
+
 The url should follow
 [hashicorp/go-getter URL format](https://github.com/hashicorp/go-getter#url-format).
 Here are some example urls pointing to Github repos following this convention.

examples/secretGeneratorPlugin.md

@@ -0,0 +1,221 @@
+[ConfigMaps]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#configmap-v1-core
+[ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format
+[Go plugin]: https://golang.org/pkg/plugin
+[Secrets]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#secret-v1-core
+[base64]: https://tools.ietf.org/html/rfc4648#section-4
+[configuration directory]: https://wiki.archlinux.org/index.php/XDG_Base_Directory#Specification
+[grpc]: https://grpc.io
+[tag]: https://github.com/kubernetes-sigs/kustomize/releases
+[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.0.3
+[`exec.Command`]: https://golang.org/pkg/os/exec/#Command
+
+# Generating Secrets
+
+## What's a Secret?
+
+Kubernetes [ConfigMaps] and [Secrets] are both
+key:value maps, but the latter is intended to
+signal that its values have a sensitive nature -
+e.g. pass phrases or ssh keys.
+
+Kubernetes developers work in various ways to hide
+the information in a Secret more carefully than
+the information held by ConfigMaps, Deployments,
+etc.
+
+## Make a place to work
+
+<!-- @establishBase @testAgainstLatestRelease -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+## Secret values from local files
+
+kustomize has three different (builtin) ways to
+generate a secret from local files:
+
+ * get them from so-called _env_ files (`NAME=VALUE`, one per line),
+ * consume the entire contents of a file to make one secret value,
+ * get literal values from the kustomization file itself.
+
+Here's an example combining all three methods:
+
+Make an env file with some short secrets:
+
+<!-- @makeEnvFile @testAgainstLatestRelease -->
+```
+cat <<'EOF' >$DEMO_HOME/foo.env
+ROUTER_PASSWORD=admin
+DB_PASSWORD=iloveyou
+EOF
+```
+
+Make a text file with a long secret:
+
+<!-- @makeLongSecretFile @testAgainstLatestRelease -->
+```
+cat <<'EOF' >$DEMO_HOME/longsecret.txt
+Lorem ipsum dolor sit amet,
+consectetur adipiscing elit,
+sed do eiusmod tempor incididunt
+ut labore et dolore magna aliqua.
+EOF
+```
+
+And make a kustomization file referring to the
+above and _additionally_ defining some literal KV
+pairs in line:
+
+<!-- @makeKustomization1 @testAgainstLatestRelease -->
+```
+cat <<'EOF' >$DEMO_HOME/kustomization.yaml
+secretGenerator:
+- name: mysecrets
+  envs:
+  - foo.env
+  files:
+  - longsecret.txt
+  literals:
+  - FRUIT=apple
+  - VEGETABLE=carrot
+EOF
+```
+
+Now generate the Secret:
+
+<!-- @build1 @testAgainstLatestRelease -->
+```
+result=$(kustomize build $DEMO_HOME)
+echo "$result"
+# Spot check the result:
+test 1 == $(echo "$result" | grep -c "FRUIT: YXBwbGU=")
+```
+
+This emits something like
+
+> ```
+> apiVersion: v1
+> kind: Secret
+> metadata:
+>   name: mysecrets-hfb5df789h
+> type: Opaque
+> data:
+>   FRUIT: YXBwbGU=
+>   VEGETABLE: Y2Fycm90
+>   ROUTER_PASSWORD: YWRtaW4=
+>   DB_PASSWORD: aWxvdmV5b3U=
+>   longsecret.txt: TG9yZW0gaXBzdW0gZG9sb3Igc2l0I... (elided)
+> ```
+
+The name of the resource is the prefix `mysecrets`
+(as specfied in the kustomization file), followed
+by a hash of its contents.
+
+Use your favorite base64 decoder to confirm the raw
+versions of any of these values.
+
+The problem that these three approaches share is
+that the purported secrets must live on disk.
+
+This adds additional security questions - who can
+see the files, who installs them, who deletes
+them, etc.
+
+
+## Secret values from anywhere
+
+A general alternative is to enshrine secret
+value generation in a [plugin](../docs/plugins).
+
+The values can then come in via, say, an
+authenticated and authorized RPC to a password
+vault service.
+
+[sgp]: ../plugin/someteam.example.com/v1/secretsfromdatabase
+
+Here's a [secret generator plugin][sgp]
+that pretends to pull the values of a map
+from a database.
+
+
+Download it
+
+<!-- @copyPlugin @testAgainstLatestRelease -->
+```
+repo=https://raw.githubusercontent.com/kubernetes-sigs/kustomize
+pPath=plugin/someteam.example.com/v1/secretsfromdatabase
+dir=$DEMO_HOME/kustomize/$pPath
+
+mkdir -p $dir
+
+curl -s -o $dir/SecretsFromDatabase.go \
+  ${repo}/master/$pPath/SecretsFromDatabase.go
+```
+
+Compile it
+
+<!-- @compilePlugin @xtest -->
+```
+go build -buildmode plugin \
+  -o $dir/SecretsFromDatabase.so \
+  $dir/SecretsFromDatabase.go
+```
+
+
+Create a configuration file for it:
+
+<!-- @makeConfiguration @testAgainstLatestRelease -->
+```
+cat <<'EOF' >$DEMO_HOME/secretFromDb.yaml
+apiVersion: someteam.example.com/v1
+kind: SecretsFromDatabase
+metadata:
+  name: mySecretGenerator
+name: forbiddenValues
+namespace: production
+keys:
+- ROCKET
+- VEGETABLE
+EOF
+```
+
+Create a new kustomization file
+referencing this plugin:
+
+<!-- @makeKustomization2 @testAgainstLatestRelease -->
+```
+cat <<'EOF' >$DEMO_HOME/kustomization.yaml
+generators:
+- secretFromDb.yaml
+EOF
+```
+
+Finally, generate the secret, setting
+`XDG_CONFIG_HOME` so that the plugin
+can be found under `$DEMO_HOME`:
+
+<!-- @build2 @xtest -->
+```
+result=$( \
+  XDG_CONFIG_HOME=$DEMO_HOME \
+  kustomize build --enable_alpha_plugins $DEMO_HOME )
+echo "$result"
+# Spot check the result:
+test 1 == $(echo "$result" | grep -c "FRUIT: YXBwbGU=")
+```
+
+This should emit something like:
+
+> ```
+> apiVersion: v1
+> kind: Secret
+> metadata:
+>   name: mysecrets-bdt27dbkd6
+> type: Opaque
+> data:
+>  FRUIT: YXBwbGU=
+>  VEGETABLE: Y2Fycm90
+> ```
+
+i.e. a subset of the same values as above.

examples/springboot/README.md

@@ -13,7 +13,7 @@ In the production environment we want to customize the following:
 - health check and readiness check.
 
 First make a place to work:
-<!-- @makeDemoHome @test -->
+<!-- @makeDemoHome @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 ```
@@ -27,7 +27,7 @@ as HERE documents.
 
 Download them:
 
-<!-- @downloadResources @test -->
+<!-- @downloadResources @testAgainstLatestRelease -->
 ```
 CONTENT="https://raw.githubusercontent.com\
 /kubernetes-sigs/kustomize\
@@ -44,14 +44,14 @@ a file called `kustomization.yaml`.
 
 Start this file:
 
-<!-- @kustomizeYaml @test -->
+<!-- @kustomizeYaml @testAgainstLatestRelease -->
 ```
 touch $DEMO_HOME/kustomization.yaml
 ```
 
 ### Add the resources
 
-<!-- @addResources @test -->
+<!-- @addResources @testAgainstLatestRelease -->
 ```
 cd $DEMO_HOME
 
@@ -71,7 +71,7 @@ cat kustomization.yaml
 
 ### Add configMap generator
 
-<!-- @addConfigMap @test -->
+<!-- @addConfigMap @testAgainstLatestRelease -->
 ```
 echo "app.name=Kustomize Demo" >$DEMO_HOME/application.properties
 
@@ -102,7 +102,7 @@ For Spring Boot application, we can set an active profile through the environmen
 the application will pick up an extra `application-<profile>.properties` file. With this, we can customize the configMap in two
 steps. Add an environment variable through the patch and add a file to the configMap.
 
-<!-- @customizeConfigMap @test -->
+<!-- @customizeConfigMap @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/patch.yaml
 apiVersion: apps/v1beta2
@@ -149,7 +149,7 @@ Arrange for the resources to begin with prefix
 _prod-_ (since they are meant for the _production_
 environment):
 
-<!-- @customizeLabel @test -->
+<!-- @customizeLabel @testAgainstLatestRelease -->
 ```
 cd $DEMO_HOME
 kustomize edit set nameprefix 'prod-'
@@ -165,7 +165,7 @@ This `namePrefix` directive adds _prod-_ to all
 resource names, as can be seen by building the
 resources:
 
-<!-- @build1 @test -->
+<!-- @build1 @testAgainstLatestRelease -->
 ```
 kustomize build $DEMO_HOME | grep prod-
 ```
@@ -180,7 +180,7 @@ selector.
 add a label, but one can always edit
 `kustomization.yaml` directly:
 
-<!-- @customizeLabels @test -->
+<!-- @customizeLabels @testAgainstLatestRelease -->
 ```
 cat <<EOF >>$DEMO_HOME/kustomization.yaml
 commonLabels:
@@ -191,7 +191,7 @@ EOF
 Confirm that the resources now all have names prefixed
 by `prod-` and the label tuple `env:prod`:
 
-<!-- @build2 @test -->
+<!-- @build2 @testAgainstLatestRelease -->
 ```
 kustomize build $DEMO_HOME | grep -C 3 env
 ```
@@ -205,7 +205,7 @@ set JVM options accordingly.
 
 Download the patch `memorylimit_patch.yaml`. It contains the memory limits setup.
 
-<!-- @downloadPatch @test -->
+<!-- @downloadPatch @testAgainstLatestRelease -->
 ```
 curl -s  -o "$DEMO_HOME/#1.yaml" \
   "$CONTENT/overlays/production/{memorylimit_patch}.yaml"
@@ -243,7 +243,7 @@ has end points such as `/actuator/health` for this. We can customize the k8s dep
 
 Download the patch `healthcheck_patch.yaml`. It contains the liveness probes and readyness probes.
 
-<!-- @downloadPatch @test -->
+<!-- @downloadPatch @testAgainstLatestRelease -->
 ```
 curl -s  -o "$DEMO_HOME/#1.yaml" \
   "$CONTENT/overlays/production/{healthcheck_patch}.yaml"
@@ -281,7 +281,7 @@ The output contains
 
 Add these patches to the kustomization:
 
-<!-- @addPatch @test -->
+<!-- @addPatch @testAgainstLatestRelease -->
 ```
 cd $DEMO_HOME
 kustomize edit add patch memorylimit_patch.yaml
@@ -301,7 +301,7 @@ The output of the following command can now be applied
 to the cluster (i.e. piped to `kubectl apply`) to
 create the production environment.
 
-<!-- @finalBuild @test -->
+<!-- @finalBuild @testAgainstLatestRelease -->
 ```
 kustomize build $DEMO_HOME  # | kubectl apply -f -
 ```

examples/springboot/overlays/production/kustomization.yaml

@@ -1,4 +1,4 @@
-bases:
+resources:
 - ../../base
 patchesStrategicMerge:
 - patch.yaml

examples/springboot/overlays/staging/kustomization.yaml

@@ -1,4 +1,4 @@
-bases:
+resources:
 - ../../base
 namePrefix: staging-
 configMapGenerator:

examples/transformerconfigs/README.md

@@ -1,37 +1,85 @@
 # Transformer Configurations
 
-Kustomize computes the resources by applying a series of transformers:
-- namespace transformer
-- prefix/suffix transformer
-- label transformer
-- annotation transformer
-- name reference transformer
-- variable reference transformer
+Kustomize creates new resources by applying a series of transformations to an original
+set of resources. Kustomize provides the following default transformers:
 
-Each transformer takes a list of resources and modifies certain fields. The modification is based on the transformer's rule.
-The fields to update is the transformer's configuration, which is a list of filedspec that can be represented in YAML format.
+- annotations
+- images
+- labels
+- name reference
+- namespace
+- prefix/suffix
+- variable reference
 
-## fieldSpec
-FieldSpec is a type to represent a path to a field in one kind of resources. It has following format
-```
+A `fieldSpec` list, in a transformer's configuration, determines which resource types and which fields
+within those types the transformer can modify.
+
+## FieldSpec
+
+FieldSpec is a type that represents a path to a field in one kind of resource.
+
+```yaml
 group: some-group
 version: some-version
 kind: some-kind
 path: path/to/the/field
 create: false
 ```
-If `create` is set to true, it indicates the transformer to create the path if it is not found in the resources. This is most useful for label and annotation transformers, where the path for labels or annotations may not be set before the transformation.
 
-## prefix/suffix transformer
-Name prefix suffix transformer adds prefix and suffix to the `metadata/name` field for all resources with following configuration:
+If `create` is set to `true`, the transformer creates the path to the field in the resource if the path is not already found. This is most useful for label and annotation transformers, where the path for labels or annotations may not be set before the transformation.
+
+## Images transformer
+
+The default images transformer updates the specified image key values found in paths that include
+`containers` and `initcontainers` sub-paths.
+If found, the `image` key value is customized by the values set in the `newName`, `newTag`, and `digest` fields.
+The `name` field should match the `image` key value in a resource.
+
+Example kustomization.yaml:
+
+```yaml
+images:
+  - name: postgres
+    newName: my-registry/my-postgres
+    newTag: v1
+  - name: nginx
+    newTag: 1.8.0
+  - name: my-demo-app
+    newName: my-app
+  - name: alpine
+    digest: sha256:25a0d4
 ```
+
+Image transformer configurations can be customized by creating a list of `images` containing the `path` and `kind` fields.
+The images transformation tutorial shows how to specify the default images transformer and customize the [images transformer configuration](images/README.md).
+
+## Prefix/suffix transformer
+
+The prefix/suffix transformer adds a prefix/suffix to the `metadata/name` field for all resources. Here is the default prefix transformer configuration:
+
+```yaml
 namePrefix:
 - path: metadata/name
 ```
 
-## label transformer
-Label transformer adds labels to `metadata/labels` field for all resources. It also adds labels to `spec/selector` field in all Service and to `spec/selector/matchLabels` field in all Deployment.
+Example kustomization.yaml:
+
+```yaml
+
+namePrefix:
+  alices-
+
+nameSuffix:
+  -v2
 ```
+
+## Labels transformer
+
+The labels transformer adds labels to the `metadata/labels` field for all resources. It also adds labels to the `spec/selector` field in all Service resources as well as the `spec/selector/matchLabels` field in all Deployment resources.
+
+Example:
+
+```yaml
 commonLabels:
 - path: metadata/labels
   create: true
@@ -44,15 +92,39 @@ commonLabels:
 - path: spec/selector/matchLabels
   create: true
   kind: Deployment
-  (etc.)  
 ```
 
-## name reference transformer
-Name reference transformer's configuration is different from all other transformers. It contains a list of namebackreferences, which represented all the possible fields that a type could be used as a reference in other types of resources. A namebackreference contains a type such as ConfigMap as well as a list of FieldSpecs where ConfigMap is referenced. Here is an example.
+Example kustomization.yaml:
+
+```yaml
+commonLabels:
+  someName: someValue
+  owner: alice
+  app: bingo
 ```
+
+## Annotations transformer
+
+The annotations transformer adds annotations to the `metadata/annotations` field for all resources.
+Annotations are also added to `spec/template/metadata/annotations` for Deployment,
+ReplicaSet, DaemonSet, StatefulSet, Job, and CronJob resources, and `spec/jobTemplate/spec/template/metadata/annotations`
+for CronJob resources.
+
+Example kustomization.yaml
+
+```yaml
+commonAnnotations:
+  oncallPager: 800-555-1212
+```
+
+## Name reference transformer
+
+Name reference transformer's configuration is different from all other transformers. It contains a list of `nameReferences`, which represent all of the possible fields that a type could be used as a reference in other types of resources. A `nameReference` contains a type such as ConfigMap as well as a list of `fieldSpecs` where ConfigMap is referenced in other resources. Here is an example:
+
+```yaml
 kind: ConfigMap
 version: v1
-FieldSpecs:
+fieldSpecs:
 - kind: Pod
   version: v1
   path: spec/volumes/configMap/name
@@ -60,10 +132,11 @@ FieldSpecs:
   path: spec/template/spec/volumes/configMap/name
 - kind: Job
   path: spec/template/spec/volumes/configMap/name
-  (etc.)
-```
-Name reference transformer configuration contains a list of such namebackreferences for ConfigMap, Secret, Service, Role, ServiceAccount and so on.
 ```
+
+Name reference transformer's configuration contains a list of `nameReferences` for resources such as ConfigMap, Secret, Service, Role, and ServiceAccount. Here is an example configuration:
+
+```yaml
 nameReference:
 - kind: ConfigMap
   version: v1
@@ -74,7 +147,7 @@ nameReference:
   - path: spec/containers/env/valueFrom/configMapKeyRef/name
     version: v1
     kind: Pod
-    (etc.)
+  # ...
 - kind: Secret
   version: v1
   fieldSpecs:
@@ -84,12 +157,22 @@ nameReference:
   - path: spec/containers/env/valueFrom/secretKeyRef/name
     version: v1
     kind: Pod
-    (etc.)    
 ```
 
-## customizing transformer configurations
+## Customizing transformer configurations
+
+In addition to the default transformers, you can create custom transformer configurations. Save the default transformer configurations to a local directory by calling `kustomize config save -d`, and modify and use these configurations. This tutorial shows how to create custom transformer configurations:
 
-Kustomize has a default set of configurations. They can be saved to local directory through `kustomize config save -d`. Kustomize allows modifying those configuration files and using them in kustomization.yaml file. This tutorial shows how to customize those configurations to
 - [support a CRD type](crd/README.md)
 - add extra fields for variable substitution
 - add extra fields for name reference
+
+
+## Supporting escape characters in CRD path
+
+```yaml
+metadata:
+  annotations:
+    foo.k8s.io/bar: baz
+```
+Kustomize supports escaping special characters in path, e.g `metadata/annotations/foo.k8s.io\/bar`

examples/transformerconfigs/crd/README.md

@@ -3,7 +3,7 @@
 This tutorial shows how to add transformer configurations to support a custom resource.
 
 Create a workspace by
-<!-- @createws @test -->
+<!-- @createws @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 ```
@@ -17,7 +17,7 @@ Consider a CRD of kind `MyKind` with fields
 - `.spec.selectors` as the label selectors
 
 Add the following file to configure the transformers for the above fields
-<!-- @addConfig @test -->
+<!-- @addConfig @testAgainstLatestRelease -->
 ```
 mkdir $DEMO_HOME/kustomizeconfig
 cat > $DEMO_HOME/kustomizeconfig/mykind.yaml << EOF
@@ -51,7 +51,7 @@ EOF
 Create a file with some resources that
 includes an instance of `MyKind`:
 
-<!-- @createResource @test -->
+<!-- @createResource @testAgainstLatestRelease -->
 ```
 cat > $DEMO_HOME/resources.yaml << EOF
 apiVersion: v1
@@ -88,7 +88,7 @@ EOF
 
 Create a kustomization referring to it:
 
-<!-- @createKustomization @test -->
+<!-- @createKustomization @testAgainstLatestRelease -->
 ```
 cat > $DEMO_HOME/kustomization.yaml << EOF
 resources:
@@ -112,7 +112,7 @@ EOF
 
 Use the customized transformer configurations by specifying them
 in the kustomization file:
-<!-- @addTransformerConfigs @test -->
+<!-- @addTransformerConfigs @testAgainstLatestRelease -->
 ```
 cat >> $DEMO_HOME/kustomization.yaml << EOF
 configurations:
@@ -122,7 +122,7 @@ EOF
 
 Run `kustomize build` and verify that the namereference is correctly resolved.
 
-<!-- @build @test -->
+<!-- @build @testAgainstLatestRelease -->
 ```
 test 2 == \
 $(kustomize build $DEMO_HOME | grep -A 2 ".*Ref" | grep "test-" | wc -l); \
@@ -131,7 +131,7 @@ echo $?
 
 Run `kustomize build` and verify that the vars correctly resolved.
 
-<!-- @verify @test -->
+<!-- @verify @testAgainstLatestRelease -->
 ```
 test 0 == \
 $(kustomize build $DEMO_HOME | grep "BEE_ACTION" | wc -l); \

examples/transformerconfigs/images/README.md

@@ -0,0 +1,128 @@
+## Images transformations
+
+This tutorial shows how to modify images in resources, and create a custom images transformer configuration.
+
+Create a workspace by
+<!-- @createws @testAgainstLatestRelease -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+### Adding a custom resource
+
+Consider a Custom Resource Definition(CRD) of kind `MyKind` with field
+- `.spec.runLatest.container.image` referencing an image
+
+Add the following file to configure the images transformer for the CRD:
+
+<!-- @addConfig @testAgainstLatestRelease -->
+```
+mkdir $DEMO_HOME/kustomizeconfig
+cat > $DEMO_HOME/kustomizeconfig/mykind.yaml << EOF
+
+images:
+- path: spec/runLatest/container/image
+  kind: MyKind
+EOF
+```
+
+### Apply config
+
+Create a file with some resources that includes an instance of `MyKind`:
+
+<!-- @createResource @testAgainstLatestRelease -->
+```
+cat > $DEMO_HOME/resources.yaml << EOF
+
+apiVersion: config/v1
+kind: MyKind
+metadata:
+  name: testSvc
+spec:
+  runLatest:
+    container:
+      image: crd-image
+  containers:
+    - image: docker
+      name: ecosystem
+    - image: my-mysql
+      name: testing-1
+---
+group: apps
+apiVersion: v1
+kind: Deployment
+metadata:
+  name: deploy1
+spec:
+  template:
+    spec:
+      initContainers:
+      - name: nginx2
+        image: my-app
+      - name: init-alpine
+        image: alpine:1.8.0
+EOF
+```
+
+Create a kustomization.yaml referring to it:
+
+<!-- @createKustomization @testAgainstLatestRelease -->
+```
+cat > $DEMO_HOME/kustomization.yaml << EOF
+resources:
+- resources.yaml
+
+images:
+- name: crd-image
+  newName: new-crd-image
+  newTag: new-v1-tag
+- name: my-app
+  newName: new-app-1
+  newTag: MYNEWTAG-1
+- name: my-mysql
+  newName: prod-mysql
+  newTag: v3
+- name: docker
+  newName: my-docker2
+  digest: sha256:25a0d4
+EOF
+```
+
+Use the customized transformer configurations by specifying them
+in the kustomization file:
+<!-- @addTransformerConfigs @testAgainstLatestRelease -->
+```
+cat >> $DEMO_HOME/kustomization.yaml << EOF
+configurations:
+- kustomizeconfig/mykind.yaml
+EOF
+```
+
+Run `kustomize build` and verify that the images have been updated.
+
+<!-- @build @testAgainstLatestRelease -->
+```
+test 1 == \
+$(kustomize build $DEMO_HOME | grep -A 2 ".*image" | grep "new-crd-image:new-v1-tag" | wc -l); \
+echo $?
+```
+
+<!-- @build @testAgainstLatestRelease -->
+```
+test 1 == \
+$(kustomize build $DEMO_HOME | grep -A 2 ".*image" | grep "new-app-1:MYNEWTAG-1" | wc -l); \
+echo $?
+```
+
+<!-- @build @testAgainstLatestRelease -->
+```
+test 1 == \
+$(kustomize build $DEMO_HOME | grep -A 2 ".*image" | grep "my-docker2@sha" | wc -l); \
+echo $?
+```
+<!-- @build @testAgainstLatestRelease -->
+```
+test 1 == \
+$(kustomize build $DEMO_HOME | grep -A 2 ".*image" | grep "prod-mysql:v3" | wc -l); \
+echo $?
+```

examples/transformerconfigs/images/kustomization.yaml

@@ -0,0 +1,19 @@
+resources:
+- resources.yaml
+
+configurations:
+- kustomizeconfig/mykind.yaml
+
+images:
+- name: crd-image
+  newName: new-crd-image
+  newTag: new-v1-tag
+- name: my-app
+  newName: new-app-1
+  newTag: MYNEWTAG-1
+- name: my-mysql
+  newName: prod-mysql
+  newTag: v3
+- name: docker
+  newName: my-docker2
+  digest: sha256:25a0d4

examples/transformerconfigs/images/mykind.yaml

@@ -0,0 +1,3 @@
+images:
+- path: spec/runLatest/container/image
+  kind: MyKind

examples/transformerconfigs/images/resources.yaml

@@ -0,0 +1,27 @@
+apiVersion: config/v1
+kind: MyKind
+metadata:
+  name: testSvc
+spec:
+  runLatest:
+    container:
+      image: crd-image
+  containers:
+    - image: docker
+      name: ecosystem
+    - image: my-mysql
+      name: testing-1
+---
+group: apps
+apiVersion: v1
+kind: Deployment
+metadata:
+  name: deploy1
+spec:
+  template:
+    spec:
+      initContainers:
+      - name: nginx2
+        image: my-app
+      - name: init-alpine
+        image: alpine:1.8.0

examples/validationTransformer/README.md

@@ -0,0 +1,221 @@
+# a transformer plugin performing validation
+
+[base]: ../../docs/glossary.md#base
+[kubeval]: https://github.com/instrumenta/kubeval
+[plugin]: ../../docs/plugins
+
+kustomize doesn't validate either its input or
+output beyond the validation provided by the
+marshalling/unmarshalling packages it depends on.
+
+Another tool, [kubeval], goes beyond this to do
+k8s aware validation. Here's a usage example:
+
+```shell
+$ kubeval my-invalid-rc.yaml
+The document my-invalid-rc.yaml contains an invalid ReplicationController
+--> spec.replicas: Invalid type. Expected: integer, given: string
+```
+
+One can write a Kustomize transformer [plugin] to
+run [kubeval] against the resources that have been
+loaded by Kustomize.
+
+
+Make a place to work:
+
+<!-- @makeWorkplace @testAgainstLatestRelease -->
+```
+DEMO_HOME=$(mktemp -d)
+mkdir -p $DEMO_HOME/valid
+mkdir -p $DEMO_HOME/invalid
+PLUGINDIR=$DEMO_HOME/kustomize/plugin/someteam.example.com/v1/validator
+mkdir -p $PLUGINDIR
+```
+
+## write a transformer plugin
+
+Download the [kubeval] binary depending on the operating system
+and add it to $PATH.
+
+<!-- @downloadKubeval @testAgainstLatestRelease -->
+```
+OS=`uname | sed -e 's/Linux/linux/' -e 's/Darwin/darwin/'`
+wget https://github.com/instrumenta/kubeval/releases/download/0.9.2/kubeval-${OS}-amd64.tar.gz
+tar xf kubeval-${OS}-amd64.tar.gz
+export PATH=$PATH:`pwd`
+```
+
+Kustomize has the following assumption of a transformer plugin:
+- The resources are passed to the transformer plugin from stdin.
+- The configuration file for the transformer plugin is passed in
+  as the first argument.
+- The working directory of the plugin is the kustomization
+  directory where it is used as a transformer.
+- The transformed resources are written to stdout by the plugin.
+- If the return code of the transformer plugin is non zero,
+  Kustomize regards there is an error during the transformation.
+
+A transformer plugin for the validation can be written as a
+bash script, which execute the [kubeval] binary and return proper
+output and exit code.
+
+<!-- @writePlugin @testAgainstLatestRelease -->
+```
+cat <<'EOF' > $PLUGINDIR/Validator
+#!/bin/bash
+
+if ! [ -x "$(command -v kubeval)" ]; then
+  echo "Error: kubeval is not installed."
+  exit 1
+fi
+
+temp_file=$(mktemp)
+output_file=$(mktemp)
+cat - > $temp_file
+
+kubeval $temp_file > $output_file
+
+if [ $? -eq 0 ]; then
+    cat $temp_file
+    rm $temp_file $output_file
+    exit 0
+fi
+
+cat $output_file
+rm $temp_file $output_file
+exit 1
+
+EOF
+chmod +x $PLUGINDIR/Validator
+```
+
+## use the transformer plugin
+
+Define a kustomization containing a valid ConfigMap
+and the transformer plugin.
+
+<!-- @writeKustomization @testAgainstLatestRelease -->
+```
+cat <<'EOF' >$DEMO_HOME/valid/configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cm
+data:
+  foo: bar
+EOF
+
+cat <<'EOF' >$DEMO_HOME/valid/validation.yaml
+apiVersion: someteam.example.com/v1
+kind: Validator
+metadata:
+  name: notImportantHere
+EOF
+
+cat <<'EOF' >$DEMO_HOME/valid/kustomization.yaml
+resources:
+- configmap.yaml
+
+transformers:
+- validation.yaml
+EOF
+```
+
+Define a kustomization containing an invalid ConfigMap
+and the transformer plugin.
+
+<!-- @writeKustomization @testAgainstLatestRelease -->
+```
+cat <<'EOF' >$DEMO_HOME/invalid/configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cm
+data:
+- foo: bar
+EOF
+
+cat <<'EOF' >$DEMO_HOME/invalid/validation.yaml
+apiVersion: someteam.example.com/v1
+kind: Validator
+metadata:
+  name: notImportantHere
+EOF
+
+cat <<'EOF' >$DEMO_HOME/invalid/kustomization.yaml
+resources:
+- configmap.yaml
+
+transformers:
+- validation.yaml
+EOF
+```
+
+The directory structure is as the following:
+
+```
+/tmp/tmp.fAYMfLZJs4
+├── invalid
+│   ├── configmap.yaml
+│   ├── kustomization.yaml
+│   └── validation.yaml
+├── kustomize
+│   └── plugin
+│       └── someteam.example.com
+│           └── v1
+│               ├── kubeval
+│               └── Validator
+└── valid
+    ├── configmap.yaml
+    ├── kustomization.yaml
+    └── validation.yaml
+```
+
+Define a helper function to run kustomize with the
+correct environment and flags for plugins:
+
+<!-- @defineKustomizeBd @testAgainstLatestRelease -->
+```
+function kustomizeBd {
+  XDG_CONFIG_HOME=$DEMO_HOME \
+  kustomize build \
+    --enable_alpha_plugins \
+    $DEMO_HOME/$1
+}
+```
+
+Build the valid variant
+
+<!-- @buildValid @testAgainstLatestRelease -->
+```
+kustomizeBd valid
+```
+The output contains a ConfigMap as
+
+```yaml
+apiVersion: v1
+data:
+  foo: bar
+kind: ConfigMap
+metadata:
+  name: cm
+```
+
+Build the invalid variant
+
+```
+kustomizeBd invalid
+```
+
+The output is an error as
+```shell
+data: Invalid type. Expected: object, given: array
+```
+
+## cleanup
+
+<!-- @cleanup @testAgainstLatestRelease -->
+```shell
+rm -rf $DEMO_HOME
+```

examples/validationTransformer/invalid.yaml

@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cm
+data:
+- foo: bar

examples/validationTransformer/valid.yaml

@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cm
+data:
+  foo: bar

examples/wordpress/README.md

@@ -8,7 +8,7 @@ To run WordPress, it's necessary to
 - access the service name of MySQL database from WordPress container
 
 First make a place to work:
-<!-- @makeDemoHome @test -->
+<!-- @makeDemoHome @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
 MYSQL_HOME=$DEMO_HOME/mysql
@@ -21,7 +21,7 @@ mkdir -p $WORDPRESS_HOME
 
 Download the resources and `kustomization.yaml` for WordPress.
 
-<!-- @downloadResources @test -->
+<!-- @downloadResources @testAgainstLatestRelease -->
 ```
 CONTENT="https://raw.githubusercontent.com\
 /kubernetes-sigs/kustomize\
@@ -33,7 +33,7 @@ curl -s -o "$WORDPRESS_HOME/#1.yaml" \
 
 Download the resources and `kustomization.yaml` for MySQL.
 
-<!-- @downloadResources @test -->
+<!-- @downloadResources @testAgainstLatestRelease -->
 ```
 CONTENT="https://raw.githubusercontent.com\
 /kubernetes-sigs/kustomize\
@@ -44,17 +44,19 @@ curl -s -o "$MYSQL_HOME/#1.yaml" \
 ```
 
 ### Create kustomization.yaml
-Create a new kustomization with two bases:
 
-<!-- @createKustomization @test -->
+Create a new kustomization with two bases,
+`wordpress` and `mysql`:
+
+<!-- @createKustomization @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/kustomization.yaml
-bases:
-  - wordpress
-  - mysql
+resources:
+- wordpress
+- mysql
 namePrefix: demo-
 patchesStrategicMerge:
-  - patch.yaml
+- patch.yaml
 EOF
 ```
 
@@ -63,7 +65,7 @@ In the new kustomization, apply a patch for wordpress deployment. The patch does
 - Add an initial container to show the mysql service name
 - Add environment variable that allow wordpress to find the mysql database
 
-<!-- @downloadPatch @test -->
+<!-- @downloadPatch @testAgainstLatestRelease -->
 ```
 CONTENT="https://raw.githubusercontent.com\
 /kubernetes-sigs/kustomize\
@@ -103,7 +105,7 @@ $(WORDPRESS_SERVICE) and $(MYSQL_SERVICE).
 
 ### Bind the Variables to k8s Object Fields
 
-<!-- @addVarRef @test -->
+<!-- @addVarRef @testAgainstLatestRelease -->
 ```
 cat <<EOF >>$DEMO_HOME/kustomization.yaml
 vars:
@@ -126,7 +128,7 @@ EOF
 ### Substitution
 Confirm the variable substitution:
 
-<!-- @kustomizeBuild @test -->
+<!-- @kustomizeBuild @testAgainstLatestRelease -->
 ```
 kustomize build $DEMO_HOME
 ```
@@ -143,4 +145,4 @@ Expect this in the output:
 >        image: debian
 >        name: init-command
 >
-> ```
+> ```

examples/wordpress/kustomization.yaml

@@ -1,19 +1,19 @@
-bases:
-  - wordpress
-  - mysql
+resources:
+- wordpress
+- mysql
 patchesStrategicMerge:
-  - patch.yaml
+- patch.yaml
 namePrefix: demo-
 
 vars:
-  - name: WORDPRESS_SERVICE
-    objref:
-      kind: Service
-      name: wordpress
-      apiVersion: v1
-  - name: MYSQL_SERVICE
-    objref:
-      kind: Service
-      name: mysql
-      apiVersion: v1
+- name: WORDPRESS_SERVICE
+  objref:
+    kind: Service
+    name: wordpress
+    apiVersion: v1
+- name: MYSQL_SERVICE
+  objref:
+    kind: Service
+    name: mysql
+    apiVersion: v1
 

examples/zh/README.md

@@ -0,0 +1,61 @@
+[English](../README.md) | 简体中文
+
+# 示例
+
+这些示例默认 `kustomize` 在您的 `$PATH` 中。
+
+这些示例通过了 [pre-commit](../../travis/pre-commit.sh) 测试，并且应该与 HEAD 一起使用。
+
+```
+go get sigs.k8s.io/kustomize/v3/cmd/kustomize
+```
+
+基本用法
+
+  * [configGenerations](configGeneration.md) - 当 ConfigMapGenerator 修改时进行滚动更新。
+
+  * [combineConfigs](combineConfigs.md) - 融合来自不同用户的配置数据（例如来自 devops/SRE 和 developers）。
+
+  * [generatorOptions](generatorOptions.md) -修改所有 ConfigMapGenerator 和 SecretGenerator 的行为。
+
+  * [vars](vars.md) - 通过 vars 将一个资源的数据注入另一个资源的容器参数 （例如，为 wordpress 指定 SQL 服务）。
+
+  * [image names and tags](image.md) - 在不使用 patch 的情况下更新镜像名称和标签。
+
+  * [remote target](remoteBuild.md) - 通过 github URL 来构建 kustomization 。
+
+  * [json patch](jsonpatch.md) -在 kustomization 中应用 json patch 。
+
+  * [patch multiple objects](patchMultipleObjects.md) - 通过一个patch来修改多个资源。
+
+高级用法
+
+  - generator 插件:
+
+    * [last mile helm](../chart.md) - 对 helm chart 进行 last mile 修改。
+
+    * [secret generation](../secretGeneratorPlugin.md) - 生成 Secret。
+
+  - transformer 插件:
+
+   * [validation transformer](../validationTransformer/README.md) - 通过 transformer 验证资源。
+
+  - 定制内建 transformer 配置
+
+    * [transformer configs](../transformerconfigs/README.md) - 自定义 transformer 配置。
+
+多 Variant 示例
+
+ * [hello world](helloWorld.md) - 部署多个不同配置的 Hello World 服务。
+
+ * [LDAP](../ldap/README.md) - 部署多个配置不同的 LDAP 服务。
+
+ * [springboot](../springboot/README.md) - 从头开始创建一个 Spring Boot 项目的生产配置。
+
+ * [mySql](../mySql/README.md) - 从头开始创建一个 MySQL 的生产配置。
+
+ * [breakfast](../breakfast.md) - 给 Alice 和 Bob 定制一顿早餐 :)
+
+ * [multibases](../multibases/README.md) - 使用相同的 base 生成三个 variants（dev，staging，production）。
+
+>声明：部分文档可能稍微滞后于英文版本，同步工作持续进行中

examples/zh/combineConfigs.md

@@ -0,0 +1,230 @@
+[overlay]: ../docs/glossary.md#overlay
+[target]: ../docs/glossary.md#target
+
+# 示例：devops和开发配合管理配置数据
+
+场景：在生产环境中有一个基于 Java 由多个内部团队（注册、结账和搜索等）共同开发的商店服务。
+
+这个服务在不同的环境中运行：_development_、 _testing_、 _staging_ 和 _production_，从 Java 的 properties 文件中读取配置。
+
+为每个环境维护一个大的 properties 文件是很困难的。这个文件需要频繁的修改，并且这些修改都需要由 devops 工程师来进行，因为：
+
+  1. 这个文件包含 devops 工程师需要知道，而开发人员不必知道的值
+  2. 比如生产环境的 properties 包含敏感数据，比如生产数据库的登录凭据。
+
+## Property sharding
+
+通过一些研究，我们注意到属性可以分为不同的类别。
+
+### Property sharding
+
+例如：国际化数据、物理常量，外部服务位置等静态数据。
+
+_这些无论哪个环境，都一样的配置。_
+
+这些都只需要一组配置。将这组配置放在一个文件中：
+
+ * `common.properties`
+
+### Plumbing properties
+
+例如：静态资源（HTML、CSS、JavaScript）的位置，产品和用户的数据表，负载均衡的端口，日志收集等。
+
+_这些属性的不同，恰恰是环境的不同之处。_
+
+DevOps 或 SRE 工程师需要完全控制生产环境中的这些配置；测试需要调整数据库来支持测试；而开发则希望尝试开发中遇到的各种不同的情景。
+
+将这些值放入
+
+ * `development/plumbing.properties`
+ * `staging/plumbing.properties`
+ * `production/plumbing.properties`
+
+
+### Secret properties
+
+例如：用户表的位置、数据库凭证、解密密钥等。
+
+_这些需要 devops 工程师控制，其他人没有访问权限。_
+
+将这些值放入
+
+ * `development/secret.properties`
+ * `staging/secret.properties`
+ * `production/secret.properties`
+
+[kubernetes secret]: https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/
+
+例如使用 unix 文件权限和模式来限制访问控制，或者使用更好的方法-使用专门用于存储密码的服务，并且使用 kustomize 中的 `secretGenerator` 字段在 Kubernetes 中创建 secret 来存储密码。
+
+<!--
+secretGenerator:
+- name: app-tls
+  files:
+    tls.crt=tls.cert
+    tls.key=tls.key
+  type: "kubernetes.io/tls"
+EOF
+-->
+
+## 混合管理方法
+
+基于相同的 base 创建 _n_ 个 overlays 来创建 _n_ 个集群环境的方法。
+
+在本例的其余部分，我们将使用 _n==2_，这里只使用 _development_ 和 _production_ ，可以使用相同的方法来增加更多的环境。
+
+运行 `kustomize build` 基于 [overlay] 的 [target] 来创建集群环境。
+
+[helloworld]: helloWorld.md
+
+以下示例将执行此操作，但将侧重于 configMap 构建，而不用担心如何将 configMaps 关联到 Deployment（[helloworld] 示例中介绍的）。
+
+所有文件（包括共享 property 文件）都将在目录树中创建，目录中包含 base 和 overlay 文件的目录，这些都与 [helloworld] 中演示的一致。
+
+它将全部存在于此工作目录中：
+
+<!-- @makeWorkplace @test -->
+```bash
+DEMO_HOME=$(mktemp -d)
+```
+
+### 创建 base
+
+<!-- kubectl create configmap BOB --dry-run -o yaml --from-file db. -->
+
+创建放置 base 配置的路径：
+
+<!-- @baseDir @test -->
+```bash
+mkdir -p $DEMO_HOME/base
+```
+
+向 base 中的插入数据，base 中应该包含所有环境共有的资源，这里我们只定义一个 java properties 文件，以及一个引用他们的 `kustomization` 文件。
+
+<!-- @baseKustomization @test -->
+```bash
+cat <<EOF >$DEMO_HOME/base/common.properties
+color=blue
+height=10m
+EOF
+
+cat <<EOF >$DEMO_HOME/base/kustomization.yaml
+configMapGenerator:
+- name: my-configmap
+  files:
+  - common.properties
+EOF
+```
+
+### 创建并使用 overlay 用于 _开发_
+
+创建一个 overlays 目录：
+
+<!-- @overlays @test -->
+```bash
+OVERLAYS=$DEMO_HOME/overlays
+```
+
+创建 _development_ overlay：
+
+<!-- @developmentFiles @test -->
+```bash
+mkdir -p $OVERLAYS/development
+
+cat <<EOF >$OVERLAYS/development/plumbing.properties
+port=30000
+EOF
+
+cat <<EOF >$OVERLAYS/development/secret.properties
+dbpassword=mothersMaidenName
+EOF
+
+cat <<EOF >$OVERLAYS/development/kustomization.yaml
+resources:
+- ../../base
+namePrefix: dev-
+nameSuffix: -v1
+configMapGenerator:
+- name: my-configmap
+  behavior: merge
+  files:
+  - plumbing.properties
+  - secret.properties
+EOF
+```
+
+现在可以生成开发使用的 configMaps ：
+
+<!-- @runDev @test -->
+```bash
+kustomize build $OVERLAYS/development
+```
+
+#### 检查 ConfigMap 名称
+
+可以在输出中看到生成的 `ConfigMap` 名称。
+
+名称应该是这样的：`dev-my-configmap-v1-2gccmccgd5`：
+
+ * `"dev-"` 来自 `namePrefix` 字段
+ * `"my-configmap"` 来自 `configMapGenerator/name` 字段
+ * `"-v1"` 来自 `nameSuffix` 字段
+ * `"-2gccmccgd5"` 为哈希值，是 `kustomize` 根据 configMap 的内容计算的
+
+哈希后缀很关键，如果 configMap 内容发生变化， configMap 的名称也会发生变化，以及从 `kustomize` 出现在 YAML 输出中的对该名称的所有引用。
+
+名称更改意味着如果使用类似命令将此 YAML 应用于群集，则 Deployment 将执行滚动更新重启以获取新数据。
+
+> ```bash
+> kustomize build $OVERLAYS/development | kubectl apply -f -
+> ```
+
+Deployment 无法自动检测 ConfigMap 是否发生改变。
+
+如果更改 configMap 的数据, 而不更改其名称以及对该名称的所有引用, 则必须重新启动Deployment中的那些Pods以获取更改。
+
+最佳的做法就是将 configMap 视为不变的。
+
+不去编辑 configMap ，而是使用 _新_ 的名称的 _新_ configMap，并在 Deployment 中引用新的 configMap 。而 `kustomize` 使用 `configMapGenerator` 指令和相关的命名控件使这很容易。
+
+### 创建并且使用 overlay 用于 _生产_
+
+接下来创建 _production_ overlay 的文件：
+
+<!-- @productionFiles @test -->
+```bash
+mkdir -p $OVERLAYS/production
+
+cat <<EOF >$OVERLAYS/production/plumbing.properties
+port=8080
+EOF
+
+cat <<EOF >$OVERLAYS/production/secret.properties
+dbpassword=thisShouldProbablyBeInASecretInstead
+EOF
+
+cat <<EOF >$OVERLAYS/production/kustomization.yaml
+resources:
+- ../../base
+namePrefix: prod-
+configMapGenerator:
+- name: my-configmap
+  behavior: merge
+  files:
+  - plumbing.properties
+  - secret.properties
+EOF
+```
+
+现在可以生成用于生产的 configMap：
+
+<!-- @runProd @test -->
+```bash
+kustomize build $OVERLAYS/production
+```
+
+可以直接在 CI/CD 流程中执行如下命令，将应用部署到集群：
+
+> ```bash
+> kustomize build $OVERLAYS/production | kubectl apply -f -
+> ```

examples/zh/configGeneration.md

@@ -0,0 +1,184 @@
+[patch]: ../../docs/glossary.md#patch
+[resource]: ../../docs/glossary.md#resource
+[variant]: ../../docs/glossary.md#variant
+
+## ConfigMap 的生成和滚动更新
+
+kustomize 提供了两种添加 ConfigMap 的方法：
+- 将 ConfigMap 声明为 [resource]
+- 通过 ConfigMapGenerator 声明 ConfigMap
+
+在 `kustomization.yaml` 中，这两种方法的格式分别如下：
+
+> ```
+> # 将 ConfigMap 声明为 resource
+> resources:
+> - configmap.yaml
+> 
+> # 在 ConfigMapGenerator 中声明 ConfigMap
+> configMapGenerator:
+> - name: a-configmap
+>   files:
+>     - configs/configfile
+>     - configs/another_configfile
+> ```
+
+声明为 [resource] 的 ConfigMaps 的处理方式与其他 resource 相同，Kustomize 不会在为 ConfigMap 的名称添加哈希后缀。而在 ConfigMapGenerator 中声明 ConfigMap 的处理方式则与之前不同，默认将为名称添加哈希后缀，ConfigMap 中的任何更改都将触发滚动更新。
+
+在 [hello_world](helloWorld.md) 示例中，使用 ConfigmapGenerator 来替换将 ConfigMap 声明为 [resource] 的方法。由此生成的 ConfigMap 中的更改将导致哈希值更改和滚动更新。
+
+### 建立 base 和 staging
+
+使用 configMapGenerator 建立 base
+<!-- @establishBase @testAgainstLatestRelease -->
+```
+DEMO_HOME=$(mktemp -d)
+
+BASE=$DEMO_HOME/base
+mkdir -p $BASE
+
+curl -s -o "$BASE/#1.yaml" "https://raw.githubusercontent.com\
+/kubernetes-sigs/kustomize\
+/master/examples/helloWorld\
+/{deployment,service}.yaml"
+
+cat <<'EOF' >$BASE/kustomization.yaml
+commonLabels:
+  app: hello
+resources:
+- deployment.yaml
+- service.yaml
+configMapGenerator:	
+- name: the-map	
+  literals:	
+    - altGreeting=Good Morning!	
+    - enableRisky="false"
+EOF
+```
+
+通过应用 ConfigMap patch 的方式建立 staging
+<!-- @establishStaging @testAgainstLatestRelease -->
+```
+OVERLAYS=$DEMO_HOME/overlays
+mkdir -p $OVERLAYS/staging
+
+cat <<'EOF' >$OVERLAYS/staging/kustomization.yaml
+namePrefix: staging-
+nameSuffix: -v1
+commonLabels:
+  variant: staging
+  org: acmeCorporation
+commonAnnotations:
+  note: Hello, I am staging!
+resources:
+- ../../base
+patchesStrategicMerge:
+- map.yaml
+EOF
+
+cat <<EOF >$OVERLAYS/staging/map.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: the-map
+data:
+  altGreeting: "Have a pineapple!"
+  enableRisky: "true"
+EOF
+```
+
+### Review
+
+在集群中运行的 _hello-world_ 的 deployment 配置了来自 configMap 的数据。
+
+deployment 按照名称引用此 ConfigMap ：
+
+<!-- @showDeployment @testAgainstLatestRelease -->
+```
+grep -C 2 configMapKeyRef $BASE/deployment.yaml
+```
+
+当 ConfigMap 中的数据需要更新时，更改群集中的实时 ConfigMap 的数据并不是一个好的做法。 由于 Deployment 无法知道其引用的 ConfigMap 已更改，这类更新是无效。
+
+更改 Deployment 配置的推荐方法是：
+
+ 1. 使用新名称创建一个新的 configMap
+ 2. 为_deployment_ 添加 patch，修改相应 `configMapKeyRef` 字段的名称值。
+
+后一种更改会启动对 deployment 中的 pod 的滚动更新。旧的 configMap 在不再被任何其他资源引用时最终会被[垃圾回收](https://github.com/kubernetes-sigs/kustomize/issues/242)。
+
+### 如何使用 kustomize 
+
+_staging_ 的 [variant] 包含一个 configMap 的 [patch]：
+
+<!-- @showMapPatch @testAgainstLatestRelease -->
+```
+cat $OVERLAYS/staging/map.yaml
+```
+
+根据定义，此 patch 是一个命名但不一定是完整的资源规范，旨在修改完整的资源规范。
+
+在 ConfigMapGenerator 中声明 ConfigMap 的修改。
+
+<!-- @showMapBase @testAgainstLatestRelease -->
+```
+grep -C 4 configMapGenerator $BASE/kustomization.yaml
+```
+
+要使这个 patch 正常工作，`metadata/name` 字段中的名称必须匹配。
+
+但是，文件中指定的名称值不是群集中使用的名称值。根据设计，kustomize 修改从 ConfigMapGenerator 声明的 ConfigMaps 的名称。要查看最终在群集中使用的名称，只需运行 kustomize：
+
+<!-- @grepStagingName @testAgainstLatestRelease -->
+```
+kustomize build $OVERLAYS/staging |\
+    grep -B 8 -A 1 staging-the-map
+```
+
+根据 `$OVERLAYS/staging/kustomization.yaml` 中的 `namePrefix` 字段，configMap 名称以 _staging-_ 为前缀。
+
+根据 `$OVERLAYS/staging/kustomization.yaml` 中的 `nameSuffix` 字段，configMap 名称以 _-v1_ 为后缀。
+
+configMap 名称的后缀是由 map 内容的哈希生成的 - 在这种情况下，名称后缀是 _k25m8k5k5m_ ：
+
+<!-- @grepStagingHash @testAgainstLatestRelease -->
+```
+kustomize build $OVERLAYS/staging | grep k25m8k5k5m
+```
+
+现在修改 map patch ，更改该服务将使用的问候消息：
+
+<!-- @changeMap @testAgainstLatestRelease -->
+```
+sed -i.bak 's/pineapple/kiwi/' $OVERLAYS/staging/map.yaml
+```
+
+查看新的问候消息：
+
+```
+kustomize build $OVERLAYS/staging |\
+  grep -B 2 -A 3 kiwi
+```
+
+再次运行 kustomize 查看新的 configMap 名称：
+
+<!-- @grepStagingName @testAgainstLatestRelease -->
+```
+kustomize build $OVERLAYS/staging |\
+    grep -B 8 -A 1 staging-the-map
+```
+
+确认 configMap 内容的更改将会生成以 _cd7kdh48fd_ 结尾的三个新名称 - 一个在 configMap 的名称中，另两个在使用 ConfigMap 的 deployment 中：
+
+<!-- @countHashes @testAgainstLatestRelease -->
+```
+test 3 == \
+  $(kustomize build $OVERLAYS/staging | grep cd7kdh48fd | wc -l); \
+  echo $?
+```
+
+将这些资源应用于群集将导致 deployment pod 的滚动更新，将它们从 _k25m8k5k5m_ map 重新定位到 _cd7kdh48fd_ map 。系统稍后将垃圾收集未使用的 map。
+
+## 回滚
+
+回滚，可以撤消对源码配置所做的任何编辑，然后在还原的配置上重新运行 kustomize 并将其应用于群集。

examples/zh/generatorOptions.md

@@ -0,0 +1,60 @@
+# Generator Options
+
+Kustomize 提供了修改 ConfigMapGenerator 和 SecretGenerator 行为的选项，这些选项包括：
+ 
+ - 不再将基于内容生成的哈希后缀添加到资源名称后
+ - 为生成的资源添加 labels
+ - 为生成的资源添加 annotations
+ 
+这个示例将展示如何运用这些选项，首先创建一个工作空间：
+```bash
+DEMO_HOME=$(mktemp -d)
+```
+
+创建 kustomization 并且为其添加一个 ConfigMapGenerator
+
+<!-- @createCMGenerator @test -->
+```bash
+cat > $DEMO_HOME/kustomization.yaml << EOF
+configMapGenerator:
+- name: my-configmap
+  literals:	
+  - foo=bar
+  - baz=qux
+EOF
+```
+
+添加如下 generatorOptions
+<!-- @addGeneratorOptions @test -->
+```bash
+cat >> $DEMO_HOME/kustomization.yaml << EOF
+generatorOptions:
+ disableNameSuffixHash: true
+ labels:
+   kustomize.generated.resource: somevalue
+ annotations:
+   annotations.only.for.generated: othervalue
+EOF
+```
+运行 `kustomize build` 并且确定生成的 ConfigMap 。
+ 
+ - 确定没有名称后缀
+    <!-- @verify @test -->
+    ```
+    test 1 == \
+    $(kustomize build $DEMO_HOME | grep "name: my-configmap$" | wc -l); \
+    echo $?
+    ```
+ - 确定 label `kustomize.generated.resource: somevalue`
+     ```
+     test 1 == \
+     $(kustomize build $DEMO_HOME | grep -A 1 "labels" | grep "kustomize.generated.resource" | wc -l); \
+     echo $?
+     ```
+ - 确定 annotation `annotations.only.for.generated: othervalue`
+      ```
+      test 1 == \
+      $(kustomize build $DEMO_HOME | grep -A 1 "annotations" | grep "annotations.only.for.generated" | wc -l); \
+      echo $?
+      ```
+      

examples/zh/helloWorld.md

@@ -0,0 +1,301 @@
+[base]: ../../docs/glossary.md#base
+[config]: https://github.com/kinflate/example-hello
+[gitops]: ../../docs/glossary.md#gitops
+[hello]: https://github.com/monopole/hello
+[kustomization]: ../../docs/glossary.md#kustomization
+[original]: https://github.com/kinflate/example-hello
+[overlay]: ../../docs/glossary.md#overlay
+[overlays]: ../../docs/glossary.md#overlay
+[patch]: ../../docs/glossary.md#patch
+[variant]: ../../docs/glossary.md#variant
+[variants]: ../../docs/glossary.md#variant
+
+# Demo: hello world with variants
+
+步骤：
+
+ 1. 下载 [base] 配置。
+ 2. 进行定制。
+ 3. 基于定制后的 base 新建2个不同的 [overlays] (_staging_ 和 _production_)。
+ 4. 运行 kustomize 和 kubectl 来部署 staging 和 production 。
+
+首先创建一个工作空间：
+
+<!-- @makeWorkplace @testAgainstLatestRelease -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+或者：
+
+> ```
+> DEMO_HOME=~/hello
+> ```
+
+## 创建 base
+
+如果要使用 [overlays] 创建 [variants] ，必须先创建一个共同的 [base] 。
+
+为了使本文档保持简洁，base 的资源位于补充目录中，并不在此处，请按照下面的方法下载它们：
+
+<!-- @downloadBase @testAgainstLatestRelease -->
+```
+BASE=$DEMO_HOME/base
+mkdir -p $BASE
+
+curl -s -o "$BASE/#1.yaml" "https://raw.githubusercontent.com\
+/kubernetes-sigs/kustomize\
+/master/examples/helloWorld\
+/{configMap,deployment,kustomization,service}.yaml"
+```
+
+观察该目录：
+
+<!-- @runTree @testAgainstLatestRelease -->
+```
+tree $DEMO_HOME
+```
+
+可以看到：
+
+> ```
+> /tmp/tmp.IyYQQlHaJP
+> └── base
+>     ├── configMap.yaml
+>     ├── deployment.yaml
+>     ├── kustomization.yaml
+>     └── service.yaml
+> ```
+
+这些 resources 可以立即在 k8s 集群中部署：
+
+> ```
+> kubectl apply -f $DEMO_HOME/base
+> ```
+
+实例化 _hello_ 服务， `kubectl` 只能识别 resources 文件。
+
+
+### The Base Kustomization
+
+`base` 目录中包含一个 [kustomization] 文件：
+
+<!-- @showKustomization @testAgainstLatestRelease -->
+```
+more $BASE/kustomization.yaml
+```
+
+（可选）在 base 目录上运行 `kustomize` 将定制过的 resources 打印到标准输出：
+
+<!-- @buildBase @testAgainstLatestRelease -->
+```
+kustomize build $BASE
+```
+
+### 定制 base
+
+定制 _app label_ 并应用于所有的 resources ：
+
+<!-- @addLabel @testAgainstLatestRelease -->
+```
+sed -i.bak 's/app: hello/app: my-hello/' \
+    $BASE/kustomization.yaml
+```
+
+查看效果：
+<!-- @checkLabel @testAgainstLatestRelease -->
+```
+kustomize build $BASE | grep -C 3 app:
+```
+
+## 创建 Overlays
+
+创建包含 _staging_ 和 _production_ 的 [overlay]：
+
+ * _Staging_ 包含生产环境中无法应用的带有风险的功能。
+ * _Production_ 包含更多的副本数。
+ * 来自这些集群 [variants] 的问候消息将与来自其他集群的不同。
+
+<!-- @overlayDirectories @testAgainstLatestRelease -->
+```
+OVERLAYS=$DEMO_HOME/overlays
+mkdir -p $OVERLAYS/staging
+mkdir -p $OVERLAYS/production
+```
+
+#### Staging Kustomization
+
+在 `staging` 目录中创建一个 kustomization 文件，用来定义一个新的名称前缀和一些不同的 labels 。
+
+<!-- @makeStagingKustomization @testAgainstLatestRelease -->
+```
+cat <<'EOF' >$OVERLAYS/staging/kustomization.yaml
+namePrefix: staging-
+commonLabels:
+  variant: staging
+  org: acmeCorporation
+commonAnnotations:
+  note: Hello, I am staging!
+resources:
+- ../../base
+patchesStrategicMerge:
+- map.yaml
+EOF
+```
+
+#### Staging Patch
+
+新增一个自定义的 configMap 将问候消息从 _Good Morning!_ 改为 _Have a pineapple!_ 。
+
+同时，将 _risky_ 标记设置为 true 。
+
+<!-- @stagingMap @testAgainstLatestRelease -->
+```
+cat <<EOF >$OVERLAYS/staging/map.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: the-map
+data:
+  altGreeting: "Have a pineapple!"
+  enableRisky: "true"
+EOF
+```
+
+#### Production Kustomization
+
+在 `production` 目录中创建一个 kustomization 文件，用来定义一个新的名称前缀和 labels 。
+
+<!-- @makeProductionKustomization @testAgainstLatestRelease -->
+```
+cat <<EOF >$OVERLAYS/production/kustomization.yaml
+namePrefix: production-
+commonLabels:
+  variant: production
+  org: acmeCorporation
+commonAnnotations:
+  note: Hello, I am production!
+resources:
+- ../../base
+patchesStrategicMerge:
+- deployment.yaml
+EOF
+```
+
+
+#### Production Patch
+
+因为生产环境需要处理更多的流量，新建一个 production patch 来增加副本数。
+
+<!-- @productionDeployment @testAgainstLatestRelease -->
+```
+cat <<EOF >$OVERLAYS/production/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: the-deployment
+spec:
+  replicas: 10
+EOF
+```
+
+## 比较 overlays
+
+
+`DEMO_HOME` 现在包含：
+
+ - _base_ 目录：对拉取到的源配置进行了简单定制
+
+ - _overlays_ 目录：包含在集群中创建不同 _staging_ 和 _production_ [variants] 的 kustomizations 和 patches 。
+
+查看目录结构和差异：
+
+<!-- @listFiles @testAgainstLatestRelease -->
+```
+tree $DEMO_HOME
+```
+
+可以看到：
+
+> ```
+> /tmp/tmp.IyYQQlHaJP1
+> ├── base
+> │   ├── configMap.yaml
+> │   ├── deployment.yaml
+> │   ├── kustomization.yaml
+> │   └── service.yaml
+> └── overlays
+>     ├── production
+>     │   ├── deployment.yaml
+>     │   └── kustomization.yaml
+>     └── staging
+>         ├── kustomization.yaml
+>         └── map.yaml
+> ```
+
+直接比较 _staging_ 和 _production_ 输出的不同：
+
+<!-- @compareOutput -->
+```
+diff \
+  <(kustomize build $OVERLAYS/staging) \
+  <(kustomize build $OVERLAYS/production) |\
+  more
+```
+
+部分比较输出：
+
+> ```diff
+> <   altGreeting: Have a pineapple!
+> <   enableRisky: "true"
+> ---
+> >   altGreeting: Good Morning!
+> >   enableRisky: "false"
+> 8c8
+> <     note: Hello, I am staging!
+> ---
+> >     note: Hello, I am production!
+> 11c11
+> <     variant: staging
+> ---
+> >     variant: production
+> 13c13
+> (...truncated)
+> ```
+
+
+## 部署
+
+输出不同 _overlys_ 的配置：
+
+<!-- @buildStaging @testAgainstLatestRelease -->
+```
+kustomize build $OVERLAYS/staging
+```
+
+<!-- @buildProduction @testAgainstLatestRelease -->
+```
+kustomize build $OVERLAYS/production
+```
+
+将上述命令传递给 kubectl 进行部署：
+
+> ```
+> kustomize build $OVERLAYS/staging |\
+>     kubectl apply -f -
+> ```
+
+> ```
+> kustomize build $OVERLAYS/production |\
+>    kubectl apply -f -
+> ```
+
+也可使用 `kubectl` (v1.14.0 以上版本)：
+
+> ```
+> kubectl apply -k $OVERLAYS/staging
+> ```
+
+> ```
+> kubectl apply -k $OVERLAYS/production
+> ```

examples/zh/image.md

@@ -0,0 +1,74 @@
+# 示例: 改变镜像名称和标签
+
+首先构建一个工作空间：
+
+<!-- @makeWorkplace @testAgainstLatestRelease -->
+```bash
+DEMO_HOME=$(mktemp -d)
+```
+
+创建包含pod资源的 `kustomization`
+
+<!-- @testAgainstLatestRelease to @test -->
+```bash
+cat <<EOF >$DEMO_HOME/kustomization.yaml
+resources:
+- pod.yaml
+EOF
+```
+
+创建 pod 资源pod.yaml
+
+<!-- @createDeployment @test -->
+```bash
+cat <<EOF >$DEMO_HOME/pod.yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: myapp-pod
+  labels:
+    app: myapp
+spec:
+  containers:
+  - name: myapp-container
+    image: busybox:1.29.0
+    command: ['sh', '-c', 'echo The app is running! && sleep 3600']
+  initContainers:
+  - name: init-mydb
+    image: busybox:1.29.0
+    command: ['sh', '-c', 'until nslookup mydb; do echo waiting for mydb; sleep 2; done;']
+EOF
+```
+
+`myapp-pod` 包含一个init容器和一个普通容器，两者都使用 `busybox：1.29.0` 镜像。
+
+在 `kustomization.yaml` 中添加 `images` 字段来更改镜像 `busybox` 和标签 `1.29.0` 。
+
+- 通过 `kustomize` 添加 `images`：
+    <!-- @addImages @test -->
+    ```bash
+    cd $DEMO_HOME
+    kustomize edit set image busybox=alpine:3.6
+    ```
+
+- 将`images`字段将被添加到`kustomization.yaml`：
+    > ```yaml
+    > images:
+    > - name: busybox
+    >   newName: alpine
+    >   newTag: 3.6
+    > ```
+
+构建 `kustomization`
+<!-- @kustomizeBuild @testAgainstLatestRelease -->
+```bash
+kustomize build $DEMO_HOME
+```
+
+确认`busybox`镜像和标签是否被替换为`alpine：3.6`：
+<!-- @confirmImages @testAgainstLatestRelease -->
+```
+test 2 = \
+  $(kustomize build $DEMO_HOME | grep alpine:3.6 | wc -l); \
+  echo $?
+```

examples/zh/jsonpatch.md

@@ -0,0 +1,124 @@
+# 示例: 应用 json patch（json补丁）
+
+kustomization文件支持通过[JSON patches](https://tools.ietf.org/html/rfc6902)来修改已有的资源.
+
+下面的例子将会使用这个功能对`Ingress`加以修改.
+
+首先，创建一个包含`ingress`的`kustomization`文件.
+
+<!-- @createIngress @testAgainstLatestRelease -->
+```bash
+DEMO_HOME=$(mktemp -d)
+
+cat <<EOF >$DEMO_HOME/kustomization.yaml
+resources:
+- ingress.yaml
+EOF
+
+cat <<EOF >$DEMO_HOME/ingress.yaml
+apiVersion: networking.k8s.io/v1beta1
+kind: Ingress
+metadata:
+  name: my-ingress
+spec:
+  rules:
+  - host: foo.bar.com
+    http:
+      paths:
+      - backend:
+          serviceName: my-api
+          servicePort: 80
+EOF
+```
+
+定义一个JSON patch文件，以更新`Ingress`对象的2个字段:
+
+- 把 host 从 `foo.bar.com` 改为 `foo.bar.io`
+- 把 servicePort 从 `80` 改为 `8080`
+
+<!-- @addJsonPatch @testAgainstLatestRelease -->
+```bash
+cat <<EOF >$DEMO_HOME/ingress_patch.json
+[
+  {"op": "replace", "path": "/spec/rules/0/host", "value": "foo.bar.io"},
+  {"op": "replace", "path": "/spec/rules/0/http/paths/0/backend/servicePort", "value": 8080}
+]
+EOF
+```
+
+JSON patch 也可以写成 YAML 的格式.该例子顺便展示了“添加”操作：
+
+<!-- @addYamlPatch @testAgainstLatestRelease -->
+```bash
+cat <<EOF >$DEMO_HOME/ingress_patch.yaml
+- op: replace
+  path: /spec/rules/0/host
+  value: foo.bar.io
+
+- op: add
+  path: /spec/rules/0/http/paths/-
+  value:
+    path: '/test'
+    backend:
+      serviceName: my-test
+      servicePort: 8081
+EOF
+```
+
+在kustomization.yaml文件中增加 _patchesJson6902_ 字段，以应用该补丁
+
+<!-- @applyJsonPatch @testAgainstLatestRelease -->
+```bash
+cat <<EOF >>$DEMO_HOME/kustomization.yaml
+patchesJson6902:
+- target:
+    group: networking.k8s.io
+    version: v1beta1
+    kind: Ingress
+    name: my-ingress
+  path: ingress_patch.json
+EOF
+```
+
+运行 `kustomize build $DEMO_HOME`, 在输出那里确认 host 已经被正确更新.
+
+<!-- @confirmHost @testAgainstLatestRelease -->
+```bash
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep "host: foo.bar.io" | wc -l); \
+  echo $?
+```
+
+运行 `kustomize build $DEMO_HOME`, 在输出那里确认 servicePort 已经被正确更新.
+
+<!-- @confirmServicePort @testAgainstLatestRelease -->
+
+```bash
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep "servicePort: 8080" | wc -l); \
+  echo $?
+```
+
+如果 patch 是YAML格式的，就能正确解析:
+
+<!-- @applyYamlPatch @testAgainstLatestRelease -->
+```bash
+cat <<EOF >>$DEMO_HOME/kustomization.yaml
+patchesJson6902:
+- target:
+    group: networking.k8s.io
+    version: v1beta1
+    kind: Ingress
+    name: my-ingress
+  path: ingress_patch.yaml
+EOF
+```
+
+运行 `kustomize build $DEMO_HOME`, 在输出那里确认有 `/test` 这个路径.
+
+<!-- @confirmYamlPatch @testAgainstLatestRelease -->
+```bash
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep "path: /test" | wc -l); \
+  echo $?
+```