Merge pull request #1603 from monopole/kustapiversion

Introduce dummy program to help with API releases.

.gitignore

@@ -10,3 +10,9 @@
 
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out
+
+# We use sed -i.bak when doing in-line replace, because it works better cross-platform
+.bak
+
+# macOS
+*.DS_store

.golangci.yml

@@ -0,0 +1,30 @@
+run:
+  deadline: 5m
+
+linters:
+  disable-all: true
+  enable:
+    - dupl
+    - goconst
+    - gocyclo
+    - gofmt
+    - golint
+    - govet
+    - ineffassign
+    - interfacer
+    - lll
+    - misspell
+    - nakedret
+    - structcheck
+    - unparam
+    - varcheck
+
+linters-settings:
+  dupl:
+    threshold: 400 
+  lll:   
+    line-length: 170
+  gocyclo:
+    min-complexity: 15
+  golint:
+    min-confidence: 0.85

.travis.yml

@@ -1,28 +1,37 @@
+os:
+  - linux
+  - osx
+# TODO: Uncomment when tests running on Windows.
+#  - windows
+
+addons:
+  apt:
+    packages:
+    - tree
+  homebrew:
+    packages:
+    - tree
+    update: true
+
+# Only clone the most recent commit.
+git:
+  depth: 1
+
 language: go
 
 go:
-  - 1.10.x
+  - "1.12"
 
-# go_import_path: k8s.io/kubectl
+go_import_path: sigs.k8s.io/kustomize
 
 before_install:
-  - source ./bin/consider-early-travis-exit.sh
-  - sudo apt-get install tree
-  - go get -u github.com/golang/lint/golint
-  - go get -u golang.org/x/tools/cmd/goimports
-  - go get -u github.com/onsi/ginkgo/ginkgo
-  - go get -u github.com/monopole/mdrip
-  - go get -u github.com/fzipp/gocyclo
-  - go get -u gopkg.in/alecthomas/gometalinter.v2 && gometalinter.v2 --install
+  - 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:

CONTRIBUTING.md

@@ -1,36 +1,22 @@
-# Contributing guidelines
+# Contributing Guidelines
 
