Merge pull request #1344 from Liujingfang1/fix

include nameprefix and namesuffix to find matched reference for cluster level kinds

.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,43 @@
+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
+  - source ./travis/consider-early-travis-exit.sh
+  - curl -sfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh| sh -s -- -b $(go env GOPATH)/bin v1.17.1
   - 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
+  # The following would install Helm if needed for some reason.
+  # - wget https://storage.googleapis.com/kubernetes-helm/helm-v2.13.1-linux-amd64.tar.gz
+  # - tar -xvzf helm-v2.13.1-linux-amd64.tar.gz
+  # - sudo mv linux-amd64/helm /usr/local/bin/helm
 
-# 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,301 +0,0 @@
-# This file is autogenerated, do not edit; changes may be undone by the next 'dep ensure'.
-
-
-[[projects]]
-  name = "github.com/PuerkitoBio/purell"
-  packages = ["."]
-  revision = "0bcb03f4b4d0a9428594752bd2a3b9aa0a9d4bd4"
-  version = "v1.1.0"
-
-[[projects]]
-  branch = "master"
-  name = "github.com/PuerkitoBio/urlesc"
-  packages = ["."]
-  revision = "de5bf2ad457846296e2031421a34e2568e304e35"
-
-[[projects]]
-  name = "github.com/davecgh/go-spew"
-  packages = ["spew"]
-  revision = "346938d642f2ec3594ed81d874461961cd0faa76"
-  version = "v1.1.0"
-
-[[projects]]
-  name = "github.com/emicklei/go-restful"
-  packages = [
-    ".",
-    "log"
-  ]
-  revision = "3658237ded108b4134956c1b3050349d93e7b895"
-  version = "v2.7.1"
-
-[[projects]]
-  name = "github.com/evanphx/json-patch"
-  packages = ["."]
-  revision = "afac545df32f2287a079e2dfb7ba2745a643747e"
-  version = "v3.0.0"
-
-[[projects]]
-  name = "github.com/ghodss/yaml"
-  packages = ["."]
-  revision = "0ca9ea5df5451ffdf184b4428c902747c2c11cd7"
-  version = "v1.0.0"
-
-[[projects]]
-  branch = "master"
-  name = "github.com/go-openapi/jsonpointer"
-  packages = ["."]
-  revision = "3a0015ad55fa9873f41605d3e8f28cd279c32ab2"
-
-[[projects]]
-  branch = "master"
-  name = "github.com/go-openapi/jsonreference"
-  packages = ["."]
-  revision = "3fb327e6747da3043567ee86abd02bb6376b6be2"
-
-[[projects]]
-  branch = "master"
-  name = "github.com/go-openapi/spec"
-  packages = ["."]
-  revision = "bcff419492eeeb01f76e77d2ebc714dc97b607f5"
-
-[[projects]]
-  branch = "master"
-  name = "github.com/go-openapi/swag"
-  packages = ["."]
-  revision = "811b1089cde9dad18d4d0c2d09fbdbf28dbd27a5"
-
-[[projects]]
-  name = "github.com/gogo/protobuf"
-  packages = [
-    "proto",
-    "sortkeys"
-  ]
-  revision = "1adfc126b41513cc696b209667c8656ea7aac67c"
-  version = "v1.0.0"
-
-[[projects]]
-  branch = "master"
-  name = "github.com/golang/glog"
-  packages = ["."]
-  revision = "23def4e6c14b4da8ac2ed8007337bc5eb5007998"
-
-[[projects]]
-  name = "github.com/golang/protobuf"
-  packages = [
-    "proto",
-    "ptypes",
-    "ptypes/any",
-    "ptypes/duration",
-    "ptypes/timestamp"
-  ]
-  revision = "b4deda0973fb4c70b50d226b1af49f3da59f5265"
-  version = "v1.1.0"
-
-[[projects]]
-  branch = "master"
-  name = "github.com/google/gofuzz"
-  packages = ["."]
-  revision = "24818f796faf91cd76ec7bddd72458fbced7a6c1"
-
-[[projects]]
-  name = "github.com/googleapis/gnostic"
-  packages = [
-    "OpenAPIv2",
-    "compiler",
-    "extensions"
-  ]
-  revision = "ee43cbb60db7bd22502942cccbc39059117352ab"
-  version = "v0.1.0"
-
-[[projects]]
-  name = "github.com/inconshreveable/mousetrap"
-  packages = ["."]
-  revision = "76626ae9c91c4f2a10f34cad8ce83ea42c93bb75"
-  version = "v1.0"
-
-[[projects]]
-  name = "github.com/json-iterator/go"
-  packages = ["."]
-  revision = "ca39e5af3ece67bbcda3d0f4f56a8e24d9f2dad4"
-  version = "1.1.3"
-
-[[projects]]
-  branch = "master"
-  name = "github.com/mailru/easyjson"
-  packages = [
-    "buffer",
-    "jlexer",
-    "jwriter"
-  ]
-  revision = "3fdea8d05856a0c8df22ed4bc71b3219245e4485"
-
-[[projects]]
-  name = "github.com/modern-go/concurrent"
-  packages = ["."]
-  revision = "bacd9c7ef1dd9b15be4a9909b8ac7a4e313eec94"
-  version = "1.0.3"
-
-[[projects]]
-  name = "github.com/modern-go/reflect2"
-  packages = ["."]
-  revision = "1df9eeb2bb81f327b96228865c5687bc2194af3f"
-  version = "1.0.0"
-
-[[projects]]
-  name = "github.com/pkg/errors"
-  packages = ["."]
-  revision = "645ef00459ed84a119197bfb8d8205042c6df63d"
-  version = "v0.8.0"
-
-[[projects]]
-  name = "github.com/spf13/cobra"
-  packages = ["."]
-  revision = "a1f051bc3eba734da4772d60e2d677f47cf93ef4"
-  version = "v0.0.2"
-
-[[projects]]
-  name = "github.com/spf13/pflag"
-  packages = ["."]
-  revision = "583c0c0531f06d5278b7d917446061adc344b5cd"
-  version = "v1.0.1"
-
-[[projects]]
-  branch = "master"
-  name = "golang.org/x/net"
-  packages = [
-    "http/httpguts",
-    "http2",
-    "http2/hpack",
-    "idna"
-  ]
-  revision = "2491c5de3490fced2f6cff376127c667efeed857"
-
-[[projects]]
-  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"
-  ]
-  revision = "f21a4dfb5e38f5895301dc265a8def02365cc3d0"
-  version = "v0.3.0"
-
-[[projects]]
-  name = "gopkg.in/inf.v0"
-  packages = ["."]
-  revision = "d2d2541c53f18d2a059457998ce2876cc8e67cbf"
-  version = "v0.9.1"
-
-[[projects]]
-  name = "gopkg.in/yaml.v2"
-  packages = ["."]
-  revision = "5420a8b6744d3b0345ab293f6fcba19c978f1183"
-  version = "v2.2.1"
-
-[[projects]]
-  branch = "master"
-  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"
-  ]
-  revision = "53d615ae3f440f957cb9989d989d597f047262d9"
-
-[[projects]]
-  branch = "master"
-  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"
-  ]
-  revision = "13b73596e4b63e03203e86f6d9c7bcc1b937c62f"
-
-[[projects]]
-  name = "k8s.io/client-go"
-  packages = ["kubernetes/scheme"]
-  revision = "23781f4d6632d88e869066eaebb743857aa1ef9b"
-  version = "v7.0.0"
-
-[[projects]]
-  branch = "master"
-  name = "k8s.io/kube-openapi"
-  packages = [
-    "pkg/common",
-    "pkg/util/proto"
-  ]
-  revision = "b3f03f55328800731ce03a164b80973014ecd455"
-
-[solve-meta]
-  analyzer-name = "dep"
-  analyzer-version = 1
-  inputs-digest = "586d4cb9094e9b5c0731f16e931b953e9c0f709b7125a7537ae3625ada179eee"
-  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
-```

OWNERS_ALIASES

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

README.md

@@ -1,5 +1,7 @@
 # kustomize
 
+_[v3.0.0](https://github.com/kubernetes-sigs/kustomize/releases/tag/v3.0.0) is the latest release._
+
 `kustomize` lets you customize raw, template-free YAML
 files for multiple purposes, leaving the original YAML
 untouched and usable as is.
@@ -7,14 +9,23 @@ 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).
+
+kustomize [v2.0.3] is available in [kubectl v1.15][kubectl].
+
 
 ## Usage
 
@@ -113,21 +124,44 @@ 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]: https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement
 [kubernetes style]: docs/glossary.md#kubernetes-style-object
 [kustomization]: docs/glossary.md#kustomization
 [overlay]: docs/glossary.md#overlay
@@ -138,4 +172,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,88 +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 \
-  --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
-[`container-builder-local`]: https://github.com/GoogleCloudPlatform/container-builder-local
-[Google Container Builder]: https://cloud.google.com/container-builder
-
-Scripts and configuration files for publishing a
-`kustomize` release on the [releases page].
-
-### Build a release locally
-
-Install [`container-builder-local`], then run
-
-```
-container-builder-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 Container
-Builder] 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.yml --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/version.kustomizeVersion={{.Version}} -X github.com/kubernetes-sigs/kustomize/version.gitCommit={{.Commit}} -X github.com/kubernetes-sigs/kustomize/version.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