-[Contributor License Agreement]: https://git.k8s.io/community/CLA.md
-[github workflow guide]: https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md
-[CNCF code of conduct]: https://github.com/cncf/foundation/blob/master/code-of-conduct.md
+Welcome to Kubernetes. We are excited about the prospect of you joining our [community](https://github.com/kubernetes/community)! The Kubernetes community abides by the CNCF [code of conduct](code-of-conduct.md). Here is an excerpt:
 
-## Contributing a Patch
+_As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities._
 
-1. Kubernetes projects require contributors to sign the
-   [Contributor License Agreement] before pull requests
-   can be considered.
-1. Submit an issue describing your proposed change to
-   the repo in question.
-1. The [repo owners](OWNERS) will respond to your issue
-   promptly.
-1. Fork the repo, develop and test your code.
-   See the [github workflow guide].
-1. For _new features_, provide a markdown-based demo following
-   the pattern established in the [examples](examples) directory.
-   Run `bin/pre-commit.sh` to test your demo.
-1. Submit a pull request.
+## Getting Started
 
-## Community, discussion, contribution, and support
+We have full documentation on how to get started contributing here:
 
-Learn how to engage with the Kubernetes community on
-the [community page](http://kubernetes.io/community/).
+- [Contributor License Agreement](https://git.k8s.io/community/CLA.md) Kubernetes projects require that you sign a Contributor License Agreement (CLA) before we can accept your pull requests
+- [Kubernetes Contributor Guide](http://git.k8s.io/community/contributors/guide) - Main contributor documentation, or you can just jump directly to the [contributing section](http://git.k8s.io/community/contributors/guide#contributing)
+- [Contributor Cheat Sheet](https://git.k8s.io/community/contributors/guide/contributor-cheatsheet.md) - Common resources for existing developers
 
-You can reach the maintainers of this project at:
+## Mentorship
 
-- [Slack](http://slack.k8s.io/)
-- [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-kustomize)
+- [Mentoring Initiatives](https://git.k8s.io/community/mentoring) - We have a diverse set of mentorship programs available that are always looking for volunteers!
 
-## Code of conduct
+## Contact Information
 
-Participation in the Kubernetes community is governed
-by the [CNCF code of conduct].
+- [Slack channel](https://kubernetes.slack.com/messages/sig-cli)
+- [Mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-cli)

Gopkg.lock

@@ -1,381 +0,0 @@
-# This file is autogenerated, do not edit; changes may be undone by the next 'dep ensure'.
-
-
-[[projects]]
-  digest = "1:8e47871087b94913898333f37af26732faaab30cdb41571136cf7aec9921dae7"
-  name = "github.com/PuerkitoBio/purell"
-  packages = ["."]
-  pruneopts = ""
-  revision = "0bcb03f4b4d0a9428594752bd2a3b9aa0a9d4bd4"
-  version = "v1.1.0"
-
-[[projects]]
-  branch = "master"
-  digest = "1:331a419049c2be691e5ba1d24342fc77c7e767a80c666a18fd8a9f7b82419c1c"
-  name = "github.com/PuerkitoBio/urlesc"
-  packages = ["."]
-  pruneopts = ""
-  revision = "de5bf2ad457846296e2031421a34e2568e304e35"
-
-[[projects]]
-  digest = "1:56c130d885a4aacae1dd9c7b71cfe39912c7ebc1ff7d2b46083c8812996dc43b"
-  name = "github.com/davecgh/go-spew"
-  packages = ["spew"]
-  pruneopts = ""
-  revision = "346938d642f2ec3594ed81d874461961cd0faa76"
-  version = "v1.1.0"
-
-[[projects]]
-  digest = "1:971e9ba63a417c5f1f83ab358677bc59e96ff04285f26c6646ff089fb60b15e8"
-  name = "github.com/emicklei/go-restful"
-  packages = [
-    ".",
-    "log",
-  ]
-  pruneopts = ""
-  revision = "3658237ded108b4134956c1b3050349d93e7b895"
-  version = "v2.7.1"
-
-[[projects]]
-  digest = "1:dcefbadf4534c5ecac8573698fba6e6e601157bfa8f96aafe29df31ae582ef2a"
-  name = "github.com/evanphx/json-patch"
-  packages = ["."]
-  pruneopts = ""
-  revision = "afac545df32f2287a079e2dfb7ba2745a643747e"
-  version = "v3.0.0"
-
-[[projects]]
-  digest = "1:b13707423743d41665fd23f0c36b2f37bb49c30e94adb813319c44188a51ba22"
-  name = "github.com/ghodss/yaml"
-  packages = ["."]
-  pruneopts = ""
-  revision = "0ca9ea5df5451ffdf184b4428c902747c2c11cd7"
-  version = "v1.0.0"
-
-[[projects]]
-  branch = "master"
-  digest = "1:e116a4866bffeec941056a1fcfd37e520fad1ee60e4e3579719f19a43c392e10"
-  name = "github.com/go-openapi/jsonpointer"
-  packages = ["."]
-  pruneopts = ""
-  revision = "3a0015ad55fa9873f41605d3e8f28cd279c32ab2"
-
-[[projects]]
-  branch = "master"
-  digest = "1:3830527ef0f4f9b268d9286661c0f52f9115f8aefd9f45ee7352516f93489ac9"
-  name = "github.com/go-openapi/jsonreference"
-  packages = ["."]
-  pruneopts = ""
-  revision = "3fb327e6747da3043567ee86abd02bb6376b6be2"
-
-[[projects]]
-  branch = "master"
-  digest = "1:238a056875c4b053b4b29984765ee335bf8c539fdf17e527fd9b7aa72521c8dd"
-  name = "github.com/go-openapi/spec"
-  packages = ["."]
-  pruneopts = ""
-  revision = "bcff419492eeeb01f76e77d2ebc714dc97b607f5"
-
-[[projects]]
-  branch = "master"
-  digest = "1:7b067ca8b94982960860d18c42e29f15bbd0e8d9ae8145a83a218296e75393cf"
-  name = "github.com/go-openapi/swag"
-  packages = ["."]
-  pruneopts = ""
-  revision = "811b1089cde9dad18d4d0c2d09fbdbf28dbd27a5"
-
-[[projects]]
-  digest = "1:0a3f6a0c68ab8f3d455f8892295503b179e571b7fefe47cc6c556405d1f83411"
-  name = "github.com/gogo/protobuf"
-  packages = [
-    "proto",
-    "sortkeys",
-  ]
-  pruneopts = ""
-  revision = "1adfc126b41513cc696b209667c8656ea7aac67c"
-  version = "v1.0.0"
-
-[[projects]]
-  branch = "master"
-  digest = "1:107b233e45174dbab5b1324201d092ea9448e58243ab9f039e4c0f332e121e3a"
-  name = "github.com/golang/glog"
-  packages = ["."]
-  pruneopts = ""
-  revision = "23def4e6c14b4da8ac2ed8007337bc5eb5007998"
-
-[[projects]]
-  digest = "1:f958a1c137db276e52f0b50efee41a1a389dcdded59a69711f3e872757dab34b"
-  name = "github.com/golang/protobuf"
-  packages = [
-    "proto",
-    "ptypes",
-    "ptypes/any",
-    "ptypes/duration",
-    "ptypes/timestamp",
-  ]
-  pruneopts = ""
-  revision = "b4deda0973fb4c70b50d226b1af49f3da59f5265"
-  version = "v1.1.0"
-
-[[projects]]
-  branch = "master"
-  digest = "1:754f77e9c839b24778a4b64422236d38515301d2baeb63113aa3edc42e6af692"
-  name = "github.com/google/gofuzz"
-  packages = ["."]
-  pruneopts = ""
-  revision = "24818f796faf91cd76ec7bddd72458fbced7a6c1"
-
-[[projects]]
-  digest = "1:2a131706ff80636629ab6373f2944569b8252ecc018cda8040931b05d32e3c16"
-  name = "github.com/googleapis/gnostic"
-  packages = [
-    "OpenAPIv2",
-    "compiler",
-    "extensions",
-  ]
-  pruneopts = ""
-  revision = "ee43cbb60db7bd22502942cccbc39059117352ab"
-  version = "v0.1.0"
-
-[[projects]]
-  digest = "1:870d441fe217b8e689d7949fef6e43efbc787e50f200cb1e70dbca9204a1d6be"
-  name = "github.com/inconshreveable/mousetrap"
-  packages = ["."]
-  pruneopts = ""
-  revision = "76626ae9c91c4f2a10f34cad8ce83ea42c93bb75"
-  version = "v1.0"
-
-[[projects]]
-  digest = "1:9eab2325abbed0ebcee9d44bb3660a69d5d10e42d5ac4a0e77f7a6ea22bfce88"
-  name = "github.com/json-iterator/go"
-  packages = ["."]
-  pruneopts = ""
-  revision = "ca39e5af3ece67bbcda3d0f4f56a8e24d9f2dad4"
-  version = "1.1.3"
-
-[[projects]]
-  branch = "master"
-  digest = "1:d9e483f4b9e306facf126bd90b02d512bd22ea4471e1568867e32221a8abbb16"
-  name = "github.com/mailru/easyjson"
-  packages = [
-    "buffer",
-    "jlexer",
-    "jwriter",
-  ]
-  pruneopts = ""
-  revision = "3fdea8d05856a0c8df22ed4bc71b3219245e4485"
-
-[[projects]]
-  digest = "1:0c0ff2a89c1bb0d01887e1dac043ad7efbf3ec77482ef058ac423d13497e16fd"
-  name = "github.com/modern-go/concurrent"
-  packages = ["."]
-  pruneopts = ""
-  revision = "bacd9c7ef1dd9b15be4a9909b8ac7a4e313eec94"
-  version = "1.0.3"
-
-[[projects]]
-  digest = "1:420f9231f816eeca3ff5aab070caac3ed7f27e4d37ded96ce9de3d7a7a2e31ad"
-  name = "github.com/modern-go/reflect2"
-  packages = ["."]
-  pruneopts = ""
-  revision = "1df9eeb2bb81f327b96228865c5687bc2194af3f"
-  version = "1.0.0"
-
-[[projects]]
-  digest = "1:7365acd48986e205ccb8652cc746f09c8b7876030d53710ea6ef7d0bd0dcd7ca"
-  name = "github.com/pkg/errors"
-  packages = ["."]
-  pruneopts = ""
-  revision = "645ef00459ed84a119197bfb8d8205042c6df63d"
-  version = "v0.8.0"
-
-[[projects]]
-  digest = "1:74c32990510c9f188556aa17600313e867d1d06f5a9db244056a95d144ec34ce"
-  name = "github.com/spf13/cobra"
-  packages = ["."]
-  pruneopts = ""
-  revision = "a1f051bc3eba734da4772d60e2d677f47cf93ef4"
-  version = "v0.0.2"
-
-[[projects]]
-  digest = "1:8e243c568f36b09031ec18dff5f7d2769dcf5ca4d624ea511c8e3197dc3d352d"
-  name = "github.com/spf13/pflag"
-  packages = ["."]
-  pruneopts = ""
-  revision = "583c0c0531f06d5278b7d917446061adc344b5cd"
-  version = "v1.0.1"
-
-[[projects]]
-  branch = "master"
-  digest = "1:9e548233d0dc00e74be262e54a9d1bbe7e4c19e5951083520261740e37daeb02"
-  name = "golang.org/x/net"
-  packages = [
-    "http/httpguts",
-    "http2",
-    "http2/hpack",
-    "idna",
-  ]
-  pruneopts = ""
-  revision = "2491c5de3490fced2f6cff376127c667efeed857"
-
-[[projects]]
-  digest = "1:5acd3512b047305d49e8763eef7ba423901e85d5dd2fd1e71778a0ea8de10bd4"
-  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 = ""
-  revision = "f21a4dfb5e38f5895301dc265a8def02365cc3d0"
-  version = "v0.3.0"
-
-[[projects]]
-  digest = "1:75fb3fcfc73a8c723efde7777b40e8e8ff9babf30d8c56160d01beffea8a95a6"
-  name = "gopkg.in/inf.v0"
-  packages = ["."]
-  pruneopts = ""
-  revision = "d2d2541c53f18d2a059457998ce2876cc8e67cbf"
-  version = "v0.9.1"
-
-[[projects]]
-  digest = "1:f0620375dd1f6251d9973b5f2596228cc8042e887cd7f827e4220bc1ce8c30e2"
-  name = "gopkg.in/yaml.v2"
-  packages = ["."]
-  pruneopts = ""
-  revision = "5420a8b6744d3b0345ab293f6fcba19c978f1183"
-  version = "v2.2.1"
-
-[[projects]]
-  branch = "master"
-  digest = "1:663df6da5560210fc39194a0a2c4fceba09ead717c330f1174bb15597cf18ce8"
-  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 = ""
-  revision = "53d615ae3f440f957cb9989d989d597f047262d9"
-
-[[projects]]
-  branch = "master"
-  digest = "1:bcb2285bb525712de7903a5d254c2789df65c8b58d2cfac5a26d950ad94c2079"
-  name = "k8s.io/apimachinery"
-  packages = [
-    "pkg/api/resource",
-    "pkg/apis/meta/v1",
-    "pkg/apis/meta/v1/unstructured",
-    "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 = ""
-  revision = "13b73596e4b63e03203e86f6d9c7bcc1b937c62f"
-
-[[projects]]
-  digest = "1:071cc2f032b701b9dba26568e040940f26931a49e3a3985f3375f17f7f6d9c5f"
-  name = "k8s.io/client-go"
-  packages = ["kubernetes/scheme"]
-  pruneopts = ""
-  revision = "23781f4d6632d88e869066eaebb743857aa1ef9b"
-  version = "v7.0.0"
-
-[[projects]]
-  branch = "master"
-  digest = "1:386c5d69077ce740614e8309ddf107dde91a5db25d3d779143f452fb4fbdfd1e"
-  name = "k8s.io/kube-openapi"
-  packages = [
-    "pkg/common",
-    "pkg/util/proto",
-  ]
-  pruneopts = ""
-  revision = "b3f03f55328800731ce03a164b80973014ecd455"
-
-[solve-meta]
-  analyzer-name = "dep"
-  analyzer-version = 1
-  input-imports = [
-    "github.com/evanphx/json-patch",
-    "github.com/ghodss/yaml",
-    "github.com/golang/glog",
-    "github.com/pkg/errors",
-    "github.com/spf13/cobra",
-    "k8s.io/api/core/v1",
-    "k8s.io/apimachinery/pkg/apis/meta/v1",
-    "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured",
-    "k8s.io/apimachinery/pkg/runtime",
-    "k8s.io/apimachinery/pkg/runtime/schema",
-    "k8s.io/apimachinery/pkg/util/mergepatch",
-    "k8s.io/apimachinery/pkg/util/sets",
-    "k8s.io/apimachinery/pkg/util/strategicpatch",
-    "k8s.io/apimachinery/pkg/util/validation",
-    "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"
-
-
-[[constraint]]
-  name = "github.com/evanphx/json-patch"
-  version = "3.0.0"
-
-[[constraint]]
-  name = "github.com/ghodss/yaml"
-  version = "1.0.0"
-
-[[constraint]]
-  branch = "master"
-  name = "github.com/golang/glog"
-
-[[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"
-
-[[constraint]]
-  branch = "master"
-  name = "k8s.io/utils"
-
-[[constraint]]
-  branch = "master"
-  name = "github.com/go-openapi/spec"

INSTALL.md

@@ -1,27 +0,0 @@
-[release page]: https://github.com/kubernetes-sigs/kustomize/releases
-[Go]: https://golang.org
-
-## Installation
-
-Download a binary from the [release page].
-
-Or try this to grab the latest official release
-using the command line:
-
-```
-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
-```
-
-To install from head with [Go] v1.10.1 or higher:
-
-<!-- @installkustomize @test -->
-```
-go get github.com/kubernetes-sigs/kustomize
-```

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

OWNERS_ALIASES

@@ -1,6 +1,5 @@
 aliases:
   kustomize-admins:
-    - grodrigues3
     - monopole
     - pwittrock
   kustomize-maintainers:

README.md

@@ -7,14 +7,32 @@ 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].
+
 
 [![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
 
@@ -113,21 +131,46 @@ The YAML can be directly [applied] to a cluster:
 > kustomize build ~/someApp/overlays/production | kubectl apply -f -
 > ```
 
-## About
+## Community
 
-This tool is sponsored by [sig-cli] ([KEP]).
+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
+   and label it [kind/feature].
+
+### Other communication channels
+
+- [Slack]
+- [Mailing List]
+- General kubernetes [community page]
+
+### Code of conduct
+
+Participation in the Kubernetes community
+is governed by the [Kubernetes Code of Conduct].
 
-[KEP]: https://github.com/kubernetes/community/blob/master/keps/sig-cli/0008-kustomize.md
 [`make`]: https://www.gnu.org/software/make
 [`sed`]: https://www.gnu.org/software/sed
+[DAM]: docs/glossary.md#declarative-application-management
+[KEP]: https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/0008-kustomize.md
+[Kubernetes Code of Conduct]: code-of-conduct.md
+[Mailing List]: https://groups.google.com/forum/#!forum/kubernetes-sig-cli
+[Slack]: https://kubernetes.slack.com/messages/sig-cli
 [applied]: docs/glossary.md#apply
 [base]: docs/glossary.md#base
+[community page]: http://kubernetes.io/community/
 [declarative configuration]: docs/glossary.md#declarative-application-management
-[examples]: examples/README.md
-[imageBase]: docs/base.jpg
-[imageOverlay]: docs/overlay.jpg
-[install]: INSTALL.md
+[eschewed feature list]: docs/eschewedFeatures.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
@@ -138,4 +181,6 @@ This tool is sponsored by [sig-cli] ([KEP]).
 [sig-cli]: https://github.com/kubernetes/community/blob/master/sig-cli/README.md
 [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,90 +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 go_dirs {
-  go list -f '{{.Dir}}' ./... | tail -n +2 | tr '\n' '\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 testGoFmt {
-  diff <(echo -n) <(go_dirs | xargs -0 gofmt -s -d -l)
-}
-
-
-function testGoCyclo {
-  diff <(echo -n) <(go_dirs | xargs -0 gocyclo -over 15)
-}
-
-function testGoLint {
-  diff -u <(echo -n) <(go_dirs | xargs -0 golint --min_confidence 0.85 )
-}
-
-function testGoMetalinter {
-  diff -u <(echo -n) <(go_dirs | xargs -0 gometalinter.v2 --disable-all --deadline 5m \
-  --enable=misspell \
-  --enable=structcheck \
-  --enable=deadcode \
-# Disabling 'goimports' because it reports hyphens in imported package \
-# names as errors, and we have to vendor them in regardless. \
-#  --enable=goimports \
-  --enable=varcheck \
-  --enable=goconst \
-  --enable=unparam \
-  --enable=ineffassign \
-  --enable=nakedret \
-  --enable=interfacer \
-  --enable=misspell \
-  --line-length=170 --enable=lll \
-  --dupl-threshold=400 --enable=dupl)
-}
-
-
-function testGoVet {
-  go vet -all ./...
-}
-
-function testGoTest {
-  go test -v ./...
-}
-
-function testExamples {
-  mdrip --mode test --label test README.md ./examples
-}
-
-runTest testGoFmt
-runTest testGoMetalinter
-runTest testGoLint
-runTest testGoVet
-runTest testGoCyclo
-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="kubernetes-sigs"
-REPO="kustomize"
-
-GO_PKG_OWNER=$GOPATH/src/github.com/$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 github.com/kubernetes-sigs/kustomize/pkg/commands.kustomizeVersion={{.Version}} -X github.com/kubernetes-sigs/kustomize/pkg/commands.gitCommit={{.Commit}} -X github.com/kubernetes-sigs/kustomize/pkg/commands.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

code-of-conduct.md

@@ -1,6 +1,3 @@
-[Kubernetes Community Code of Conduct]: https://git.k8s.io/community/code-of-conduct.md
+# Kubernetes Community Code of Conduct
 
-# Code of Conduct
-
-This project has adopted the
-[Kubernetes Community Code of Conduct].
+Please refer to our [Kubernetes Community Code of Conduct](https://git.k8s.io/community/code-of-conduct.md)

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

@@ -0,0 +1,52 @@
+[release page]: https://github.com/kubernetes-sigs/kustomize/releases
+[Go]: https://golang.org
+
+# Installation
+
+Binaries at various versions for linux, macOs and Windows
+are available on the [release page].
+
+Or...
+
+## Quickly curl the latest
+
+```
+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
+```
+
+## Get and install source for a particular release
+
+For example
+```
+# 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

@@ -0,0 +1,69 @@
+English | [简体中文](zh/README.md)
+
+# Documentation
+
+ * [Installation](INSTALL.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
+
+ * [kustomize/3.2.2](https://github.com/kubernetes-sigs/kustomize/releases/tag/kustomize%2Fv3.2.2) - kustomize CLI
+   moved to depend on kustomize Go API [3.3.0](v3.3.0.md).
+
+ * [API 3.3.0](v3.3.0.md) - First release of the kustomize Go API
+   in a module excluding the `kustomize` CLI.  From here on,
+   the CLI and API will release independently.
+ 
+ * [kustomize/3.2.1](https://github.com/kubernetes-sigs/kustomize/releases/tag/kustomize%2Fv3.2.1) - Patch release
+   of `kustomize` CLI in its own module,
+   depending on Go API release [3.2.0](v3.2.0.md).
+
+ * [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/eschewedFeatures.md

@@ -1,13 +1,22 @@
 # Eschewed Features
 
+The maintainers established this list to
+place bounds on the kustomize feature
+set.  The bounds can be changed with
+a consensus on the risks.
+
+For a bigger picture about why kustomize
+does some things and not others, see the
+glossary entry for [DAM].
+
 ## Removal directives
 
 `kustomize` supports configurations that can be reasoned about as
 _compositions_ or _mixins_ - concepts that are widely accepted as
 a best practice in various programming languages.
 
-To this end, `kustomize` offers various _addition_ directives.  One
-can add labels, annotations, patches, resources and bases.
+To this end, `kustomize` offers various _addition_ directives.
+One may add labels, annotations, patches, resources, bases, etc.
 Corresponding _removal_ directives are not offered.
 
 Removal semantics would introduce many possibilities for
@@ -27,6 +36,48 @@ what you don't want and commit it to your private fork, then use
 kustomize on your fork.  As often as desired, use _git rebase_ to
 capture improvements from the upstream base.
 
+## Unstructured edits
+
+_Structured edits_ are changes controlled by
+knowledge of the k8s API, and YAML or JSON syntax.
+
+Most edits performed by kustomize can be expressed as
+[JSON patches] or [SMP patches].  Common edits, like
+adding labels or adding a name prefix, get dedicated 
+shorthand commands.  Another class of edits take
+data from one specific object's field and use it in
+another (e.g. a service object's name found and
+copied into a container's command line).
+
+These edits are designed to create valid output
+given valid input, and can provide syntactically
+and semantically informed error messages if inputs
+are invalid.
+
+_Unstructured edits_, e.g. a templating approach,
+or a command to replace any target string in the
+character stream with some other string, aren't
+limited by any syntax or object structure.
+  
+Such powerful techniques are eschewed because
+- There would be no way to say that a kustomization
+  was correct without running it and checking
+  the output.
+- Errors in the output would be
+  disconnected from the edit that caused it.
+- They are toil to maintain by a rotating
+  staff of operators.
+    
+Kustomizations are meant to be sharable and stackable.
+Imagine tracing down a problem rooted in a
+clever set of stacked regexp replacements
+performed by various overlays on some remote base. 
+
+Other tools (sed, jinja, erb, envsubst, helm, ksonnet,
+etc.) provide varying degrees of unstructured editting
+and/or embedded languages, and can be used instead
+of, or in a pipe with, kustomize.
+
 ## Build-time side effects from CLI args or env variables
 
 `kustomize` supports the best practice of storing one's
@@ -35,7 +86,7 @@ entire configuration in a version control system.
 Changing `kustomize build` configuration output as a result
 of additional arguments or flags to `build`, or by
 consulting shell environment variable values in `build`
-code, would violate that goal.
+code, would frustrate that goal.
 
 `kustomize` insteads offers [kustomization] file `edit`
 commands.  Like any shell command, they can accept
@@ -45,7 +96,7 @@ For example, to set the tag used on an image to match an
 environment variable, run
 
 ```
-kustomize edit set imagetag nginx:$MY_NGINX_VERSION
+kustomize edit set image nginx:$MY_NGINX_VERSION
 ```
 
 as part of some encapsulating work flow executed before
@@ -70,11 +121,10 @@ commands that accept globbed arguments, expand them at _edit
 time_ relative to the local file system, and store the resulting
 explicit names into the kustomization file.
 
-In this way the resources, patches and bases used at _build time_
-remain explicitly declared in version control.
-
-
 [base]: glossary.md#base
+[DAM]: glossary.md#declarative-application-management
+[java import]: https://www.codebyamir.com/blog/pitfalls-java-import-wildcards
+[JSON patches]: glossary.md#patchjson6902
 [kustomization]: glossary.md#kustomization
 [OTS workflow]: workflows.md#off-the-shelf-configuration
-[java import]: https://www.codebyamir.com/blog/pitfalls-java-import-wildcards
+[SMP patches]: glossary.md#patchstrategicmerge

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

@@ -1,7 +1,11 @@
 # Glossary
-
+[CRD spec]: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/
+[CRD]: #custom-resource-definition
 [DAM]: #declarative-application-management
+[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
@@ -15,17 +19,24 @@
 [kubernetes]: #kubernetes
 [kustomize]: #kustomize
 [kustomization]: #kustomization
-[off-the-shelf]: #off-the-shelf
+[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
 [resource]: #resource
 [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
@@ -66,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.
 
@@ -92,25 +104,46 @@ simpler than the workflow associated with an
 periodically capturing someone else's upgrades to the
 [off-the-shelf] config.
 
+## custom resource definition
+
+One can extend the k8s API by making a
+Custom Resource Definition ([CRD spec]).
+
+This defines a custom [resource] (CD), an entirely
+new resource that can be used alongside _native_
+resources like ConfigMaps, Deployments, etc.
+
+Kustomize can customize a CD, but to do so
+kustomize must also be given the corresponding CRD
+so that it can interpret the structure correctly.
+
 ## declarative application management
 
-_Declarative Application Management_ (DAM) is a [set of
-ideas](https://goo.gl/T66ZcD) aiming to ease management
-of k8s clusters.
+Kustomize aspires to support [Declarative Application Management],
+a set of best practices around managing k8s clusters.
 
- * Works with any configuration, be it bespoke,
+In brief, kustomize should
+
+ * Work with any configuration, be it bespoke,
    off-the-shelf, stateless, stateful, etc.
- * Supports common customizations, and creation of
-   [variants] (dev vs. staging vs. production).
- * Exposes and teaches native k8s APIs, rather than
-   hiding them.
- * No friction integration with version control to
+ * Support common customizations, and creation of
+   [variants] (e.g. _development_ vs.
+   _staging_ vs. _production_).
+ * Expose and teach native k8s APIs, rather than
+   hide them.
+ * Add no friction to version control integration to
    support reviews and audit trails.
- * Composable with other tools in a unix sense.
- * Eschews crossing the line into templating, domain
+ * Compose with other tools in a unix sense.
+ * Eschew crossing the line into templating, domain
    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
@@ -119,26 +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.
 
- * Immediate customization declarations, e.g.
-   _namePrefix_, _commonLabels_, etc.
- * Resource _generators_ for configmaps and secrets.
- * References to _external files_ in these categories:
-   * [resources] - completely specified k8s API objects,
-      e.g. `deployment.yaml`, `configmap.yaml`, etc.
-   * [patches] - _partial_ resources that modify full
-     resources defined in a [base]
-     (only meaningful in an [overlay]).
-   * [bases] - path to a directory containing
-     a [kustomization] (only meaningful in an [overlay]).
- * (_TBD_) Standard k8s API kind-version fields.
+When a kustomization file is processed, it may or may
+not be able to access files outside its root.
+
+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.
+
+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
 
@@ -161,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].
 
@@ -198,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.
 
@@ -217,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:
 
@@ -232,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
 
@@ -242,35 +352,81 @@ management tool in the tradition of, say, [apt] or
 
 ## patch
 
-A _patch_ is a partially defined k8s resource with a
-name that must match a resource already known per
-traversal rules built into [kustomize].
+General instructions to modify a resource.
 
-_Patch_ is a field in the kustomization, distinct from
-resources, because a patch file looks like a resource
-file, but has different semantics.  A patch depends on
-(modifies) a resource, whereas a resource has no
-dependencies.  Since any resource file can be used as a
-patch, one cannot reliably distinguish a resource from
-a patch just by looking at the file's [YAML].
+There are two alternative techniques with similar
+power but different notation - the
+[strategic merge patch](#patchstrategicmerge)
+and the [JSON patch](#patchjson6902).
+
+## patchStrategicMerge
+
+A _patchStrategicMerge_ is [strategic-merge]-style patch (SMP).
+
+An SMP looks like an incomplete YAML specification of
+a k8s resource.  The SMP includes `TypeMeta`
+fields to establish the group/version/kind/name of the
+[resource] to patch, then just enough remaining fields
+to step into a nested structure to specify a new field
+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
+value is a list.
+
+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].
+
+Fun fact - any resource file can be used as
+an SMP, overwriting matching fields in another
+resource with the same group/version/kind/name,
+but leaving all other fields as they were.
+
+TODO(monopole): add ptr to example.
+
+## patchJson6902
+
+A _patchJson6902_ refers to a kubernetes [resource] and
+a [JSONPatch] specifying how to change the resource.
+
+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 kustomize, is a path to
-a [YAML] or [JSON] file that completely defines a
-functional k8s API object, like a deployment or a
-configmap.
+A _resource_ in the context of a REST-ful API is the
+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 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
 
-A _resource_ in the content of a REST-ful API is the
-target of an HTTP operation like _GET_, _PUT_ or
-_POST_.  k8s offers a RESTful API surface to interact
-with clients.
-
+See [kustomization root][root].
 
 ## sub-target / sub-application / sub-package
 
@@ -285,14 +441,19 @@ The _target_ is the argument to `kustomize build`, e.g.:
 >  kustomize build $target
 > ```
 
-`$target` must be a path 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,202 +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 kustomize.yaml to reduce the content
-# visible in configuration reviews.
-# ----------------------------------------------------
-
-# 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-
-
-# 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
-- ../some-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 a ConfigMap with the
-# names and contents of the given files.
-configMapGenerator:
-- name: myJavaServerProps
-  files:
-  - application.properties
-  - more.properties
-
-# Each entry in this list results in the creation of
-# one Secret resource (it's a generator of n secrets).
-# A command can do anything to get a secret,
-# e.g. prompt the user directly, start a webserver to
-# initate an oauth dance, etc.
-secretGenerator:
-- name: app-tls
-  commands:
-    tls.crt: "cat secret/tls.cert"
-    tls.key: "cat secret/tls.key"
-  type: "kubernetes.io/tls"
-- name: downloaded_secret
-  commands:
-    username: "curl -s https://path/to/secrets/username.yaml"
-    password: "curl -s https://path/to/secrets/password.yaml"
-  type: Opaque
-
-# Each entry in this list should resolve to a directory
-# containing a kustomization file, else the
-# customization fails.
-#
-# 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
-
-# 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.
-patches:
-- service_port_8888.yaml
-- deployment_increase_replicas.yaml
-- deployment_increase_memory.yaml
-
-
-# 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 kustomization, the ConfigMap object name may change by adding namePrefix or hashing
-# The name reference for this ConfigMap object in CRD object need to be
-# updated with namePrefix or hashing in the same way.
-crds:
-- crds/typeA.yaml
-- crds/typeB.yaml
-
-# Vars are used to insert values from resources that cannot be referenced
-# otherwise. For example if you need to pass a Service's name to the arguments
-# or environment variables of a program but without hard coding the actual name
-# of the Service you'd insert `$(MY_SERVICE_NAME)` into the value field of the
-# env var or into the command or args of the container as shown here:
-# ```
-#   containers:
-#     - image: myimage
-#       command: ["start", "--host", "$(MY_SERVICE_NAME)"]
-#       env:
-#         - name: SECRET_TOKEN
-#           value: $(SOME_SECRET_NAME)
-# ```
-#
-# Then you'll add an entry to `vars:` like shown below with the same name
-# and a reference to the resource from which to pull the field's value.
-# The actual field's path is optional and by default it will use
-# `metadata.name`. Currently only string type fields are supported, no integers
-# or booleans, etc. Also array access is currently not possible. For example getting
-# the image field of container number 2 inside of a pod can currently not be done.
-#
-# Not every location of a variable is supported. To see a complete list of locations
-# see the file [refvars.go](https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/transformers/refvars.go#L20).
-#
-# An example of a situation where you'd not use vars is when you'd like to set a
-# pod's `serviceAccountName`. In that case you would just reference the ServiceAccount
-# by name and Kustomize will resolve it to the eventual name while building the manifests.
-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
-
-# ImageTags modify the tags for images without creating patches.
-# E.g. Given this fragment of a Deployment:
-# ```
-#  containers:
-#    - name: myapp
-#      image: mycontainerregistry/myimage:v0
-#    - name: nginxapp
-#      image: nginx:1.7.9
-#```
-# one can change the tag of myimage to v1 and the tag of nginx to 1.8.0 with the following:
-imageTags:
-  - name: mycontainerregistry/myimage
-    newTag: v1
-  - name: nginx
-    newTag: 1.8.0

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/v3.3.0.md

@@ -0,0 +1,114 @@
+# kustomize 3.3.0
+ 
+[versioning policy documentation]: https://github.com/kubernetes-sigs/kustomize/blob/master/docs/versioningPolicy.md
+[release process documentation]: https://github.com/kubernetes-sigs/kustomize/tree/master/releasing
+ 
+## Summary of changes
+
+### First release of the Go API-only module.
+
+Many of the PRs since the last kustomize release were
+around restructuring the _sigs.k8s.io/kustomize_
+repository into three Go modules instead of just one.
+
+The reasons for this are detailed in the [versioning
+policy documentation], and what it means for releasing
+is explained in the [release process documentation].
+
+The tl;dr is that the top level module
+`sigs.k8s.io/kustomize` now defines the kustomize Go
+API, and the _kustomize_ CLI sits below it in an
+independent module `sigs.k8s.io/kustomize/kustomize`.
+
+The modules release independently, though in practice a
+new release of the kustomize Go API will likely be
+followed quickly by a new release of the `kustomize`
+executable.
+
+This is a necessary step to creating a much smaller
+kustomize Go API surface that has some hope of
+conforming to semantic versioning and being of some use
+to clients.
+
+The kustomize CLI will see the same kustomize Go API as
+any other client.
+
+The new semver-able API will begin with `v4.0.0` (not
+yet released) and be a clean break with `v3` etc.
+
+
+### Change log since v3.2.0
+
+```
+3c9d828f - Have kustomize CLI depend on kustomize Go API v3.3.0 (Jeffrey Regan)
+5d800f0b - Merge pull request #1595 from monopole/threeReleases (Jeff Regan)
+4eb2d5bc - Three builders. (Jeffrey Regan)
+988af1ff - Update README.md (Jeff Regan)
+1617183e - Merge pull request #1590 from monopole/releaseProcessUpdate (Kubernetes Prow Robot)
+ee727464 - update release process doc (jregan)
+c9e7dc3b - Merge pull request #1589 from monopole/moreTestsAroundKustFileName (Jeff Regan)
+07e0e46a - improve tests for alternative kustomization file names (Jeffrey Regan)
+404d2d63 - Merge pull request #1587 from monopole/reducePgmconfig (Jeff Regan)
+baa0296a - Reduce size of pgmconfig package (Jeffrey Regan)
+0f665ac1 - Merge pull request #1544 from ptux/add-transformer-href (Jeff Regan)
+14b0a650 - Merge pull request #1581 from monopole/refactorFs (Jeff Regan)
+2d58f8b8 - Break the dep between fs and pgmconfig. (Jeffrey Regan)
+9a43ca53 - Merge pull request #1578 from nlamirault/fix/build-plugins-doc (Jeff Regan)
+5372fc6f - Merge pull request #1579 from monopole/fsPackageCleanup (Jeff Regan)
+86bc3440 - Merge pull request #1513 from nimohunter/fix_empty_list_item (Kubernetes Prow Robot)
+a014f7d4 - Merge pull request #1561 from beautytiger/dev-190925 (Jeff Regan)
+9a94bcb8 - Improve fs package and doc in prep to officially go public (Jeffrey Regan)
+07634ef0 - Merge pull request #1575 from monopole/versioning (Jeff Regan)
+995f88d6 - Update versioning notes. (jregan)
+334a6467 - Fix: documentation link for plugins (Nicolas Lamirault)
+08963ba5 - improve test code coverage in transformers (Guangming Wang)
+326fb689 - Merge pull request #1570 from bzub/1234-go_plugin_doc (Jeff Regan)
+970ce67c - Update goPluginCaveats.md (Jeff Regan)
+98d18930 - Update INSTALL.md (Jeff Regan)
+d89b448c - Fix git tag recovery in cloud build. (Jeff Regan)
+17bf9d32 - Update releasing README. (Jeff Regan)
+a99aff1d - Merge pull request #1571 from monopole/updateCloudBuildProcess (Kubernetes Prow Robot)
+a694ac7b - Update cloud build process for kustomize. (Jeffrey Regan)
+b5b11ef6 - Fix compile kustomize example. (bzub)
+fa1af6f5 - Merge pull request #1473 from richardmarshall/execpluginhash (Jeff Regan)
+9288dec0 - Fix failing BashedConfigMapTest (Jeff Regan)
+1a45dd0b - Merge pull request #1566 from monopole/releaseNotes3.2.1 (Kubernetes Prow Robot)
+592c5acf - docs: Exec plugin generator options (Richard Marshall)
+ac9424fa - tests: Add unit tests for update resource options (Richard Marshall)
+79fbe7c4 - Support resource generator options in exec plugins (Richard Marshall)
+f69d526f - v3.2.1 release notes (Jeff Regan)
+07a95a60 - Merge pull request #1565 from monopole/tweakBinaryDepsBeforeTagging (Jeff Regan)
+032b3857 - Pin the kustomize binary's dependence on kustomize libs. (jregan)
+81062959 - Merge pull request #1564 from monopole/moveKustomizeBinaryToOwnModule (Kubernetes Prow Robot)
+b82a8fd3 - Move the kustomize binary to its own module. (Jeffrey Regan)
+2d0c22d6 - Merge pull request #1562 from keleustes/tools (Kubernetes Prow Robot)
+aa342def - Pin tool versions using go modules (Ian Howell)
+10786ec0 - Merge pull request #1554 from keleustes/readme (Kubernetes Prow Robot)
+7c705687 - Update README.md to include Kubernetes 1.16 (Jerome Brette)
+e8933d97 - Merge pull request #1560 from monopole/precommitTuneup (Jeff Regan)
+9d7b6544 - Make pre-commit more portable and less tricky. (jregan)
+7a0946a9 - Merge pull request #1558 from monopole/dependOnNewPluginatorModule (Jeff Regan)
+def4f045 - Depend on new pluginator location. (Jeffrey Regan)
+2f2408f1 - Merge pull request #1559 from monopole/compressCopyright (Jeff Regan)
+3b9bcc48 - Compress copyright in the commands package. (Jeffrey Regan)
+d0429ff4 - Merge pull request #1557 from monopole/pluginatorModule (Jeff Regan)
+33deefc3 - Copy pluginator to its own module. (Jeffrey Regan)
+9b3de82b - Merge pull request #1506 from Liujingfang1/release (Jeff Regan)
+d217074f - Merge pull request #1550 from keleustes/apiversion (Kubernetes Prow Robot)
+1d90ba7c - Fix typo in apiVersion yaml declaration (Jerome Brette)
+eeeb4c36 - Merge pull request #1547 from keleustes/extensions (Kubernetes Prow Robot)
+b1faa989 - Update Ingress apiVersion to networking.k8s.io/v1beta1 (Jerome Brette)
+d8250c9e - move test case (nimohunter)
+c9500466 - add transformer href (Wang(わん))
+0c32691e - Merge pull request #1537 from jaypipes/gomod-install-note (Kubernetes Prow Robot)
+88b1d627 - Merge pull request #1541 from rtnpro/patch-1 (Jeff Regan)
+aec82066 - Update INSTALL.md (Jeff Regan)
+20c2b53a - Merge pull request #1542 from monopole/tweakFilePathsInTest (Jeff Regan)
+274b5c3b - Tweak file path handling and logging in test. (Jeffrey Regan)
+b1fdaa23 - Fix typo in transformerconfigs README (Ratnadeep Debnath)
+b5d5e70b - empty list or map item return error (nimohunter)
+2e829853 - empty list or map item return error (nimohunter)
+55941f57 - add note about GO111MODULE for source install (Jay Pipes)
+9e226001 - empty list or map item return error (nimohunter)
+77b63f96 - add release note for v3.2.0 (jingfangliu)
+```

docs/versioningPolicy.md

@@ -0,0 +1,278 @@
+# Versioning
+
+Running `kustomize` means one is running a
+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.
+
+## CLI Program Versioning
+
+The command `kustomize version` prints a three
+field version tag (e.g. `v3.0.0`) that aspires to
+[semantic versioning].
+
+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
+
+
+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 kustomize Go API, and
+  defining a migration path in a non-fatal error
+  message.
+- Removal means triggering a _major_ (semver)
+  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
+
+This `kustomize` command reads a Kustomization
+file, converts deprecated fields to new
+fields, and writes it out again in the latest
+format.
+
+This is a type version upgrade mechanism that
+works within _major_ API revisions.  There is no
+downgrade capability, as there's no use case for
+it (see discussion below).
+
+### Examples
+
+With the 2.0.0 release, there were three field
+removals:
+
+- `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`
+   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.
+
+The `edit fix` command in a v2.0.x binary
+will no longer recognize these fields.
+
+## Relationship to the k8s API
+
+### Review of k8s API versioning
+
+The k8s API has specific [conventions] and a
+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),
+- 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
+bearing the newest possible value for its version,
+the server will accept it and store it in
+"versionless" JSON form in storage, and can
+convert it to a range of older versions should
+an older client request data.
+
+For native k8s types, this all requires writing Go
+code in the kubernetes core repo, to provide
+defaulting and conversions.
+
+For CRDs, there's a [proposal] on how to manage
+versioning (e.g. a remote service can offer type
+defaulting and conversions).
+
+### Differences
+
+- 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]
+object, and the kustomize command and associated
+library is neither a server of, nor a client to,
+the k8s API.
+
+### Additional Kustomization file rules
+
+In addition to the [field change policy] described
+above, kustomization files conform to
+the following rules.
+
+#### Eschew classic k8s fields
+
+Field names with dedicated meaning in k8s
+(`metadata`, `spec`, `status`, etc.)  aren't used.
+This is enforced via code review.
+
+#### Default values for k8s `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.
+If present, the value of `kind` must be:
+
+> ```
+> kind: Kustomization
+> ```
+
+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
+[proposal]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/customresources-versioning.md
+[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/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 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/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

@@ -1,18 +1,19 @@
-[OTS]: glossary.md#off-the-shelf
+[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
+[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]: 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
 
@@ -21,14 +22,17 @@ use and maintain a configuration.
 
 ## Bespoke configuration
 
-In this workflow, all configuration files are owned by
-the user.  No content is incorporated from version
+In this workflow, all configuration (resource YAML) files
+are owned by the user.  No content is incorporated from version
 control repositories owned by others.
 
 ![bespoke config workflow image][workflowBespoke]
 
 #### 1) create a directory in version control
 
+Speculate some overall cluster application called _ldap_;
+we want to keep its configuration in its own repo.
+
 > ```
 > git init ~/ldap
 > ```
@@ -68,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
 
@@ -117,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,40 +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 github.com/kubernetes-sigs/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
+  * [mySql](mySql/README.md) - Create a MySQL production
+   configuration from scratch.
 
- * [breakfast](breakfast.md) - Customize breakfast for
-   Alice and Bob.
-   
- * [container args](wordpress/README.md) - Injecting k8s runtime data into container arguments (e.g. to point wordpress to a SQL service).
- 
- * [image tags](imageTags.md) - Updating image 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.
+  * [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,16 +64,16 @@ 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
-patches:
+patchesStrategicMerge:
 - temperature.yaml
 EOF
 
@@ -87,16 +87,16 @@ 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
-patches:
+patchesStrategicMerge:
 - topping.yaml
 EOF
 
@@ -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

@@ -92,9 +92,9 @@ secret holding them (not covering that here).
 <!--
 secretGenerator:
 - name: app-tls
-  commands:
-    tls.crt: "cat tls.cert"
-    tls.key: "cat tls.key"
+  files:
+    tls.crt=tls.cert
+    tls.key=tls.key
   type: "kubernetes.io/tls"
 EOF
 -->
@@ -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,9 +191,10 @@ dbpassword=mothersMaidenName
 EOF
 
 cat <<EOF >$OVERLAYS/development/kustomization.yaml
-bases:
+resources:
 - ../../base
 namePrefix: dev-
+nameSuffix: -v1
 configMapGenerator:
 - name: my-configmap
   behavior: merge
@@ -205,7 +206,7 @@ EOF
 
 One can now generate the configMaps for development:
 
-<!-- @runDev @test -->
+<!-- @runDev @testAgainstLatestRelease -->
 ```
 kustomize build $OVERLAYS/development
 ```
@@ -215,11 +216,12 @@ kustomize build $OVERLAYS/development
 The name of the generated `ConfigMap` is visible in this
 output.
 
-The name should be something like `dev-my-configmap-b5m75ck895`:
+The name should be something like `dev-my-configmap-v1-2gccmccgd5`:
 
  * `"dev-"` comes from the `namePrefix` field,
  * `"my-configmap"` comes from the `configMapGenerator/name` field,
- * `"-b5m75ck895"` comes from a deterministic hash that `kustomize`
+ * `"-v1"` comes from the `nameSuffix` field,
+ * `"-2gccmccgd5"` comes from a deterministic hash that `kustomize`
     computes from the contents of the configMap.
 
 The hash suffix is critical.  If the configMap content
@@ -258,7 +260,7 @@ deletes unused configMaps.
 Next, create the files for the _production_ overlay:
 
 
-<!-- @productionFiles @test -->
+<!-- @productionFiles @testAgainstLatestRelease -->
 ```
 mkdir -p $OVERLAYS/production
 
@@ -271,7 +273,7 @@ dbpassword=thisShouldProbablyBeInASecretInstead
 EOF
 
 cat <<EOF >$OVERLAYS/production/kustomization.yaml
-bases:
+resources:
 - ../../base
 namePrefix: prod-
 configMapGenerator:
@@ -285,13 +287,13 @@ EOF
 
 One can now generate the configMaps for production:
 
-<!-- @runProd @test -->
+<!-- @runProd @testAgainstLatestRelease -->
 ```
 kustomize build $OVERLAYS/production
 ```
 
 A CICD process could apply this directly to
-the cluser using:
+the cluster using:
 
 > ```
 > kustomize build $OVERLAYS/production | kubectl apply -f -

examples/configGeneration.md

@@ -1,6 +1,6 @@
-[patch]: ../../docs/glossary.md#patch
-[resource]: ../../docs/glossary.md#resource
-[variant]: ../../docs/glossary.md#variant
+[patch]: ../docs/glossary.md#patch
+[resource]: ../docs/glossary.md#resource
+[variant]: ../docs/glossary.md#variant
 
 ## ConfigMap generation and rolling updates
 
@@ -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,21 +53,22 @@ EOF
 ```
 
 Establish the staging with a patch applied to the ConfigMap
-<!-- @establishStaging @test -->
+<!-- @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!
-bases:
+resources:
 - ../../base
-patches:
+patchesStrategicMerge:
 - map.yaml
 EOF
 
@@ -90,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
 ```
@@ -109,14 +110,14 @@ configuration is to
 
 This latter change initiates rolling update to the pods
 in the deployment.  The older configMap, when no longer
-referenced by any other resource, is eventually garbage
-collected.
+referenced by any other resource, is eventually [garbage
+collected](https://github.com/kubernetes-sigs/kustomize/issues/242).
 
 ### How this works with kustomize
 
 The _staging_ [variant] here has a configMap [patch]:
 
-<!-- @showMapPatch @test -->
+<!-- @showMapPatch @testAgainstLatestRelease -->
 ```
 cat $OVERLAYS/staging/map.yaml
 ```
@@ -127,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
 ```
@@ -140,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
@@ -150,21 +151,25 @@ The configMap name is prefixed by _staging-_, per the
 `namePrefix` field in
 `$OVERLAYS/staging/kustomization.yaml`.
 
+The configMap name is suffixed by _-v1_, per the
+`nameSuffix` field in
+`$OVERLAYS/staging/kustomization.yaml`.
+
 The suffix to the configMap name is generated from a
 hash of the maps content - in this case the name suffix
-is _hhhhkfmgmk_:
+is _k25m8k5k5m_:
 
-<!-- @grepStagingHash @test -->
+<!-- @grepStagingHash @testAgainstLatestRelease -->
 ```
-kustomize build $OVERLAYS/staging | grep hhhhkfmgmk
+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 's/pineapple/kiwi/' $OVERLAYS/staging/map.yaml
+sed -i.bak 's/pineapple/kiwi/' $OVERLAYS/staging/map.yaml
 ```
 
 See the new greeting:
@@ -176,27 +181,27 @@ 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
 ```
 
 Confirm that the change in configMap content resulted
-in three new names ending in _khk45ktkd9_ - one in the
+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 khk45ktkd9 | wc -l); \
+  $(kustomize build $OVERLAYS/staging | grep cd7kdh48fd | wc -l); \
   echo $?
 ```
 
 Applying these resources to the cluster will result in
 a rolling update of the deployments pods, retargetting
-them from the _hhhhkfmgmk_ maps to the _khk45ktkd9_
+them from the _k25m8k5k5m_ maps to the _cd7kdh48fd_
 maps.  The system will later garbage collect the
 unused maps.
 

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

@@ -0,0 +1,60 @@
+# Generator Options
+
+Kustomize provides options to modify the behavior of ConfigMap and Secret generators. These options include
+ 
+ - disable appending a content hash suffix to the names of generated resources
+ - adding labels to generated resources
+ - adding annotations to generated resources
+ 
+This demo shows how to use these options. First create a workspace.
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+Create a kustomization and add a ConfigMap generator to it.
+
+<!-- @createCMGenerator @testAgainstLatestRelease -->
+```
+cat > $DEMO_HOME/kustomization.yaml << EOF
+configMapGenerator:
+- name: my-configmap
+  literals:	
+  - foo=bar
+  - baz=qux
+EOF
+```
+
+Add following generatorOptions
+<!-- @addGeneratorOptions @testAgainstLatestRelease -->
+```
+cat >> $DEMO_HOME/kustomization.yaml << EOF
+generatorOptions:
+ disableNameSuffixHash: true
+ labels:
+   kustomize.generated.resource: somevalue
+ annotations:
+   annotations.only.for.generated: othervalue
+EOF
+```
+Run `kustomize build` and make sure that the generated ConfigMap
+ 
+ - doesn't have name suffix
+    <!-- @verify @testAgainstLatestRelease -->
+    ```
+    test 1 == \
+    $(kustomize build $DEMO_HOME | grep "name: my-configmap$" | wc -l); \
+    echo $?
+    ```
+ - has label `kustomize.generated.resource: somevalue`
+     ```
+     test 1 == \
+     $(kustomize build $DEMO_HOME | grep -A 1 "labels" | grep "kustomize.generated.resource" | wc -l); \
+     echo $?
+     ```
+ - has 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/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,20 +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 's/app: hello/app: my-hello/' \
+sed -i.bak 's/app: hello/app: my-hello/' \
     $BASE/kustomization.yaml
 ```
 
-On a Mac, use:
-```
-sed -i '' $pattern $file
-```
-to get in-place editing.
-
 See the effect:
-<!-- @checkLabel @test -->
+<!-- @checkLabel @testAgainstLatestRelease -->
 ```
 kustomize build $BASE | grep -C 3 app:
 ```
@@ -133,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
@@ -145,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-
@@ -154,9 +148,9 @@ commonLabels:
   org: acmeCorporation
 commonAnnotations:
   note: Hello, I am staging!
-bases:
+resources:
 - ../../base
-patches:
+patchesStrategicMerge:
 - map.yaml
 EOF
 ```
@@ -168,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
@@ -186,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-
@@ -195,9 +189,9 @@ commonLabels:
   org: acmeCorporation
 commonAnnotations:
   note: Hello, I am production!
-bases:
+resources:
 - ../../base
-patches:
+patchesStrategicMerge:
 - deployment.yaml
 EOF
 ```
@@ -208,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
@@ -234,7 +228,7 @@ EOF
 
 Review the directory structure and differences:
 
-<!-- @listFiles @test -->
+<!-- @listFiles @testAgainstLatestRelease -->
 ```
 tree $DEMO_HOME
 ```
@@ -294,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

@@ -0,0 +1,76 @@
+# Demo: change image names and tags
+
+
+Define a place to work:
+
+<!-- @makeWorkplace @testAgainstLatestRelease -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+Make a `kustomization` containing a pod resource
+
+<!-- @createKustomization @testAgainstLatestRelease -->
+```
+cat <<EOF >$DEMO_HOME/kustomization.yaml
+resources:
+- pod.yaml
+EOF
+```
+
+Declare the pod resource
+
+<!-- @createDeployment @testAgainstLatestRelease -->
+```
+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
+```
+
+The `myapp-pod` resource declares an initContainer and a container, both use the image `busybox:1.29.0`.
+The image `busybox` and tag `1.29.0` can be changed by adding `images` in `kustomization.yaml`.
+
+
+Add `images`:
+<!-- @addImages @testAgainstLatestRelease -->
+```
+cd $DEMO_HOME
+kustomize edit set image busybox=alpine:3.6
+```
+
+The following `images` will be added to `kustomization.yaml`:
+> ```
+> images:
+> - name: busybox
+>   newName: alpine
+>   newTag: 3.6
+> ```
+
+Now build this `kustomization`
+<!-- @kustomizeBuild @testAgainstLatestRelease -->
+```
+kustomize build $DEMO_HOME
+```
+
+Confirm that this replaces _both_ busybox images and tags for `alpine:3.6`:
+
+<!-- @confirmImages @testAgainstLatestRelease -->
+```
+test 2 = \
+  $(kustomize build $DEMO_HOME | grep alpine:3.6 | wc -l); \
+  echo $?
+```

examples/imageTags.md

@@ -1,75 +0,0 @@
-# Demo: change image tags
-
-
-Define a place to work:
-
-<!-- @makeWorkplace @test -->
-```
-DEMO_HOME=$(mktemp -d)
-```
-
-Make a `kustomization` containing a pod resource
-
-<!-- @createKustomization @test -->
-```
-cat <<EOF >$DEMO_HOME/kustomization.yaml
-resources:
-- pod.yaml
-EOF
-```
-
-Declare the pod resource
-
-<!-- @createDeployment @test -->
-```
-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
-```
-
-The `myapp-pod` resource declares an initContainer and a container, both use the image `busybox:1.29.0`.
-The tag `1.29.0` can be changed by adding `imageTags` in `kustomization.yaml`.
-
-
-Add `imageTags`:
-<!-- @addImageTags @test -->
-```
-cd $DEMO_HOME
-kustomize edit set imagetag busybox:1.29.1
-```
-
-The `kustomization.yaml` will be added following `imageTags`.
-> ```
-> imageTags:
-> - name: busybox
->   newTag: 1.29.1
-> ```
-
-Now build this `kustomization`
-<!-- @kustomizeBuild @test -->
-```
-kustomize build $DEMO_HOME
-```
-
-Confirm that this replaces _both_ busybox tags:
-
-<!-- @confirmTags @test -->
-```
-test 2 == \
-  $(kustomize build $DEMO_HOME | grep busybox:1.29.1 | wc -l); \
-  echo $?
-```

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
@@ -48,12 +48,12 @@ function setUpEnv {
   [[ $? -eq 0 ]] || "Failed to cd to $repo"
   echo "pwd is " `pwd`
 
-  local expectedRepo=kubernetes-sigs/kustomize
+  local expectedRepo=sigs.k8s.io/kustomize
   if [[ `pwd` != */$expectedRepo ]]; then
     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

@@ -0,0 +1,118 @@
+# Demo: applying a json patch
+
+A kustomization file supports customizing resources via [JSON patches](https://tools.ietf.org/html/rfc6902).
+
+The example below modifies an `Ingress` object with such a patch.
+
+Make a `kustomization` containing an ingress resource.
+
+<!-- @createIngress @testAgainstLatestRelease -->
+```
+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
+```
+
+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 @testAgainstLatestRelease -->
+```
+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
+```
+
+You can also write the patch in YAML format. This example also shows the "add" operation:
+
+<!-- @addYamlPatch @testAgainstLatestRelease -->
+```
+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
+```
+
+Apply the patch by adding _patchesJson6902_ field in kustomization.yaml
+
+<!-- @applyJsonPatch @testAgainstLatestRelease -->
+```
+cat <<EOF >>$DEMO_HOME/kustomization.yaml
+patchesJson6902:
+- target:
+    group: networking.k8s.io
+    version: v1beta1
+    kind: Ingress
+    name: my-ingress
+  path: ingress_patch.json
+EOF
+```
+
+Running `kustomize build $DEMO_HOME`, in the output confirm that host has been updated correctly.
+<!-- @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 @testAgainstLatestRelease -->
+```
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep "servicePort: 8080" | wc -l); \
+  echo $?
+```
+
+If the patch is YAML-formatted, it will be parsed correctly:
+
+<!-- @applyYamlPatch @testAgainstLatestRelease -->
+```
+cat <<EOF >>$DEMO_HOME/kustomization.yaml
+patchesJson6902:
+- target:
+    group: networking.k8s.io
+    version: v1beta1
+    kind: Ingress
+    name: my-ingress
+  path: ingress_patch.yaml
+EOF
+```
+
+<!-- @confirmYamlPatch @testAgainstLatestRelease -->
+```
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep "path: /test" | wc -l); \
+  echo $?
+```

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,5 +1,5 @@
-bases:
+resources:
   - ../../base
-patches:
+patchesStrategicMerge:
   - deployment.yaml
 namePrefix: production-

examples/ldap/overlays/staging/kustomization.yaml

@@ -1,9 +1,9 @@
-bases:
-  - ../../base
-patches:
-  - deployment.yaml
-nameprefix: staging-
+resources:
+- ../../base
+patchesStrategicMerge:
+ - 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
@@ -107,9 +117,9 @@ Now the workspace has following directories
 >     └── kustomization.yaml
 > ```
 
-Confirm that the `kustomize build` output contains three pod objects from dev, staing and production variants.
+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,9 +134,9 @@ 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 's/app: helloworld/app: prod/' \
+sed -i.bak 's/app: helloworld/app: prod/' \
     $DEMO_HOME/kustomization.yaml
 ```
 
@@ -150,10 +150,10 @@ Off the shelf MySQL uses `emptyDir` type volume, which
 gets wiped away if the MySQL Pod is recreated, and that
 is certainly not desirable for production
 environment. So we want to use Persistent Disk in
-production. kustomize lets you apply `patches` to the
+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,14 +173,16 @@ EOF
 
 Add the patch file to `kustomization.yaml`:
 
-<!-- @specifyPatch @test -->
+<!-- @specifyPatch @testAgainstLatestRelease -->
 ```
 cat <<'EOF' >> $DEMO_HOME/kustomization.yaml
-patches:
+patchesStrategicMerge:
 - persistent-disk.yaml
 EOF
 ```
 
+A `mysql-persistent-storage` persistent disk needs to exist for it to run successfully.
+
 Lets break this down:
 
 - In the first step, we created a YAML file named
@@ -188,7 +190,7 @@ Lets break this down:
   in deployment.yaml
 
 - Then we added `persistent-disk.yaml` to list of
-  `patches` in `kustomization.yaml`. `kustomize build`
+  `patchesStrategicMerge` in `kustomization.yaml`. `kustomize build`
   will apply this patch to the deployment resource with
   the name `mysql` as defined in the patch.
 
@@ -197,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/mySql/secret.yaml

@@ -2,7 +2,7 @@ apiVersion: v1
 kind: Secret
 metadata:
   creationTimestamp: null
-  name: mysql-pass-d2gtcm2t2k
+  name: mysql-pass
 type: Opaque
 data:
   # Default password is "admin".

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

@@ -0,0 +1,78 @@
+# remote targets
+
+`kustomize build` can be run on a URL.
+
+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 -->
+
+```
+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 $?
+```
+
+A base can be a URL:
+
+<!-- @createOverlay @testAgainstLatestRelease -->
+```
+DEMO_HOME=$(mktemp -d)
+
+cat <<EOF >$DEMO_HOME/kustomization.yaml
+resources:
+- github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6
+namePrefix: remote-
+EOF
+```
+
+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); \
+  echo $?
+```
+
+## 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.
+
+- a repo with a root level kustomization.yaml
+
+  `github.com/Liujingfang1/mysql`
+- a repo with a root level kustomization.yaml on branch test
+
+  `github.com/Liujingfang1/mysql?ref=test`
+- a subdirectory in a repo on version v1.0.6
+
+  `github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6`
+- a subdirectory in a repo on branch repoUrl2
+
+  `github.com/Liujingfang1/kustomize//examples/helloWorld?ref=repoUrl2`
+- a subdirectory in a repo on commit `7050a45134e9848fca214ad7e7007e96e5042c03`
+
+  `github.com/Liujingfang1/kustomize//examples/helloWorld?ref=7050a45134e9848fca214ad7e7007e96e5042c03`

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
@@ -291,7 +291,7 @@ kustomize edit add patch healthcheck_patch.yaml
 `kustomization.yaml` should have patches field:
 
 > ```
-> patches:
+> patchesStrategicMerge:
 > - patch.yaml
 > - memorylimit_patch.yaml
 > - healthcheck_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,6 +1,6 @@
-bases:
+resources:
 - ../../base
-patches:
+patchesStrategicMerge:
 - patch.yaml
 - healthcheck_patch.yaml
 - memorylimit_patch.yaml

examples/springboot/overlays/staging/kustomization.yaml

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

examples/transformerconfigs/README.md

@@ -0,0 +1,178 @@
+# Transformer Configurations
+
+Kustomize creates new resources by applying a series of transformations to an original
+set of resources. Kustomize provides the following default transformers:
+
+- annotations
+- images
+- labels
+- name reference
+- namespace
+- prefix/suffix
+- variable reference
+
+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`, 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
+```
+
+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
+
+- path: spec/selector
+  create: true
+  version: v1
+  kind: Service
+
+- path: spec/selector/matchLabels
+  create: true
+  kind: Deployment
+```
+
+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:
+- kind: Pod
+  version: v1
+  path: spec/volumes/configMap/name
+- kind: Deployment
+  path: spec/template/spec/volumes/configMap/name
+- kind: Job
+  path: spec/template/spec/volumes/configMap/name
+```
+
+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
+  fieldSpecs:
+  - path: spec/volumes/configMap/name
+    version: v1
+    kind: Pod
+  - path: spec/containers/env/valueFrom/configMapKeyRef/name
+    version: v1
+    kind: Pod
+  # ...
+- kind: Secret
+  version: v1
+  fieldSpecs:
+  - path: spec/volumes/secret/secretName
+    version: v1
+    kind: Pod
+  - path: spec/containers/env/valueFrom/secretKeyRef/name
+    version: v1
+    kind: Pod
+```
+
+## 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:
+
+- [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

@@ -0,0 +1,139 @@
+## Supporting Custom Resources (defined by a CRD)
+
+This tutorial shows how to add transformer configurations to support a custom resource.
+
+Create a workspace by
+<!-- @createws @testAgainstLatestRelease -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+### Adding a custom resource
+
+Consider a CRD of kind `MyKind` with fields
+- `.spec.secretRef.name` reference a Secret
+- `.spec.beeRef.name` reference an instance of CRD `Bee`
+- `.spec.containers.command` as the list of container commands
+- `.spec.selectors` as the label selectors
+
+Add the following file to configure the transformers for the above fields
+<!-- @addConfig @testAgainstLatestRelease -->
+```
+mkdir $DEMO_HOME/kustomizeconfig
+cat > $DEMO_HOME/kustomizeconfig/mykind.yaml << EOF
+
+commonLabels:
+- path: spec/selectors
+  create: true
+  kind: MyKind
+
+nameReference:
+- kind: Bee
+  fieldSpecs:
+  - path: spec/beeRef/name
+    kind: MyKind
+- kind: Secret
+  fieldSpecs:
+  - path: spec/secretRef/name
+    kind: MyKind
+
+varReference:
+- path: spec/containers/command
+  kind: MyKind
+- path: spec/beeRef/action
+  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: v1
+kind: Secret
+metadata:
+  name: crdsecret
+data:
+  PATH: YmJiYmJiYmIK
+---
+apiVersion: v1beta1
+kind: Bee
+metadata:
+  name: bee
+spec:
+  action: fly
+---
+apiVersion: jingfang.example.com/v1beta1
+kind: MyKind
+metadata:
+  name: mykind
+spec:
+  secretRef:
+    name: crdsecret
+  beeRef:
+    name: bee
+    action: \$(BEE_ACTION)
+  containers:
+  - command:
+    - "echo"
+    - "\$(BEE_ACTION)"
+    image: myapp
+EOF
+```
+
+Create a kustomization referring to it:
+
+<!-- @createKustomization @testAgainstLatestRelease -->
+```
+cat > $DEMO_HOME/kustomization.yaml << EOF
+resources:
+- resources.yaml
+
+namePrefix: test-
+
+commonLabels:
+  foo: bar
+
+vars:
+- name: BEE_ACTION
+  objref:
+    kind: Bee
+    name: bee
+    apiVersion: v1beta1
+  fieldref:
+    fieldpath: spec.action
+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 namereference is correctly resolved.
+
+<!-- @build @testAgainstLatestRelease -->
+```
+test 2 == \
+$(kustomize build $DEMO_HOME | grep -A 2 ".*Ref" | grep "test-" | wc -l); \
+echo $?    
+```
+
+Run `kustomize build` and verify that the vars correctly resolved.
+
+<!-- @verify @testAgainstLatestRelease -->
+```
+test 0 == \
+$(kustomize build $DEMO_HOME | grep "BEE_ACTION" | wc -l); \
+echo $?    
+```

examples/transformerconfigs/crd/kustomization.yaml

@@ -0,0 +1,16 @@
+resources:
+- resources.yaml
+
+namePrefix: test-
+
+commonLabels:
+  foo: bar
+
+vars:
+- name: BEE_ACTION
+  objref:
+    kind: Bee
+    name: bee
+    apiVersion: v1beta1
+  fieldref:
+    fieldpath: spec.action

examples/transformerconfigs/crd/resources.yaml

@@ -0,0 +1,29 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: crdsecret
+data:
+  PATH: YmJiYmJiYmIK
+---
+apiVersion: v1beta1
+kind: Bee
+metadata:
+  name: bee
+spec:
+  action: fly
+---
+apiVersion: jingfang.example.com/v1beta1
+kind: MyKind
+metadata:
+  name: mykind
+spec:
+  secretRef:
+    name: crdsecret
+  beeRef:
+    name: bee
+    action: $(BEE_ACTION)
+  containers:
+  - command:
+    - "echo"
+    - "$(BEE_ACTION)"
+    image: myapp

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