build/goreleaser.yml

@@ -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/version.kustomizeVersion={{.Version}} -X github.com/kubernetes-sigs/kustomize/version.gitCommit={{.Commit}} -X github.com/kubernetes-sigs/kustomize/version.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

cmd/kustomize/main.go

@@ -0,0 +1,17 @@
+// Copyright 2019 The Kubernetes Authors.
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"os"
+
+	"sigs.k8s.io/kustomize/v3/pkg/commands"
+)
+
+func main() {
+	if err := commands.NewDefaultCommand().Execute(); err != nil {
+		os.Exit(1)
+	}
+	os.Exit(0)
+}

cmd/pluginator/main.go

@@ -0,0 +1,132 @@
+// Copyright 2019 The Kubernetes Authors.
+// SPDX-License-Identifier: Apache-2.0
+
+// See /plugin/doc.go for an explanation.
+package main
+
+import (
+	"bufio"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"sigs.k8s.io/kustomize/v3/pkg/pgmconfig"
+	"sigs.k8s.io/kustomize/v3/pkg/plugins"
+)
+
+func main() {
+	root := inputFileRoot()
+	file, err := os.Open(root + ".go")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer file.Close()
+	scanner := bufio.NewScanner(file)
+	readToPackageMain(scanner, file.Name())
+
+	w := NewWriter(root)
+	defer w.close()
+
+	// This particular phrasing is required.
+	w.write(
+		fmt.Sprintf(
+			"// Code generated by pluginator on %s; DO NOT EDIT.",
+			root))
+	w.write("package builtin")
+
+	for scanner.Scan() {
+		l := scanner.Text()
+		if strings.HasPrefix(l, "//go:generate") {
+			continue
+		}
+		if l == "var "+plugins.PluginSymbol+" plugin" {
+			w.write("func New" + root + "Plugin() *" + root + "Plugin {")
+			w.write("  return &" + root + "Plugin{}")
+			w.write("}")
+			continue
+		}
+		w.write(l)
+	}
+	if err := scanner.Err(); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func inputFileRoot() string {
+	n := os.Getenv("GOFILE")
+	if !strings.HasSuffix(n, ".go") {
+		log.Fatalf("expecting .go suffix on %s", n)
+	}
+	return n[:len(n)-len(".go")]
+}
+
+func readToPackageMain(s *bufio.Scanner, f string) {
+	gotMain := false
+	for !gotMain && s.Scan() {
+		gotMain = strings.HasPrefix(s.Text(), "package main")
+	}
+	if !gotMain {
+		log.Fatalf("%s missing package main", f)
+	}
+}
+
+type writer struct {
+	root string
+	f    *os.File
+}
+
+func NewWriter(r string) *writer {
+	n := makeOutputFileName(r)
+	f, err := os.Create(n)
+	if err != nil {
+		log.Fatalf("unable to create `%s`; %v", n, err)
+	}
+	return &writer{root: r, f: f}
+}
+
+func makeOutputFileName(root string) string {
+	return filepath.Join(
+		os.Getenv("GOPATH"),
+		"src",
+		pgmconfig.DomainName,
+		pgmconfig.ProgramName,
+		pgmconfig.PluginRoot,
+		"builtin",
+		root+".go")
+}
+
+func (w *writer) close() {
+	fmt.Println("Generated " + w.root)
+	w.f.Close()
+}
+
+func (w *writer) write(line string) {
+	_, err := w.f.WriteString(w.filter(line) + "\n")
+	if err != nil {
+		log.Printf("Trouble writing: %s", line)
+		log.Fatal(err)
+	}
+}
+
+func (w *writer) filter(in string) string {
+	if ok, newer := w.replace(in, "type plugin struct"); ok {
+		return newer
+	}
+	if ok, newer := w.replace(in, "*plugin)"); ok {
+		return newer
+	}
+	return in
+}
+
+// replace 'plugin' with 'FooPlugin' in context
+// sensitive manner.
+func (w *writer) replace(in, target string) (bool, string) {
+	if !strings.Contains(in, target) {
+		return false, ""
+	}
+	newer := strings.Replace(
+		target, "plugin", w.root+"Plugin", 1)
+	return true, strings.Replace(in, target, newer, 1)
+}

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,30 @@
+# 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
+```

docs/INSTALL.md

@@ -0,0 +1,50 @@
+[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
+```
+
+## Install from the HEAD of master branch
+
+Requires [Go] v1.12 or higher:
+
+<!-- @installkustomize @test -->
+```
+go install sigs.k8s.io/kustomize/v3/cmd/kustomize
+```
+
+### 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,52 @@
+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
+
+ * [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/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

@@ -0,0 +1,130 @@
+# 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 may add labels, annotations, patches, resources, bases, etc.
+Corresponding _removal_ directives are not offered.
+
+Removal semantics would introduce many possibilities for
+inconsistency, and the need to add code to detect, report and
+reject it.  It would also allow, and possibly encourage,
+unnecessarily complex configuration layouts.
+
+When faced with a situation where removal is desirable, it's
+always possible to remove things from a base like labels and
+annotations, and/or split multi-resource manifests into individual
+resource files - then add things back as desired via the
+[kustomization].
+
+If the underlying base is outside of one's control, an [OTS
+workflow] is the recommended best practice.  Fork the base, remove
+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
+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 frustrate that goal.
+
+`kustomize` insteads offers [kustomization] file `edit`
+commands.  Like any shell command, they can accept
+environment variable arguments.
+
+For example, to set the tag used on an image to match an
+environment variable, run
+
+```
+kustomize edit set image nginx:$MY_NGINX_VERSION
+```
+
+as part of some encapsulating work flow executed before
+`kustomize build`.
+
+
+## Globs in kustomization files
+
+`kustomize` supports the best practice of storing one's
+entire configuration in a version control system.
+
+Globbing the local file system for files not explicitly
+declared in the [kustomization] file at `kustomize build` time
+would violate that goal.
+
+Allowing globbing in a kustomization file would also introduce
+the same problems as allowing globbing in [java import]
+declarations or BUILD/Makefile dependency rules.
+
+`kustomize` will instead provide kustomization file editting
+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.
+
+[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
+[SMP patches]: glossary.md#patchstrategicmerge

docs/execPluginIn30sec.md

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

docs/fields.md

@@ -0,0 +1,507 @@
+# Kustomization File Fields
+
+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. |
+|[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
+
+Adds labels to all resources and selectors
+```
+commonLabels:
+  someName: someValue
+  owner: alice
+  app: bingo
+```
+
+### commonAnnotations
+
+Adds annotions (non-identifying metadata) to add
+all resources. Like labels, these are key value
+pairs.
+
+```
+commonAnnotations:
+  oncallPager: 800-555-1212
+```
+
+### 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: myJavaServerProps
+  files:
+  - application.properties
+  - more.properties
+- name: myJavaServerEnvVars
+  literals:	
+  - JAVA_HOME=/opt/java/jdk
+  - JAVA_TOOL_OPTIONS=-agentlib:hprof
+```
+
+### 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
+
+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
+```
+
+### inventory
+
+See [inventory object](inventory_object.md).
+
+### kind
+
+If missing, this field's value defaults to
+
+```
+kind: Kustomization
+```
+
+
+### namespace
+
+Adds namespace to all resources
+
+```
+namespace: my-namespace
+```
+
+### namePrefix
+
+Prepends value to the names of all resources
+Ex. a deployment named `wordpress` would become `alices-wordpress`
+
+```
+namePrefix: alices-
+```
+
+### nameSuffix
+
+The value is appended to the names of all
+resources.  Ex. A deployment named `wordpress`
+would become `wordpress-v2`.
+
+The suffix is appended before content has if
+resource type is ConfigMap or Secret.
+
+```
+nameSuffix: -v2
+```
+
+### patchesStrategicMerge
+
+Each entry in this list should be a relative path
+resolving 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.  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
+```
+
+### 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
+```
+
+### 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.
+
+
+#### Limitation
+
+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.
+
+
+### 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
+
+Each entry in this list results in the creation of
+one Secret resource (it's a generator of n secrets).
+
+```
+secretGenerator:
+- name: app-tls
+  files:
+  - secret/tls.cert
+  - secret/tls.key
+  type: "kubernetes.io/tls"
+- name: app-tls-namespaced
+  # you can define a namespace to generate secret in, defaults to: "default"
+  namespace: apps
+  files:
+  - tls.crt=catsecret/tls.cert
+  - tls.key=secret/tls.key
+  type: "kubernetes.io/tls"
+- name: env_file_secret
+  envs:
+  - env.txt
+  type: Opaque
+```
+
+### 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,16 +19,22 @@
 [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
 [variant]: #variant
 [variants]: #variant
@@ -66,10 +76,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 +103,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 +151,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 +270,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 +307,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 +325,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 +340,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 +351,82 @@ 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 include _replace_ (the default), _merge_
+(avoid replacing a list), _delete_ and a few more
+(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,138 +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

docs/plugins/README.md

@@ -0,0 +1,333 @@
+# 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
+
+#### 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.
+
+
+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.
+
+### 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/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,117 @@
+[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} go get \
+    sigs.k8s.io/kustomize/cmd/kustomize@${releaseVersion}
+```
+
+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,337 @@
+# 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
+ * Google cloud (gcloud) install
+ * a Google account (will use Google kms -
+   volunteers needed to convert to a GPG example).
+
+## Make a place to work
+
+```
+# 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):
+
+```
+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:
+
+> ```
+> $XGD_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
+
+```
+PLUGIN_ROOT=$DEMO/kustomize/plugin
+```
+
+and ephemerally set `XGD_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
+
+```
+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.
+
+```
+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:
+
+```
+mkdir -p $PLUGIN_ROOT/${apiVersion}
+cd $PLUGIN_ROOT/${apiVersion}
+git clone git@github.com:monopole/sopsencodedsecrets.git
+```
+
+Remember this directory:
+
+```
+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:
+
+```
+cd $MY_PLUGIN_DIR
+go test SopsEncodedSecrets_test.go
+```
+
+Build the object code for use by kustomize:
+
+```
+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:
+
+```
+MYAPP=$DEMO/myapp
+mkdir -p $MYAPP
+```
+
+Make a config file for the SopsEncodedSecrets plugin.
+
+Its `apiVersion` and `kind` allow the plugin to be
+found:
+
+```
+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:
+
+```
+cat <<EOF >$MYAPP/kustomization.yaml
+commonLabels:
+  app: hello
+generators:
+- secGenerator.yaml
+EOF
+```
+
+Now for the hard part.  Generate the real encrypted data.
+
+
+### Assure you have a Google Cloud sops key ring.
+
+We're going to use [sops](https://github.com/mozilla/sops) to encode a file.
+
+Try this:
+
+```
+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:
+
+```
+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:
+```
+keyLocation=$(\
+    gcloud kms keys list --location global --keyring sops |\
+    grep GOOGLE | cut -d " " -f1)
+echo $keyLocation
+```
+
+### Install `sops`
+
+```
+GOPATH=$tmpGoPath go install go.mozilla.org/sops/cmd/sops
+```
+
+### Create data encrypted with your Google Cloud key
+
+Create raw data to encrypt:
+```
+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:
+
+```
+$tmpGoPath/bin/sops --encrypt \
+  --gcp-kms $keyLocation \
+  $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml
+```
+
+
+Review the files
+```
+tree $DEMO
+```
+
+This should look something like:
+
+> ```
+> /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:
+
+```
+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
+
+> ```
+> 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/versioningPolicy.md

@@ -0,0 +1,242 @@
+# Versioning
+
+Running `kustomize` means one is running a
+particular version of a program, using a
+particular version of underlying packages, and
+reading a particular version of a [kustomization]
+file.
+
+## Program Versioning
+
+The command `kustomize version` prints a three
+field version tag (e.g. `v3.0.0`) that aspires to
+[semantic versioning].
+
+When enough changes have accumulated to
+warrant a new release, a [release process]
+is followed, and the fields in the version
+number are bumped per semver.
+
+## Kustomize packages
+
+At the time of writing, the kustomize program and
+the packages it uses (and exports) are in the same
+Go module (see the top level `go.mod` file in the
+repo).
+
+[trailing major version indicator]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher
+
+Thus, they share the module's version number, per
+its git tag (e.g. `v3.0.0`), whose major verion
+number matches the [trailing major version
+indicator] in the module name (e.g. the `/v3` in
+`sigs.k8s.io/kustomize/v3`).
+
+The non-internal packages in the Go module
+`sigs.k8s.io/kustomize/v3`, introduced in
+[v3.0.0](v3.0.0.md), conform to [semantic
+versioning].
+
+
+## Kustomization File Versioning
+
+At the time of writing (circa release of v2.0.0):
+
+- A [kustomization] file is just a YAML file that
+  can be successfully parsed into a particular Go
+  struct defined in the `kustomize` binary.
+
+- This struct does not have a version number,
+  which is the same as saying that its version
+  number matches the program's version number,
+  since it's compiled in.
+
+### Field Change Policy
+
+- A field's meaning cannot be changed.
+
+- A field may be deprecated, then removed.
+
+- Deprecation means triggering a _minor_ (semver)
+  version bump in the program, and
+  defining a migration path in a non-fatal
+  error message.
+
+- Removal means triggering a _major_ (semver)
+  version bump, and fatal error if field encountered
+  (as with any unknown field).
+
+### 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_ program revisions.  There is
+no downgrade capability, as there's no use case
+for it (see discussion below).
+
+### Examples
+
+At the time of writing, in v1.0.x, there were 12
+minor releases, with backward compatible
+deprecations fixable via `edit fix`.
+
+With the 2.0.0 release, there were three field
+removals:
+
+- `imageTag` was deprecated when `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).
+
+### Kustomization file versioning
+
+The critical difference between k8s API versioning
+and kustomization file versioning is
+
+- A k8s API server is able to go _forward_ and
+  _backward_ in versioning, to work with older
+  clients, over [some range].
+
+- The `kustomize edit fix` command only moves
+  _forward_ within a _major_ program
+  version.
+
+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.
+
+#### Optional use of k8s `kind` and `apiVersion`
+
+At the time of writing two [special] k8s
+resource fields are allowed, but not required, in
+a kustomization file: [`kind`] and [`apiVersion`].
+
+If either field is present, they both must be, and
+they must have the following values:
+
+``` yaml
+kind: Kustomization
+apiVersion: kustomize.config.k8s.io/v1beta1
+```
+
+They are allowed to exist and have specific values
+in a kustomization file only as a sort of
+domain-squatting behavior for some future API.  A
+kustomize user gains nothing from adding these
+fields to a kustomization file.
+
+### Why not require `kind` and `apiVersion`
+
+#### Ease of use and setting proper expectations
+
+Use cases for a kustomization file don't include a
+server storing muliple k8s kinds and offering
+version downgrades.
+
+The kustomization file is more akin to a
+`Makefile`.  A kustomize command can either read a
+kustomization file, or it cannot, and in the later
+case will complain as specifically as possible
+about why (e.g. `unknown field Foo`).
+
+So requiring a `kind` and `apiVersion` would just
+be boilerplate in a user's files, and in all the
+examples and tests.
+
+Nevertheless, _a user still benefits from a
+versioning policy_ and has a `fix` command to
+upgrade files as needed.
+
+#### We can change our minds
+
+When/if the kustomization struct graduates to some
+kind of API status, with an expectation of
+"versionless" storage and downgrade capability,
+whatever it looks like at that moment can be
+locked into `/v1beta1` or `/v1` and the `kind`
+and `apiVersion` fields can be required from that
+moment forward.
+
+[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/api-conventions.md#resources
+[k8s API]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
+[conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
+[release process]: ../releasing/README.md
+[kustomization]: glossary.md#kustomization
+[`kind`]: https://github.com/kubernetes/community/blob/master/contributors/devel/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 @test -->
+```
+go install sigs.k8s.io/kustomize/v3/cmd/kustomize
+```

docs/zh/README.md

@@ -0,0 +1,48 @@
+[English](../README.md) | 简体中文
+
+# 文档
+
+ * [安装说明](INSTALL.md)
+
+ * [示例](../../examples) - 各种使用流程和概念的详细演示。
+
+ * [术语表](../glossary.md) - 用于消除术语歧义。
+
+ * [Kustomize 字段](fields.md) - 介绍 [kustomization](../glossary.md#kustomization) 文件中各字段的含义。
+
+ * [插件](../plugins) - 使用自定义的资源生成器和资源转换器来拓展 kustomize 功能。
+
+ * [工作流](workflows.md) - 使用定制及使用现成配置使用的一些步骤。
+
+ * [FAQ](../FAQ.md)
+
+
+## 发行说明
+
+ * [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/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,33 +1,72 @@
+English | [简体中文](zh/README.md)
+
 # Examples
 
 These examples assume that `kustomize` is on your `$PATH`.
 
-They are covered by [pre-commit](../bin/pre-commit.sh)
+They are covered by [pre-commit](../travis/pre-commit.sh)
 tests, and should work with HEAD
 
 <!-- @installkustomize @test -->
 ```
-go get github.com/kubernetes-sigs/kustomize
+go get sigs.k8s.io/kustomize/v3/cmd/kustomize
 ```
 
- * [hello world](helloWorld/README.md) - Deploy multiple
-   (differently configured) variants of a simple Hello
-   World server.
+Basic Usage
 
- * [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
-   application production configuration from scratch.
-
- * [configGeneration](configGeneration.md) -
+  * [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. 
 
- * [breakfast](breakfast.md) - Customize breakfast for
-   Alice and Bob.
+  * [vars](wordpress/README.md) - Injecting k8s runtime data into
+     container arguments (e.g. to point wordpress to a SQL service) by vars.
+ 
+  * [image names and tags](image.md) - Updating image names and tags without applying a patch.
+ 
+  * [remote target](remoteBuild.md) - Building a kustomization from a github URL
+ 
+  * [json patch](jsonpatch.md) - Apply a json patch in a kustomization    
+
+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. 
+
+- transformer plugins:
+   * [validation transformer](validationTransformer/README.md) -
+   validate resources through a transformer
+  
+- customize builtin transformer configurations
+  
+   * [transformer configs](transformerconfigs/README.md) - Customize transformer configurations
    
- * [container args](wordpress/README.md) - Injecting k8s runtime data into container arguments (e.g. to point wordpress to a SQL service).
+
+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.
+     
+  * [springboot](springboot/README.md) - Create a Spring Boot
+   application production configuration from scratch.
+
+  * [mySql](mySql/README.md) - Create a MySQL production
+   configuration from scratch.
+ 
+  * [breakfast](breakfast.md) - Customize breakfast for
+     Alice and Bob.
+     
+  * [multibases](multibases/README.md) - Composing three variants (dev, staging, production) with a common base.  

examples/breakfast.md

@@ -71,9 +71,9 @@ 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
 
@@ -94,9 +94,9 @@ 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
 

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

@@ -0,0 +1,300 @@
+[overlay]: ../docs/glossary.md#overlay
+[target]: ../docs/glossary.md#target
+
+# Demo: combining config data from devops and developers
+
+Scenario: you have a Java-based server storefront in
+production that various internal development teams
+(signups, checkout, search, etc.) contribute to.
+
+The server runs in different environments:
+_development_, _testing_, _staging_ and _production_,
+accepting configuration parameters from java property
+files.
+
+Using one big properties file for each environment is
+difficult to manage.  The files change frequently, and
+have to be changed by devops exclusively because
+
+  1. the files must at least partially agree on certain
+     values that devops cares about and that developers
+     ignore and
+  1. because the production
+     properties contain sensitive data like production
+     database credentials.
+
+## Property sharding
+
+With some study, we notice that the properties are
+separable into categories.
+
+### Common properties
+
+E.g. internationalization data, static data like
+physical constants, location of external services, etc.
+
+_Things that are the same regardless of environment._
+
+Only one set of values is needed.
+
+Place them in a file called
+
+ * `common.properties`
+
+(relative location defined below).
+
+### Plumbing properties
+
+E.g. serving location of static content (HTML, CSS,
+javascript), location of product and customer database
+tables, ports expected by load balancers, log sinks,
+etc.
+
+_The different values for these properties are
+precisely what sets the environments apart._
+
+Devops or SRE will want full control over the values
+used in production.  Testing will have fixed
+databases supporting testing.  Developers will want
+to do whatever they want to try scenarios under
+development.
+
+Places these values in
+
+ * `development/plumbing.properties`
+ * `staging/plumbing.properties`
+ * `production/plumbing.properties`
+
+
+### Secret properties
+
+E.g. location of actual user tables, database
+credentials, decryption keys, etc.
+
+_Things that are a subset of devops controls, that
+nobody else has (or should want) access to._
+
+Places these values in
+
+ * `development/secret.properties`
+ * `staging/secret.properties`
+ * `production/secret.properties`
+
+[kubernetes secret]: https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/
+
+and control access to them with (for example) unix file
+owner and mode bits, or better yet, put them in
+a server dedicated to storing password protected
+secrets, and use a field called  `secretGenerator`
+in your _kustomization_ to create a kubernetes
+secret holding them (not covering that here).
+
+<!--
+secretGenerator:
+- name: app-tls
+  files:
+    tls.crt=tls.cert
+    tls.key=tls.key
+  type: "kubernetes.io/tls"
+EOF
+-->
+
+## A mixin approach to management
+
+The way to create _n_ cluster environments that share
+some common information is to create _n_ overlays of a
+common base.
+
+For the rest of this example, we'll do _n==2_, just
+_development_ and _production_, since adding more
+environments follows the same pattern.
+
+A cluster environment is created by
+running `kustomize build` on a [target] that happens to
+be an [overlay].
+
+[helloworld]: helloWorld/README.md
+
+The following example will do that, but will focus on
+configMap construction, and not worry about how to
+connect the configMaps to deployments (that is covered
+in the [helloworld] example).
+
+
+All files - including the shared property files
+discussed above - will be created in a directory tree
+that is consistent with the base vs overlay file layout
+defined in the [helloworld] demo.
+
+It will all live in this work directory:
+
+<!-- @makeWorkplace @test -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+### Create the base
+
+<!-- kubectl create configmap BOB --dry-run -o yaml --from-file db. -->
+
+Make a place to put the base configuration:
+
+<!-- @baseDir @test -->
+```
+mkdir -p $DEMO_HOME/base
+```
+
+Make the data for the base.  This direction by
+definition should hold resources common to all
+environments. Here we're only defining a java
+properties file, and a `kustomization` file that
+references it.
+
+<!-- @baseKustomization @test -->
+```
+cat <<EOF >$DEMO_HOME/base/common.properties
+color=blue
+height=10m
+EOF
+
+cat <<EOF >$DEMO_HOME/base/kustomization.yaml
+configMapGenerator:
+- name: my-configmap
+  files:
+  - common.properties
+EOF
+```
+
+
+### Create and use the overlay for _development_
+
+Make an abbreviation for the parent of the overlay
+directories:
+
+<!-- @overlays @test -->
+```
+OVERLAYS=$DEMO_HOME/overlays
+```
+
+Create the files that define the _development_ overlay:
+
+<!-- @developmentFiles @test -->
+```
+mkdir -p $OVERLAYS/development
+
+cat <<EOF >$OVERLAYS/development/plumbing.properties
+port=30000
+EOF
+
+cat <<EOF >$OVERLAYS/development/secret.properties
+dbpassword=mothersMaidenName
+EOF
+
+cat <<EOF >$OVERLAYS/development/kustomization.yaml
+resources:
+- ../../base
+namePrefix: dev-
+nameSuffix: -v1
+configMapGenerator:
+- name: my-configmap
+  behavior: merge
+  files:
+  - plumbing.properties
+  - secret.properties
+EOF
+```
+
+One can now generate the configMaps for development:
+
+<!-- @runDev @test -->
+```
+kustomize build $OVERLAYS/development
+```
+
+#### Check the ConfigMap name
+
+The name of the generated `ConfigMap` is visible in this
+output.
+
+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,
+ * `"-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
+changes, so does the configMap name, along with all
+references to that name that appear in the YAML output
+from `kustomize`.
+
+The name change means deployments will do a rolling
+restart to get new data if this YAML is applied to the
+cluster using a command like
+
+> ```
+> kustomize build $OVERLAYS/development | kubectl apply -f -
+> ```
+
+A deployment has no means to automatically know when or
+if a configMap in use by the deployment changes.
+
+If one changes a configMap without changing its name
+and all references to that name, one must imperatively
+restart the cluster to pick up the change.
+
+The best practice is to treat configMaps as immutable.
+
+Instead of editing configMaps, modify your declarative
+specification of the cluster's desired state to
+point deployments to _new_ configMaps with _new_ names.
+`kustomize` makes this easy with its
+`configMapGenerator` directive and associated naming
+controls.  A GC process in the k8s master eventually
+deletes unused configMaps.
+
+
+### Create and use the overlay for _production_
+
+Next, create the files for the _production_ overlay:
+
+
+<!-- @productionFiles @test -->
+```
+mkdir -p $OVERLAYS/production
+
+cat <<EOF >$OVERLAYS/production/plumbing.properties
+port=8080
+EOF
+
+cat <<EOF >$OVERLAYS/production/secret.properties
+dbpassword=thisShouldProbablyBeInASecretInstead
+EOF
+
+cat <<EOF >$OVERLAYS/production/kustomization.yaml
+resources:
+- ../../base
+namePrefix: prod-
+configMapGenerator:
+- name: my-configmap
+  behavior: merge
+  files:
+  - plumbing.properties
+  - secret.properties
+EOF
+```
+
+One can now generate the configMaps for production:
+
+<!-- @runProd @test -->
+```
+kustomize build $OVERLAYS/production
+```
+
+A CICD process could apply this directly to
+the cluster using:
+
+> ```
+> kustomize build $OVERLAYS/production | kubectl apply -f -
+> ```

examples/configGeneration.md

@@ -1,298 +1,213 @@
-[overlay]: ../docs/glossary.md#overlay
-[target]: ../docs/glossary.md#target
+[patch]: ../docs/glossary.md#patch
+[resource]: ../docs/glossary.md#resource
+[variant]: ../docs/glossary.md#variant
 
-# Demo: combining config data from devops and developers
+## ConfigMap generation and rolling updates
 
-Scenario: you have a Java-based server storefront in
-production that various internal development teams
-(signups, checkout, search, etc.) contribute to.
+Kustomize provides two ways of adding ConfigMap in one `kustomization`, either by declaring ConfigMap as a [resource] or declaring ConfigMap from a ConfigMapGenerator. The formats inside `kustomization.yaml` are 
 
-The server runs in different environments:
-_development_, _testing_, _staging_ and _production_,
-accepting configuration parameters from java property
-files.
+> ```
+> # declare ConfigMap as a resource
+> resources:
+> - configmap.yaml
+> 
+> # declare ConfigMap from a ConfigMapGenerator
+> configMapGenerator:
+> - name: a-configmap
+>   files:
+>     - configs/configfile
+>     - configs/another_configfile
+> ```
 
-Using one big properties file for each environment is
-difficult to manage.  The files change frequently, and
-have to be changed by devops exclusively because
+The ConfigMaps declared as [resource] are treated the same way as other resources. Kustomize doesn't append any hash to the ConfigMap name. The ConfigMap declared from a ConfigMapGenerator is treated differently. A hash is appended to the name and any change in the ConfigMap will trigger a rolling update.
 
-  1. the files must at least partially agree on certain
-     values that devops cares about and that developers
-     ignore and
-  1. because the production
-     properties contain sensitive data like production
-     database credentials.
+In this demo, the same [hello_world](helloWorld/README.md) is used while the ConfigMap declared as [resources] is replaced by a ConfigMap declared from a ConfigmapGenerator. The change in this ConfigMap will result in a hash change and a rolling update.
 
-## Property sharding
+### Establish base and staging
 
-With some study, we notice that the properties are
-separable into categories.
-
-### Common properties
-
-E.g. internationalization data, static data like
-physical constants, location of external services, etc.
-
-_Things that are the same regardless of environment._
-
-Only one set of values is needed.
-
-Place them in a file called
-
- * `common.properties`
-
-(relative location defined below).
-
-### Plumbing properties
-
-E.g. serving location of static content (HTML, CSS,
-javascript), location of product and customer database
-tables, ports expected by load balancers, log sinks,
-etc.
-
-_The different values for these properties are
-precisely what sets the environments apart._
-
-Devops or SRE will want full control over the values
-used in production.  Testing will have fixed
-databases supporting testing.  Developers will want
-to do whatever they want to try scenarios under
-development.
-
-Places these values in
-
- * `development/plumbing.properties`
- * `staging/plumbing.properties`
- * `production/plumbing.properties`
-
-
-### Secret properties
-
-E.g. location of actual user tables, database
-credentials, decryption keys, etc.
-
-_Things that are a subset of devops controls, that
-nobody else has (or should want) access to._
-
-Places these values in
-
- * `development/secret.properties`
- * `staging/secret.properties`
- * `production/secret.properties`
-
-[kubernetes secret]: https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/
-
-and control access to them with (for example) unix file
-owner and mode bits, or better yet, put them in
-a server dedicated to storing password protected
-secrets, and use a field called  `secretGenerator`
-in your _kustomization_ to create a kubernetes
-secret holding them (not covering that here).
-
-<!--
-secretGenerator:
-- name: app-tls
-  commands:
-    tls.crt: "cat tls.cert"
-    tls.key: "cat tls.key"
-  type: "kubernetes.io/tls"
-EOF
--->
-
-## A mixin approach to management
-
-The way to create _n_ cluster environments that share
-some common information is to create _n_ overlays of a
-common base.
-
-For the rest of this example, we'll do _n==2_, just
-_development_ and _production_, since adding more
-environments follows the same pattern.
-
-A cluster environment is created by
-running `kustomize build` on a [target] that happens to
-be an [overlay].
-
-[helloworld]: helloworld.md
-
-The following example will do that, but will focus on
-configMap construction, and not worry about how to
-connect the configMaps to deployments (that is covered
-in the [helloworld] example).
-
-
-All files - including the shared property files
-discussed above - will be created in a directory tree
-that is consistent with the base vs overlay file layout
-defined in the [helloworld] demo.
-
-It will all live in this work directory:
-
-<!-- @makeWorkplace @test -->
+Establish the base with a configMapGenerator
+<!-- @establishBase @test -->
 ```
 DEMO_HOME=$(mktemp -d)
-```
 
-### Create the base
+BASE=$DEMO_HOME/base
+mkdir -p $BASE
 
-<!-- kubectl create configmap BOB --dry-run -o yaml --from-file db. -->
+curl -s -o "$BASE/#1.yaml" "https://raw.githubusercontent.com\
+/kubernetes-sigs/kustomize\
+/master/examples/helloWorld\
+/{deployment,service}.yaml"
 
-Make a place to put the base configuration:
-
-<!-- @baseDir @test -->
-```
-mkdir -p $DEMO_HOME/base
-```
-
-Make the data for the base.  This direction by
-definition should hold resources common to all
-environments. Here we're only defining a java
-properties file, and a `kustomization` file that
-references it.
-
-<!-- @baseKustomization @test -->
-```
-cat <<EOF >$DEMO_HOME/base/common.properties
-color=blue
-height=10m
-EOF
-
-cat <<EOF >$DEMO_HOME/base/kustomization.yaml
-configMapGenerator:
-- name: my-configmap
-  files:
-  - common.properties
+cat <<'EOF' >$BASE/kustomization.yaml
+commonLabels:
+  app: hello
+resources:
+- deployment.yaml
+- service.yaml
+configMapGenerator:	
+- name: the-map	
+  literals:	
+    - altGreeting=Good Morning!	
+    - enableRisky="false"
 EOF
 ```
 
-
-### Create and use the overlay for _development_
-
-Make an abbreviation for the parent of the overlay
-directories:
-
-<!-- @overlays @test -->
+Establish the staging with a patch applied to the ConfigMap
+<!-- @establishStaging @test -->
 ```
 OVERLAYS=$DEMO_HOME/overlays
-```
+mkdir -p $OVERLAYS/staging
 
-Create the files that define the _development_ overlay:
-
-<!-- @developmentFiles @test -->
-```
-mkdir -p $OVERLAYS/development
-
-cat <<EOF >$OVERLAYS/development/plumbing.properties
-port=30000
-EOF
-
-cat <<EOF >$OVERLAYS/development/secret.properties
-dbpassword=mothersMaidenName
-EOF
-
-cat <<EOF >$OVERLAYS/development/kustomization.yaml
-bases:
+cat <<'EOF' >$OVERLAYS/staging/kustomization.yaml
+namePrefix: staging-
+nameSuffix: -v1
+commonLabels:
+  variant: staging
+  org: acmeCorporation
+commonAnnotations:
+  note: Hello, I am staging!
+resources:
 - ../../base
-namePrefix: dev-
-configMapGenerator:
-- name: my-configmap
-  behavior: merge
-  files:
-  - plumbing.properties
-  - secret.properties
+patchesStrategicMerge:
+- map.yaml
+EOF
+
+cat <<EOF >$OVERLAYS/staging/map.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: the-map
+data:
+  altGreeting: "Have a pineapple!"
+  enableRisky: "true"
 EOF
 ```
 
-One can now generate the configMaps for development:
+### Review
 
-<!-- @runDev @test -->
+The _hello-world_ deployment running in this cluster is
+configured with data from a configMap.
+
+The deployment refers to this map by name:
+
+
+<!-- @showDeployment @test -->
 ```
-kustomize build $OVERLAYS/development
+grep -C 2 configMapKeyRef $BASE/deployment.yaml
 ```
 
-#### Check the ConfigMap name
+Changing the data held by a live configMap in a cluster
+is considered bad practice. Deployments have no means
+to know that the configMaps they refer to have
+changed, so such updates have no effect.
 
-The name of the generated `ConfigMap` is visible in this
-output.
+The recommended way to change a deployment's
+configuration is to
 
-The name should be something like `dev-my-configmap-b5m75ck895`:
+ 1. create a new configMap with a new name,
+ 1. patch the _deployment_, modifying the name value of
+    the appropriate `configMapKeyRef` field.
 
- * `"dev-"` comes from the `namePrefix` field,
- * `"my-configmap"` comes from the `configMapGenerator/name` field,
- * `"-b5m75ck895"` comes from a deterministic hash that `kustomize`
-    computes from the contents of the configMap.
+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](https://github.com/kubernetes-sigs/kustomize/issues/242).
 
-The hash suffix is critical.  If the configMap content
-changes, so does the configMap name, along with all
-references to that name that appear in the YAML output
-from `kustomize`.
+### How this works with kustomize
 
-The name change means deployments will do a rolling
-restart to get new data if this YAML is applied to the
-cluster using a command like
+The _staging_ [variant] here has a configMap [patch]:
 
-> ```
-> kustomize build $OVERLAYS/development | kubectl apply -f -
-> ```
-
-A deployment has no means to automatically know when or
-if a configMap in use by the deployment changes.
-
-If one changes a configMap without changing its name
-and all references to that name, one must imperatively
-restart the cluster to pick up the change.
-
-The best practice is to treat configMaps as immutable.
-
-Instead of editing configMaps, modify your declarative
-specification of the cluster's desired state to
-point deployments to _new_ configMaps with _new_ names.
-`kustomize` makes this easy with its
-`configMapGenerator` directive and associated naming
-controls.  A GC process in the k8s master eventually
-deletes unused configMaps.
-
-
-### Create and use the overlay for _production_
-
-Next, create the files for the _production_ overlay:
-
-
-<!-- @productionFiles @test -->
+<!-- @showMapPatch @test -->
 ```
-mkdir -p $OVERLAYS/production
-
-cat <<EOF >$OVERLAYS/production/plumbing.properties
-port=8080
-EOF
-
-cat <<EOF >$OVERLAYS/production/secret.properties
-dbpassword=thisShouldProbablyBeInASecretInstead
-EOF
-
-cat <<EOF >$OVERLAYS/production/kustomization.yaml
-bases:
-- ../../base
-namePrefix: prod-
-configMapGenerator:
-- name: my-configmap
-  behavior: merge
-  files:
-  - plumbing.properties
-  - secret.properties
-EOF
+cat $OVERLAYS/staging/map.yaml
 ```
 
-One can now generate the configMaps for production:
+This patch is by definition a named but not necessarily
+complete resource spec intended to modify a complete
+resource spec.
 
-<!-- @runProd @test -->
+The ConfigMap it modifies is declared from a configMapGenerator.
+
+<!-- @showMapBase @test -->
 ```
-kustomize build $OVERLAYS/production
+grep -C 4 configMapGenerator $BASE/kustomization.yaml
 ```
 
-A CICD process could apply this directly to
-the cluser using:
+For a patch to work, the names in the `metadata/name`
+fields must match.
 
-> ```
-> kustomize build $OVERLAYS/production | kubectl apply -f -
-> ```
+However, the name values specified in the file are
+_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 -->
+```
+kustomize build $OVERLAYS/staging |\
+    grep -B 8 -A 1 staging-the-map
+```
+
+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 _k25m8k5k5m_:
+
+<!-- @grepStagingHash @test -->
+```
+kustomize build $OVERLAYS/staging | grep k25m8k5k5m
+```
+
+Now modify the map patch, to change the greeting
+the server will use:
+
+<!-- @changeMap @test -->
+```
+sed -i.bak 's/pineapple/kiwi/' $OVERLAYS/staging/map.yaml
+```
+
+See the new greeting:
+
+```
+kustomize build $OVERLAYS/staging |\
+  grep -B 2 -A 3 kiwi
+```
+
+Run kustomize again to see the new configMap names:
+
+<!-- @grepStagingName @test -->
+```
+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 _cd7kdh48fd_ - one in the
+configMap name itself, and two in the deployment that
+uses the map:
+
+<!-- @countHashes @test -->
+```
+test 3 == \
+  $(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 _k25m8k5k5m_ maps to the _cd7kdh48fd_
+maps.  The system will later garbage collect the
+unused maps.
+
+## Rollback
+
+To rollback, one would undo whatever edits were made to
+the configuation in source control, then rerun kustomize
+on the reverted configuration and apply it to the
+cluster.

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 @test -->
+```
+cat > $DEMO_HOME/kustomization.yaml << EOF
+configMapGenerator:
+- name: my-configmap
+  literals:	
+  - foo=bar
+  - baz=qux
+EOF
+```
+
+Add following generatorOptions
+<!-- @addGeneratorOptions @test -->
+```
+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 @test -->
+    ```
+    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/helloWorld/README.md

@@ -108,16 +108,10 @@ label_ applied to all resources:
 
 <!-- @addLabel @test -->
 ```
-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 -->
 ```
@@ -154,9 +148,9 @@ commonLabels:
   org: acmeCorporation
 commonAnnotations:
   note: Hello, I am staging!
-bases:
+resources:
 - ../../base
-patches:
+patchesStrategicMerge:
 - map.yaml
 EOF
 ```
@@ -195,9 +189,9 @@ commonLabels:
   org: acmeCorporation
 commonAnnotations:
   note: Hello, I am production!
-bases:
+resources:
 - ../../base
-patches:
+patchesStrategicMerge:
 - deployment.yaml
 EOF
 ```
@@ -315,130 +309,3 @@ To deploy, pipe the above commands to kubectl apply:
 > kustomize build $OVERLAYS/production |\
 >    kubectl apply -f -
 > ```
-
-## Rolling updates
-
-### Review
-
-The _hello-world_ deployment running in this cluster is
-configured with data from a configMap.
-
-The deployment refers to this map by name:
-
-
-<!-- @showDeployment @test -->
-```
-grep -C 2 configMapKeyRef $DEMO_HOME/base/deployment.yaml
-```
-
-Changing the data held by a live configMap in a cluster
-is considered bad practice. Deployments have no means
-to know that the configMaps they refer to have
-changed, so such updates have no effect.
-
-The recommended way to change a deployment's
-configuration is to
-
- 1. create a new configMap with a new name,
- 1. patch the _deployment_, modifying the name value of
-    the appropriate `configMapKeyRef` field.
-
-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.
-
-### How this works with kustomize
-
-The _staging_ [variant] here has a configMap [patch]:
-
-<!-- @showMapPatch @test -->
-```
-cat $OVERLAYS/staging/map.yaml
-```
-
-This patch is by definition a named but not necessarily
-complete resource spec intended to modify a complete
-resource spec.
-
-The resource it modifies is here:
-
-<!-- @showMapBase @test -->
-```
-cat $DEMO_HOME/base/configMap.yaml
-```
-
-For a patch to work, the names in the `metadata/name`
-fields must match.
-
-However, the name values specified in the file are
-_not_ what gets used in the cluster.  By design,
-kustomize modifies these names.  To see the names
-ultimately used in the cluster, just run kustomize:
-
-<!-- @grepStagingName @test -->
-```
-kustomize build $OVERLAYS/staging |\
-    grep -B 8 -A 1 staging-the-map
-```
-
-The configMap name is prefixed by _staging-_, per the
-`namePrefix` 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_:
-
-<!-- @grepStagingHash @test -->
-```
-kustomize build $OVERLAYS/staging | grep hhhhkfmgmk
-```
-
-Now modify the map patch, to change the greeting
-the server will use:
-
-<!-- @changeMap @test -->
-```
-sed -i 's/pineapple/kiwi/' $OVERLAYS/staging/map.yaml
-```
-
-See the new greeting:
-
-```
-kustomize build $OVERLAYS/staging |\
-  grep -B 2 -A 3 kiwi
-```
-
-Run kustomize again to see the new configMap names:
-
-<!-- @grepStagingName @test -->
-```
-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
-configMap name itself, and two in the deployment that
-uses the map:
-
-<!-- @countHashes @test -->
-```
-test 3 == \
-  $(kustomize build $OVERLAYS/staging | grep khk45ktkd9 | 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_
-maps.  The system will later garbage collect the
-unused maps.
-
-## Rollback
-
-To rollback, one would undo whatever edits were made to
-the configuation in source control, then rerun kustomize
-on the reverted configuration and apply it to the
-cluster.

examples/helloWorld/kustomization.yaml

@@ -5,5 +5,5 @@ commonLabels:
 
 resources:
 - deployment.yaml
-- configMap.yaml
 - service.yaml
+- configMap.yaml

examples/image.md

@@ -0,0 +1,76 @@
+# Demo: change image names and 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 image `busybox` and tag `1.29.0` can be changed by adding `images` in `kustomization.yaml`.
+
+
+Add `images`:
+<!-- @addImages @test -->
+```
+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 @test -->
+```
+kustomize build $DEMO_HOME
+```
+
+Confirm that this replaces _both_ busybox images and tags for `alpine:3.6`:
+
+<!-- @confirmImages @test -->
+```
+test 2 = \
+  $(kustomize build $DEMO_HOME | grep alpine:3.6 | wc -l); \
+  echo $?
+```

examples/integration_tests.sh

@@ -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 . || \
     { 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 @test -->
+```
+DEMO_HOME=$(mktemp -d)
+
+cat <<EOF >$DEMO_HOME/kustomization.yaml
+resources:
+- ingress.yaml
+EOF
+
+cat <<EOF >$DEMO_HOME/ingress.yaml
+apiVersion: extensions/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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+cat <<EOF >>$DEMO_HOME/kustomization.yaml
+patchesJson6902:
+- target:
+    group: extensions
+    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 @test -->
+```
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep "host: foo.bar.io" | wc -l); \
+  echo $?
+```
+Running `kustomize build $DEMO_HOME`, in the output confirm that the servicePort has been updated correctly.
+<!-- @confirmServicePort @test -->
+```
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep "servicePort: 8080" | wc -l); \
+  echo $?
+```
+
+If the patch is YAML-formatted, it will be parsed correctly:
+
+<!-- @applyYamlPatch @test -->
+```
+cat <<EOF >>$DEMO_HOME/kustomization.yaml
+patchesJson6902:
+- target:
+    group: extensions
+    version: v1beta1
+    kind: Ingress
+    name: my-ingress
+  path: ingress_patch.yaml
+EOF
+```
+
+<!-- @confirmYamlPatch @test -->
+```
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep "path: /test" | wc -l); \
+  echo $?
+```

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

@@ -0,0 +1,137 @@
+# Demo: multibases with 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.
+
+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 is just a single pod.
+
+Define a place to work:
+
+<!-- @makeWorkplace @test -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+Define a common base:
+<!-- @makeBase @test -->
+```
+BASE=$DEMO_HOME/base
+mkdir $BASE
+
+cat <<EOF >$BASE/kustomization.yaml
+resources:
+- pod.yaml
+EOF
+
+cat <<EOF >$BASE/pod.yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: myapp-pod
+  labels:
+    app: myapp
+spec:
+  containers:
+  - name: nginx
+    image: nginx:1.7.9
+EOF
+```
+
+Define a dev variant overlaying base:
+<!-- @makeDev @test -->
+```
+DEV=$DEMO_HOME/dev
+mkdir $DEV
+
+cat <<EOF >$DEV/kustomization.yaml
+resources:
+- ./../base
+namePrefix: dev-
+EOF
+```
+
+Define a staging variant overlaying base:
+<!-- @makeStaging @test -->
+```
+STAG=$DEMO_HOME/staging
+mkdir $STAG
+
+cat <<EOF >$STAG/kustomization.yaml
+resources:
+- ./../base
+namePrefix: stag-
+EOF
+```
+
+Define a production variant overlaying base:
+<!-- @makeProd @test -->
+```
+PROD=$DEMO_HOME/production
+mkdir $PROD
+
+cat <<EOF >$PROD/kustomization.yaml
+resources:
+- ./../base
+namePrefix: prod-
+EOF
+```
+
+Then define a _Kustomization_ composing three variants together:
+<!-- @makeTopLayer @test -->
+```
+cat <<EOF >$DEMO_HOME/kustomization.yaml
+resources:
+- ./dev
+- ./staging
+- ./production
+
+namePrefix: cluster-a-
+EOF
+```
+
+Now the workspace has following directories
+> ```
+> .
+> ├── base
+> │   ├── kustomization.yaml
+> │   └── pod.yaml
+> ├── dev
+> │   └── kustomization.yaml
+> ├── kustomization.yaml
+> ├── production
+> │   └── kustomization.yaml
+> └── staging
+>     └── kustomization.yaml
+> ```
+
+Confirm that the `kustomize build` output contains three pod objects from dev, staging and production variants.
+
+<!-- @confirmVariants @test -->
+```
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep cluster-a-dev-myapp-pod | wc -l); \
+  echo $?
+  
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep cluster-a-stag-myapp-pod | wc -l); \
+  echo $?
+  
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep cluster-a-prod-myapp-pod | wc -l); \
+  echo $?    
+```
+Similarly to adding different `namePrefix` in different variants, one can also add different `namespace` and compose those variants in
+one _kustomization_. For more details, take a look at [multi-namespaces](multi-namespace.md).

examples/multibases/base/kustomization.yaml

@@ -0,0 +1,2 @@
+resources:
+- pod.yaml

examples/multibases/base/pod.yaml

@@ -0,0 +1,10 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: myapp-pod
+  labels:
+    app: myapp
+spec:
+  containers:
+  - name: nginx
+    image: nginx:1.7.9

examples/multibases/dev/kustomization.yaml

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

examples/multibases/kustomization.yaml

@@ -0,0 +1,5 @@
+resources:
+- dev
+- staging
+- production
+namePrefix: cluster-a-

examples/multibases/multi-namespace.md

@@ -0,0 +1,115 @@
+# Demo: multi namespaces with a common base
+
+`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.
+
+Define a place to work:
+
+<!-- @makeWorkplace @test -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+Define a common base:
+<!-- @makeBase @test -->
+```
+BASE=$DEMO_HOME/base
+mkdir $BASE
+
+cat <<EOF >$BASE/kustomization.yaml
+resources:
+- pod.yaml
+EOF
+
+cat <<EOF >$BASE/pod.yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: myapp-pod
+  labels:
+    app: myapp
+spec:
+  containers:
+  - name: nginx
+    image: nginx:1.7.9
+EOF
+```
+
+Define a variant in namespace-a overlaying base:
+<!-- @makeNamespaceA @test -->
+```
+NSA=$DEMO_HOME/namespace-a
+mkdir $NSA
+
+cat <<EOF >$NSA/kustomization.yaml
+resources:
+- namespace.yaml
+- ../base
+namespace: namespace-a
+EOF
+
+cat <<EOF >$NSA/namespace.yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: namespace-a
+EOF
+```
+
+Define a variant in namespace-b overlaying base:
+<!-- @makeNamespaceB @test -->
+```
+NSB=$DEMO_HOME/namespace-b
+mkdir $NSB
+
+cat <<EOF >$NSB/kustomization.yaml
+resources:
+- namespace.yaml
+- ../base
+namespace: namespace-b
+EOF
+
+cat <<EOF >$NSB/namespace.yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: namespace-b
+EOF
+```
+
+Then define a _Kustomization_ composing two variants together:
+<!-- @makeTopLayer @test -->
+```
+cat <<EOF >$DEMO_HOME/kustomization.yaml
+resources:
+- namespace-a
+- namespace-b
+EOF
+```
+
+Now the workspace has following directories
+> ```
+> .
+> ├── base
+> │   ├── kustomization.yaml
+> │   └── pod.yaml
+> ├── kustomization.yaml
+> ├── namespace-a
+> │   ├── kustomization.yaml
+> │   └── namespace.yaml
+> └── namespace-b
+>     ├── kustomization.yaml
+>     └── namespace.yaml
+> ```
+
+Confirm that the `kustomize build` output contains two pod objects from namespace-a and namespace-b.
+
+<!-- @confirmVariants @test -->
+```
+test 2 == \
+  $(kustomize build $DEMO_HOME| grep -B 4 "namespace: namespace-[ab]" | grep "name: myapp-pod" | wc -l); \
+  echo $?  
+```

examples/multibases/production/kustomization.yaml

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

examples/multibases/staging/kustomization.yaml

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

examples/mySql/README.md

@@ -136,7 +136,7 @@ a label, but one can always edit `kustomization.yaml` directly:
 
 <!-- @customizeLabels @test -->
 ```
-sed -i 's/app: helloworld/app: prod/' \
+sed -i.bak 's/app: helloworld/app: prod/' \
     $DEMO_HOME/kustomization.yaml
 ```
 
@@ -150,7 +150,7 @@ 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 -->
@@ -176,11 +176,13 @@ Add the patch file to `kustomization.yaml`:
 <!-- @specifyPatch @test -->
 ```
 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.
 

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/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 @test -->
+
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+cat <<'EOF' >$DEMO_HOME/foo.env
+ROUTER_PASSWORD=admin
+DB_PASSWORD=iloveyou
+EOF
+```
+
+Make a text file with a long secret:
+
+<!-- @makeLongSecretFile @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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

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

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 `matadata/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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+cat >> $DEMO_HOME/kustomization.yaml << EOF
+configurations:
+- kustomizeconfig/mykind.yaml
+EOF
+```
+
+Run `kustomize build` and verify that the namereference is correctly resolved.
+
+<!-- @build @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+cat >> $DEMO_HOME/kustomization.yaml << EOF
+configurations:
+- kustomizeconfig/mykind.yaml
+EOF
+```
+
+Run `kustomize build` and verify that the images have been updated.
+
+<!-- @build @test -->
+```
+test 1 == \
+$(kustomize build $DEMO_HOME | grep -A 2 ".*image" | grep "new-crd-image:new-v1-tag" | wc -l); \
+echo $?
+```
+
+<!-- @build @test -->
+```
+test 1 == \
+$(kustomize build $DEMO_HOME | grep -A 2 ".*image" | grep "new-app-1:MYNEWTAG-1" | wc -l); \
+echo $?
+```
+
+<!-- @build @test -->
+```
+test 1 == \
+$(kustomize build $DEMO_HOME | grep -A 2 ".*image" | grep "my-docker2@sha" | wc -l); \
+echo $?
+```
+<!-- @build @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+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 @test -->
+```
+function kustomizeBd {
+  XDG_CONFIG_HOME=$DEMO_HOME \
+  kustomize build \
+    --enable_alpha_plugins \
+    $DEMO_HOME/$1
+}
+```
+
+Build the valid variant
+
+<!-- @buildValid @test -->
+```
+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 @test -->
+```shell
+rm -rf $DEMO_HOME
+```

examples/validationTransformer/invalid.yaml

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

examples/validationTransformer/valid.yaml

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

examples/wordpress/README.md

@@ -1,6 +1,6 @@
 # Demo: Injecting k8s runtime data into containers
 
-In this tutorial, you will learn how to use `kustomize` to declare a variable reference and substitute it in container's command.
+In this tutorial, you will learn how to use `kustomize` to declare a variable reference and substitute it in container's command. Note that, the substitution is not for arbitrary fields, it is only applicable to container env, args and command. 
 
 To run WordPress, it's necessary to
 
@@ -44,15 +44,19 @@ curl -s -o "$MYSQL_HOME/#1.yaml" \
 ```
 
 ### Create kustomization.yaml
-Create a new kustomization with two bases:
+
+Create a new kustomization with two bases,
+`wordpress` and `mysql`:
 
 <!-- @createKustomization @test -->
 ```
 cat <<EOF >$DEMO_HOME/kustomization.yaml
-bases:
-  - wordpress
-  - mysql
+resources:
+- wordpress
+- mysql
 namePrefix: demo-
+patchesStrategicMerge:
+- patch.yaml
 EOF
 ```
 
@@ -65,7 +69,7 @@ In the new kustomization, apply a patch for wordpress deployment. The patch does
 ```
 CONTENT="https://raw.githubusercontent.com\
 /kubernetes-sigs/kustomize\
-/master/examples/patch.yaml"
+/master/examples/wordpress"
 
 curl -s -o "$DEMO_HOME/#1.yaml" \
   "$CONTENT/{patch}.yaml"
@@ -141,4 +145,4 @@ Expect this in the output:
 >        image: debian
 >        name: init-command
 >
-> ```
+> ```

examples/wordpress/kustomization.yaml

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

examples/zh/README.md

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

examples/zh/configGeneration.md

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

examples/zh/helloWorld.md

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

examples/zh/jsonpatch.md

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

go.mod

@@ -0,0 +1,32 @@
+module sigs.k8s.io/kustomize/v3
+
+go 1.12
+
+require (
+	github.com/emicklei/go-restful v2.9.6+incompatible // indirect
+	github.com/evanphx/json-patch v4.5.0+incompatible
+	github.com/go-openapi/spec v0.19.2
+	github.com/gogo/protobuf v1.2.1 // indirect
+	github.com/golang/protobuf v1.3.1 // indirect
+	github.com/google/gofuzz v1.0.0 // indirect
+	github.com/googleapis/gnostic v0.3.0 // indirect
+	github.com/inconshreveable/mousetrap v1.0.0 // indirect
+	github.com/json-iterator/go v1.1.6 // indirect
+	github.com/mailru/easyjson v0.0.0-20190620125010-da37f6c1e481 // indirect
+	github.com/modern-go/reflect2 v1.0.1 // indirect
+	github.com/onsi/ginkgo v1.8.0 // indirect
+	github.com/onsi/gomega v1.5.0 // indirect
+	github.com/pkg/errors v0.8.1
+	github.com/spf13/cobra v0.0.2
+	github.com/spf13/pflag v1.0.3
+	golang.org/x/net v0.0.0-20190620200207-3b0461eec859 // indirect
+	golang.org/x/sys v0.0.0-20190621203818-d432491b9138 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	gopkg.in/yaml.v2 v2.2.2
+	k8s.io/api v0.0.0-20190313235455-40a48860b5ab
+	k8s.io/apimachinery v0.0.0-20190313205120-d7deff9243b1
+	k8s.io/client-go v11.0.0+incompatible
+	k8s.io/klog v0.3.3 // indirect
+	k8s.io/kube-openapi v0.0.0-20190603182131-db7b694dc208
+	sigs.k8s.io/yaml v1.1.0
+)