Merge pull request #1194 from monopole/moveKustomizeToCmd

Move kustomize main to cmd directory.

.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,26 +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
+  # 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 [demos](demos) 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,147 +0,0 @@
-# This file is autogenerated, do not edit; changes may be undone by the next 'dep ensure'.
-
-
-[[projects]]
-  name = "github.com/davecgh/go-spew"
-  packages = ["spew"]
-  revision = "346938d642f2ec3594ed81d874461961cd0faa76"
-  version = "v1.1.0"
-
-[[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]]
-  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]]
-  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/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"]
-  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/util/proto"]
-  revision = "b3f03f55328800731ce03a164b80973014ecd455"
-
-[[projects]]
-  branch = "master"
-  name = "k8s.io/utils"
-  packages = ["exec"]
-  revision = "258e2a2fa64568210fbd6267cf1d8fd87c3cb86e"
-
-[solve-meta]
-  analyzer-name = "dep"
-  analyzer-version = 1
-  inputs-digest = "6e36daa1798b0dae7f45160f9275ca6bbe6c5667de7cd808d0057cbaf19fc55e"
-  solver-name = "gps-cdcl"
-  solver-version = 1

Gopkg.toml

@@ -1,54 +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"

OWNERS_ALIASES

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

README.md

@@ -1,71 +1,174 @@
 # kustomize
 
-[applied]: docs/glossary.md#apply
-[base]: docs/glossary.md#base
-[declarative configuration]: docs/glossary.md#declarative-application-management
-[demo]: demos/README.md
-[demos]: demos/README.md
-[imageBase]: docs/base.jpg
-[imageOverlay]: docs/overlay.jpg
-[kubernetes style]: docs/glossary.md#kubernetes-style-object
-[KEP]: https://github.com/kubernetes/community/blob/master/keps/sig-cli/0008-kustomize.md
-[kustomization]: docs/glossary.md#kustomization
-[overlay]: docs/glossary.md#overlay
-[resources]: docs/glossary.md#resource
-[sig-cli]: https://github.com/kubernetes/community/blob/master/sig-cli/README.md
-[workflows]: docs/workflows.md
+`kustomize` lets you customize raw, template-free YAML
+files for multiple purposes, leaving the original YAML
+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.
 
-`kustomize` is a command line tool supporting
-template-free customization of YAML (or JSON) objects
-that conform to the [kubernetes style].  If your
-objects have a `kind` and a `metadata` field,
-`kustomize` can patch them to support configuration
-sharing and re-use.
+This tool is sponsored by [sig-cli] ([KEP]), and
+inspired by [DAM].
 
-For more details, try a [demo].
 
 [![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)
 
+Download a binary from the [release page], or see
+these [instructions](docs/INSTALL.md).
 
-## Installation
+Browse the [docs](docs) or jump right into the
+tested [examples](examples).
 
-This assumes [Go](https://golang.org/) (v1.10.1 or higher)
-is installed and your `PATH` contains `$GOPATH/bin`:
-
-<!-- @installkustomize @test -->
-```
-go get github.com/kubernetes-sigs/kustomize
-```
+kustomize [v2.0.3] is available in [kubectl v1.14][kubectl].
 
 
 ## Usage
 
-#### 1) Make a base
 
-A [base] configuration is a [kustomization] file listing a set of
-k8s [resources] - deployments, services, configmaps,
-secrets that serve some common purpose.
+### 1) Make a [kustomization] file
+
+In some directory containing your YAML [resource]
+files (deployments, services, configmaps, etc.), create a
+[kustomization] file.
+
+This file should declare those resources, and any
+customization to apply to them, e.g. _add a common
+label_.
 
 ![base image][imageBase]
 
-#### 2) Customize it with overlays
+File structure:
 
-An [overlay] customizes your base along different dimensions
-for different purposes or different teams, e.g. for
-_development, staging and production_.
+> ```
+> ~/someApp
+> ├── deployment.yaml
+> ├── kustomization.yaml
+> └── service.yaml
+> ```
+
+The resources in this directory could be a fork of
+someone else's configuration.  If so, you can easily
+rebase from the source material to capture
+improvements, because you don't modify the resources
+directly.
+
+Generate customized YAML with:
+
+```
+kustomize build ~/someApp
+```
+
+The YAML can be directly [applied] to a cluster:
+
+> ```
+> kustomize build ~/someApp | kubectl apply -f -
+> ```
+
+
+### 2) Create [variants] using [overlays]
+
+Manage traditional [variants] of a configuration - like
+_development_, _staging_ and _production_ - using
+[overlays] that modify a common [base].
 
 ![overlay image][imageOverlay]
 
-#### 3) Run kustomize
+File structure:
+> ```
+> ~/someApp
+> ├── base
+> │   ├── deployment.yaml
+> │   ├── kustomization.yaml
+> │   └── service.yaml
+> └── overlays
+>     ├── development
+>     │   ├── cpu_count.yaml
+>     │   ├── kustomization.yaml
+>     │   └── replica_count.yaml
+>     └── production
+>         ├── cpu_count.yaml
+>         ├── kustomization.yaml
+>         └── replica_count.yaml
+> ```
 
-Run `kustomize` on your overlay.  The result
-is printed to `stdout` as a set of complete
-resources, ready to be [applied] to a cluster.
-See the [demos].
+Take the work from step (1) above, move it into a
+`someApp` subdirectory called `base`, then
+place overlays in a sibling directory.
 
+An overlay is just another kustomization, refering to
+the base, and referring to patches to apply to that
+base.
 
-## About
+This arrangement makes it easy to manage your
+configuration with `git`.  The base could have files
+from an upstream repository managed by someone else.
+The overlays could be in a repository you own.
+Arranging the repo clones as siblings on disk avoids
+the need for git submodules (though that works fine, if
+you are a submodule fan).
 
-This project sponsored by [sig-cli] ([KEP]).
+Generate YAML with
+
+```sh
+kustomize build ~/someApp/overlays/production
+```
+
+The YAML can be directly [applied] to a cluster:
+
+> ```sh
+> kustomize build ~/someApp/overlays/production | kubectl apply -f -
+> ```
+
+## Community
+
+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].
+
+[`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
+[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
+[overlays]: docs/glossary.md#overlay
+[release page]: https://github.com/kubernetes-sigs/kustomize/releases
+[resource]: docs/glossary.md#resource
+[resources]: docs/glossary.md#resource
+[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
+[workflows]: docs/workflows.md

SECURITY_CONTACTS

@@ -0,0 +1,15 @@
+# Defined below are the security contacts for this repo.
+#
+# They are the contact point for the Product Security Team to reach out
+# to for triaging and handling of incoming issues.
+#
+# The below names agree to abide by the
+# [Embargo Policy](https://github.com/kubernetes/sig-release/blob/master/security-release-process-documentation/security-release-process.md#embargo-policy)
+# and will be removed and replaced if they violate that agreement.
+#
+# DO NOT REPORT SECURITY VULNERABILITIES DIRECTLY TO THESE NAMES, FOLLOW THE
+# INSTRUCTIONS AT https://kubernetes.io/security/
+
+monopole
+Liujingfang1
+pwittrock

bin/pre-commit.sh

@@ -1,56 +0,0 @@
-#!/bin/bash
-
-# 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 testGoImports {
-  diff -u <(echo -n) <(go_dirs | xargs -0 goimports -l)
-}
-
-function testGoVet {
-  go vet -all ./...
-}
-
-function testGoTest {
-  go test -v ./...
-}
-
-function testDemos {
-  mdrip --mode test --label test README.md ./demos
-}
-
-runTest testGoFmt
-runTest testGoImports
-runTest testGoVet
-runTest testGoTest
-runTest testDemos
-
-exit $rc

build/README.md

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

build/build.sh

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

build/cloudbuild.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+set -e
+set -x
+
+# Google Container Builder automatically checks
+# out all the code under the /workspace directory,
+# but we actually want it to under the correct
+# expected package in the GOPATH (/go)
+#
+# - Create the directory to host the code that
+#   matches the expected GOPATH package locations
+#
+# - Use /go as the default GOPATH because this is
+#   what the image uses
+#
+# - Link our current directory (containing the
+#   source code) to the package location in the
+#   GOPATH
+
+OWNER="sigs.k8s.io"
+REPO="kustomize"
+
+GO_PKG_OWNER=$GOPATH/src/$OWNER
+GO_PKG_PATH=$GO_PKG_OWNER/$REPO
+
+mkdir -p $GO_PKG_OWNER
+ln -sf $(pwd) $GO_PKG_PATH
+
+# When invoked in container builder, this script runs under /workspace which is
+# not under $GOPATH, so we need to `cd` to repo under GOPATH for it to build
+cd $GO_PKG_PATH
+
+
+# If snapshot is enabled, release is not published
+# to GitHub and the build is available under
+# workspace/dist directory.
+
+SNAPSHOT=""
+
+# parse commandline args copied from the link below
+# https://stackoverflow.com/questions/192249/how-do-i-parse-command-line-arguments-in-bash?utm_medium=organic&utm_source=google_rich_qa&utm_campaign=google_rich_qa
+while [[ $# -gt 0 ]]
+do
+key="$1"
+
+case $key in
+    --snapshot)
+    SNAPSHOT="--snapshot"
+    shift # past argument
+    ;;
+esac
+done
+
+/goreleaser \
+  release \
+  --config=build/goreleaser.yaml \
+  --rm-dist \
+  --skip-validate ${SNAPSHOT}

build/cloudbuild.yaml

@@ -1,23 +1,8 @@
-#  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"]
+- name: "gcr.io/kubebuilder/goreleaser_with_go_1.12.5:0.0.1"
+  args: ["bash", "build/cloudbuild.sh"]
   secretEnv: ['GITHUB_TOKEN']
 secrets:
 - kmsKeyName: projects/kustomize-199618/locations/global/keyRings/github-tokens/cryptoKeys/gh-release-token

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,18 +1,22 @@
-# This is an example goreleaser.yaml file with some sane defaults.
-# Make sure to check the documentation at http://goreleaser.com
+# Documentation at http://goreleaser.com
+# By default, output sent to ./dist (see docs).
+#
+# 2019-may-29: windows removed because of error
+#              pkg/plugins/execplugin.go:111:2: undefined: syscall.Mkfifo
+#
 project_name: kustomize
 builds:
-- main: ./kustomize.go
+- main: ./cmd/kustomize/main.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}}
+  ldflags: -s -X sigs.k8s.io/kustomize/pkg/commands/misc.kustomizeVersion={{.Version}} -X sigs.k8s.io/kustomize/pkg/commands/misc.gitCommit={{.Commit}} -X sigs.k8s.io/kustomize/pkg/commands/misc.buildDate={{.Date}}
   goos:
   - darwin
   - linux
-  - windows
   goarch:
    - amd64
   env:
   - CGO_ENABLED=0
+  - GO111MODULE=on
 checksum:
   name_template: 'checksums.txt'
 archive:

build/localbuild.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+
+# Usage
+#
+#   ./build/localbuild.sh
+#
+# The script attempts to use cloudbuild configuration
+# to create a release "locally".
+#
+# See https://cloud.google.com/cloud-build/docs/build-debug-locally
+#
+# At the time of writing,
+#
+#   https://pantheon.corp.google.com/cloud-build/triggers?project=kustomize-199618
+#
+# has a trigger such that whenever a git tag is
+# applied to the kustomize repo, the cloud builder
+# reads the repository-relative file
+#
+#   build/cloudbuild.yaml
+#  
+# Inside this yaml file is a reference to the script
+#
+#   build/cloudbuild.sh
+#
+# The script you are reading now does something
+# analogous via docker tricks.
+
+set -e
+
+if [ -z ${GOPATH+x} ]; then
+  echo GOPATH is unset; cannot proceed.
+  exit 1
+fi
+
+pushd $GOPATH/src/sigs.k8s.io/kustomize
+pwd
+
+# The first "step" in the following uses a special
+# goreleaser container image that the kubebuilder folks made.
+# TODO: On a rainy day, switch to something more standard.
+
+config=$(mktemp)
+cat <<EOF >$config
+steps:
+- name: "gcr.io/kubebuilder/goreleaser_with_go_1.12.5:0.0.1"
+  args: ["bash", "build/cloudbuild.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==
+EOF
+
+cloud-build-local \
+  --config=$config \
+  --bind-mount-source \
+  --dryrun=false \
+  .
+
+# Print results of local build, which went to ./dist
+echo "##########################################"
+tree ./dist
+echo "##########################################"
+
+popd

build/vendor_kustomize.diff

@@ -0,0 +1,281 @@
+commit 1b893558aa83ac6491e5ba416b493170a9045fec
+Author: Jingfang Liu <jingfangliu@google.com>
+Date:   Mon Nov 12 10:26:12 2018 -0800
+
+    last change
+
+diff --git a/staging/src/k8s.io/cli-runtime/artifacts/kustomization/configMap.yaml b/staging/src/k8s.io/cli-runtime/artifacts/kustomization/configMap.yaml
+new file mode 100644
+index 0000000000..0008853094
+--- /dev/null
++++ b/staging/src/k8s.io/cli-runtime/artifacts/kustomization/configMap.yaml
+@@ -0,0 +1,8 @@
++
++apiVersion: v1
++kind: ConfigMap
++metadata:
++  name: the-map
++data:
++  altGreeting: "Good Morning!"
++  enableRisky: "false"
+diff --git a/staging/src/k8s.io/cli-runtime/artifacts/kustomization/deployment.yaml b/staging/src/k8s.io/cli-runtime/artifacts/kustomization/deployment.yaml
+new file mode 100644
+index 0000000000..6e79409080
+--- /dev/null
++++ b/staging/src/k8s.io/cli-runtime/artifacts/kustomization/deployment.yaml
+@@ -0,0 +1,30 @@
++apiVersion: apps/v1
++kind: Deployment
++metadata:
++  name: the-deployment
++spec:
++  replicas: 3
++  template:
++    metadata:
++      labels:
++        deployment: hello
++    spec:
++      containers:
++      - name: the-container
++        image: monopole/hello:1
++        command: ["/hello",
++                  "--port=8080",
++                  "--enableRiskyFeature=$(ENABLE_RISKY)"]
++        ports:
++        - containerPort: 8080
++        env:
++        - name: ALT_GREETING
++          valueFrom:
++            configMapKeyRef:
++              name: the-map
++              key: altGreeting
++        - name: ENABLE_RISKY
++          valueFrom:
++            configMapKeyRef:
++              name: the-map
++              key: enableRisky
+diff --git a/staging/src/k8s.io/cli-runtime/artifacts/kustomization/kustomization.yaml b/staging/src/k8s.io/cli-runtime/artifacts/kustomization/kustomization.yaml
+new file mode 100644
+index 0000000000..6e1e3202d5
+--- /dev/null
++++ b/staging/src/k8s.io/cli-runtime/artifacts/kustomization/kustomization.yaml
+@@ -0,0 +1,5 @@
++nameprefix: test-
++ resources:
++- deployment.yaml
++- service.yaml
++- configMap.yaml
+diff --git a/staging/src/k8s.io/cli-runtime/artifacts/kustomization/service.yaml b/staging/src/k8s.io/cli-runtime/artifacts/kustomization/service.yaml
+new file mode 100644
+index 0000000000..2942cdb7df
+--- /dev/null
++++ b/staging/src/k8s.io/cli-runtime/artifacts/kustomization/service.yaml
+@@ -0,0 +1,13 @@
++kind: Service
++apiVersion: v1
++metadata:
++  name: the-service
++spec:
++  selector:
++    deployment: hello
++  type: LoadBalancer
++  ports:
++  - protocol: TCP
++    port: 8666
++    targetPort: 8080
++    
+\ No newline at end of file
+diff --git a/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/BUILD b/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/BUILD
+index 22b34de008..b91d1c0130 100644
+--- a/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/BUILD
++++ b/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/BUILD
+@@ -35,12 +35,15 @@ go_library(
+         "//staging/src/k8s.io/apimachinery/pkg/util/sets:go_default_library",
+         "//staging/src/k8s.io/apimachinery/pkg/util/yaml:go_default_library",
+         "//staging/src/k8s.io/apimachinery/pkg/watch:go_default_library",
++        "//staging/src/k8s.io/cli-runtime/pkg/kustomize/k8sdeps:go_default_library",
+         "//staging/src/k8s.io/client-go/discovery:go_default_library",
+         "//staging/src/k8s.io/client-go/kubernetes/scheme:go_default_library",
+         "//staging/src/k8s.io/client-go/rest:go_default_library",
+         "//staging/src/k8s.io/client-go/restmapper:go_default_library",
+         "//vendor/golang.org/x/text/encoding/unicode:go_default_library",
+         "//vendor/golang.org/x/text/transform:go_default_library",
++        "//vendor/sigs.k8s.io/kustomize/pkg/commands/build:go_default_library",
++        "//vendor/sigs.k8s.io/kustomize/pkg/fs:go_default_library",
+     ],
+ )
+ 
+diff --git a/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/builder_test.go b/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/builder_test.go
+index 7fd526b33c..801f13f772 100644
+--- a/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/builder_test.go
++++ b/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/builder_test.go
+@@ -465,27 +465,48 @@ func TestPathBuilderWithMultipleInvalid(t *testing.T) {
+ }
+ 
+ func TestDirectoryBuilder(t *testing.T) {
+-	b := newDefaultBuilder().
+-		FilenameParam(false, &FilenameOptions{Recursive: false, Filenames: []string{"../../../artifacts/guestbook"}}).
+-		NamespaceParam("test").DefaultNamespace()
++	tests := []struct {
++		directories   []string
++		singleItem    bool
++		number        int
++		expectedNames []string
++	}{
++		{[]string{"../../../artifacts/guestbook"}, false, 3, []string{"redis-master"}},
++		{[]string{"../../../artifacts/kustomization"}, true, 3, []string{"test-the-deployment"}},
++		{[]string{"../../../artifacts/guestbook", "../../../artifacts/kustomization"}, false, 6, []string{"redis-master", "test-the-deployment"}},
++	}
+ 
+-	test := &testVisitor{}
+-	singleItemImplied := false
++	for _, tt := range tests {
++		b := newDefaultBuilder().
++			FilenameParam(false, &FilenameOptions{Recursive: false, Filenames: tt.directories}).
++			NamespaceParam("test").DefaultNamespace()
+ 
+-	err := b.Do().IntoSingleItemImplied(&singleItemImplied).Visit(test.Handle)
+-	if err != nil || singleItemImplied || len(test.Infos) < 3 {
+-		t.Fatalf("unexpected response: %v %t %#v", err, singleItemImplied, test.Infos)
+-	}
++		test := &testVisitor{}
++		singleItemImplied := false
+ 
+-	found := false
+-	for _, info := range test.Infos {
+-		if info.Name == "redis-master" && info.Namespace == "test" && info.Object != nil {
+-			found = true
+-			break
++		err := b.Do().IntoSingleItemImplied(&singleItemImplied).Visit(test.Handle)
++		if err != nil || singleItemImplied != tt.singleItem || len(test.Infos) < tt.number {
++			t.Fatalf("unexpected response: %v %t %#v", err, singleItemImplied, test.Infos)
++		}
++
++		contained := func(name string) bool {
++			for _, info := range test.Infos {
++				if info.Name == name && info.Namespace == "test" && info.Object != nil {
++					return true
++				}
++			}
++			return false
++		}
++
++		allFound := true
++		for _, name := range tt.expectedNames {
++			if !contained(name) {
++				allFound = false
++			}
++		}
++		if !allFound {
++			t.Errorf("unexpected responses: %#v", test.Infos)
+ 		}
+-	}
+-	if !found {
+-		t.Errorf("unexpected responses: %#v", test.Infos)
+ 	}
+ }
+ 
+diff --git a/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/visitor.go b/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/visitor.go
+index 32c1a691a5..d7a37e1cde 100644
+--- a/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/visitor.go
++++ b/staging/src/k8s.io/cli-runtime/pkg/genericclioptions/resource/visitor.go
+@@ -20,10 +20,12 @@ import (
+ 	"bytes"
+ 	"fmt"
+ 	"io"
++	"io/ioutil"
+ 	"net/http"
+ 	"net/url"
+ 	"os"
+ 	"path/filepath"
++	"strings"
+ 	"time"
+ 
+ 	"golang.org/x/text/encoding/unicode"
+@@ -38,6 +40,9 @@ import (
+ 	utilerrors "k8s.io/apimachinery/pkg/util/errors"
+ 	"k8s.io/apimachinery/pkg/util/yaml"
+ 	"k8s.io/apimachinery/pkg/watch"
++	"k8s.io/cli-runtime/pkg/kustomize/k8sdeps"
++	"sigs.k8s.io/kustomize/pkg/commands/build"
++	"sigs.k8s.io/kustomize/pkg/fs"
+ )
+ 
+ const (
+@@ -452,7 +457,10 @@ func ExpandPathsToFileVisitors(mapper *mapper, paths string, recursive bool, ext
+ 		if err != nil {
+ 			return err
+ 		}
+-
++		if isKustomizationDir(path) {
++			visitors = append(visitors, NewKustomizationVisitor(mapper, path, schema))
++			return filepath.SkipDir
++		}
+ 		if fi.IsDir() {
+ 			if path != paths && !recursive {
+ 				return filepath.SkipDir
+@@ -463,7 +471,10 @@ func ExpandPathsToFileVisitors(mapper *mapper, paths string, recursive bool, ext
+ 		if path != paths && ignoreFile(path, extensions) {
+ 			return nil
+ 		}
+-
++		if strings.HasSuffix(path, "kustomization.yaml") {
++			visitors = append(visitors, NewKustomizationVisitor(mapper, filepath.Dir(path), schema))
++			return nil
++		}
+ 		visitor := &FileVisitor{
+ 			Path:          path,
+ 			StreamVisitor: NewStreamVisitor(nil, mapper, path, schema),
+@@ -479,6 +490,14 @@ func ExpandPathsToFileVisitors(mapper *mapper, paths string, recursive bool, ext
+ 	return visitors, nil
+ }
+ 
++func isKustomizationDir(path string) bool {
++	if _, err := os.Stat(filepath.Join(path, "kustomization.yaml")); err == nil {
++		return true
++	}
++	return false
++}
++
++
+ // FileVisitor is wrapping around a StreamVisitor, to handle open/close files
+ type FileVisitor struct {
+ 	Path string
+@@ -507,6 +526,37 @@ func (v *FileVisitor) Visit(fn VisitorFunc) error {
+ 	return v.StreamVisitor.Visit(fn)
+ }
+ 
++// KustomizationVisitor prorvides the output of kustomization build
++type KustomizationVisitor struct {
++	Path string
++	*StreamVisitor
++}
++
++// Visit in a KustomizationVisitor build the kustomization output
++func (v *KustomizationVisitor) Visit(fn VisitorFunc) error {
++	fSys := fs.MakeRealFS()
++	f := k8sdeps.NewFactory()
++	var out bytes.Buffer
++	cmd := build.NewCmdBuild(&out, fSys, f.ResmapF, f.TransformerF)
++	cmd.SetArgs([]string{v.Path})
++	// we want to silence usage, error output, and any future output from cobra
++	// we will get error output as a golang error from execute
++	cmd.SetOutput(ioutil.Discard)
++	_, err := cmd.ExecuteC()
++	if err != nil {
++		return err
++	}
++	v.StreamVisitor.Reader = bytes.NewReader(out.Bytes())
++	return v.StreamVisitor.Visit(fn)
++}
++
++func NewKustomizationVisitor(mapper *mapper, path string, schema ContentValidator) *KustomizationVisitor {
++	return &KustomizationVisitor{
++		Path:          path,
++		StreamVisitor: NewStreamVisitor(nil, mapper, path, schema),
++	}
++}
++
+ // StreamVisitor reads objects from an io.Reader and walks them. A stream visitor can only be
+ // visited once.
+ // TODO: depends on objects being in JSON format before being passed to decode - need to implement

build/vendor_kustomize.sh

@@ -0,0 +1,118 @@
+#!/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
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )"
+
+# vendor_kustomize.sh creates the change in kubernetes repo for vendoring kustomize
+
+function setUpWorkspace {
+  KPATH=~/kustomize_vendor
+  mkdir $KPATH
+  GOPATH=$KPATH
+}
+
+function cloneK8s {
+  mkdir -p $KPATH/src/k8s.io
+  cd $KPATH/src/k8s.io
+
+  git clone git@github.com:kubernetes/kubernetes.git
+}
+
+function godepRestore {
+  cd $KPATH/src/k8s.io/kubernetes
+
+  # restore dependencies
+  hack/run-in-gopath.sh hack/godep-restore.sh
+}
+
+function getKustomizeDeps {
+  # get Kustomize and Kustomize dependencies
+  hack/run-in-gopath.sh godep get sigs.k8s.io/kustomize/pkg/commands
+  hack/run-in-gopath.sh godep get github.com/bgentry/go-netrc/netrc
+  hack/run-in-gopath.sh godep get github.com/hashicorp/go-cleanhttp
+  hack/run-in-gopath.sh godep get github.com/hashicorp/go-getter
+  hack/run-in-gopath.sh godep get github.com/hashicorp/go-safetemp
+  hack/run-in-gopath.sh godep get github.com/hashicorp/go-version
+
+  # The hashes below passed bin/pre-commit.sh with kustomize HEAD at time of merger.
+  DEPS=(
+  "hashicorp/go-getter     4bda8fa99001c61db3cad96b421d4c12a81f256d"
+  "hashicorp/go-cleanhttp  d5fe4b57a186c716b0e00b8c301cbd9b4182694d"
+  "hashicorp/go-safetemp   b1a1dbde6fdc11e3ae79efd9039009e22d4ae240"
+  "hashicorp/go-version    270f2f71b1ee587f3b609f00f422b76a6b28f348"
+  "bgentry/go-netrc        9fd32a8b3d3d3f9d43c341bfe098430e07609480"
+  "mitchellh/go-homedir    58046073cbffe2f25d425fe1331102f55cf719de"
+  "mitchellh/go-testing-interface  a61a99592b77c9ba629d254a693acffaeb4b7e28"
+  "ulikunitz/xz            v0.5.4"
+  )
+
+  function foo {
+    cd $KPATH/src/k8s.io/kubernetes/_output/local/go/src/github.com/$1
+    git checkout $2
+  }
+  for i in "${DEPS[@]}"; do
+    foo $i
+  done
+}
+
+function updateK8s {
+  # Copy k8sdeps from Kustomize to cli-runtime in staging
+  mkdir -p $KPATH/src/k8s.io/kubernetes/staging/src/k8s.io/cli-runtime/pkg/kustomize
+  cp -r $KPATH/src/k8s.io/kubernetes/_output/local/go/src/sigs.k8s.io/kustomize/k8sdeps \
+    $KPATH/src/k8s.io/kubernetes/staging/src/k8s.io/cli-runtime/pkg/kustomize/k8sdeps
+
+  # Change import path of k8sdeps
+  find $KPATH/src/k8s.io/kubernetes/staging/src/k8s.io/cli-runtime/pkg/kustomize/k8sdeps \
+    -type f -name "*.go" | \
+    xargs sed -i \
+    's!sigs.k8s.io/kustomize/k8sdeps!k8s.io/cli-runtime/pkg/kustomize/k8sdeps!'
+
+
+  # Add kustomize command to kubectl
+  cp $DIR/vendor_kustomize.diff $KPATH/vendor_kustomize.diff
+
+  cd $GOPATH/src/k8s.io/kubernetes
+  git apply --ignore-space-change --ignore-whitespace $KPATH/vendor_kustomize.diff
+}
+
+function godepSave {
+  # Save all dependencies into k8s.io/kubernetes/vendor by running
+  # hack/godep-save.sh
+  hack/run-in-gopath.sh  hack/godep-save.sh
+}
+
+function verify {
+  # make sure in k8s.io/kubernetes/vendor/sigs.k8s.io/kustomize
+  # there is no internal package
+  test 0 == $(ls $KPATH/src/k8s.io/kubernetes/vendor/sigs.k8s.io/kustomize | grep “internal” | wc -l)
+
+  # Make sure it compiles.
+  test 0 == $(bazel build cmd/kubectl:kubectl)
+
+  # next step, open a PR
+  echo "The change for vendoring kustomize is ready in $GOPATH/src/k8s.io/kubernetes.\n Next step, open a PR for it.\n"
+}
+
+setUpWorkspace
+cloneK8s
+godepRestore
+getKustomizeDeps
+updateK8s
+godepSave
+verify

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/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/pkg/pgmconfig"
+	"sigs.k8s.io/kustomize/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)

demos/README.md

@@ -1,24 +0,0 @@
-# Demos
-
-These demos assume that `kustomize` is on your `$PATH`.
-They are covered by pre-submit tests.
-
- * [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.
-
- * [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) -
-   Mixing configuration data from different owners
-   (e.g. devops/SRE and developers).
-
- * [breakfast](breakfast.md) - Customize breakfast for
-   Alice and Bob.

demos/configGeneration.md

@@ -1,298 +0,0 @@
-[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
-  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 -->
-```
-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
-bases:
-- ../../base
-namePrefix: dev-
-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-b5m75ck895`:
-
- * `"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.
-
-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
-bases:
-- ../../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 cluser using:
-
-> ```
-> kustomize build $OVERLAYS/production | kubectl apply -f -
-> ```

demos/helloWorld/README.md

@@ -1,430 +0,0 @@
-[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
-
-Steps:
-
- 1. Clone an existing configuration as a [base].
- 1. Customize it.
- 1. Create two different [overlays] (_staging_ and _production_)
-    from the customized base.
- 1. Run kustomize and kubectl to deploy staging and production.
-
-First define a place to work:
-
-<!-- @makeWorkplace @test -->
-```
-DEMO_HOME=$(mktemp -d)
-```
-
-Alternatively, use
-
-> ```
-> DEMO_HOME=~/hello
-> ```
-
-## Establish the base
-
-Let's run the [hello] service.
-
-To use [overlays] to create [variants], we must
-first establish a common [base].
-
-To keep this document shorter, the base resources are
-off in a supplemental data directory rather than
-declared here as HERE documents.  Download them:
-
-<!-- @downloadBase @test -->
-```
-BASE=$DEMO_HOME/base
-mkdir -p $BASE
-
-curl -s -o "$BASE/#1.yaml" "https://raw.githubusercontent.com\
-/kubernetes-sigs/kustomize\
-/master/demos/helloWorld\
-/{configMap,deployment,kustomization,service}.yaml"
-```
-
-Look at the directory:
-
-<!-- @runTree @test -->
-```
-tree $DEMO_HOME
-```
-
-Expect something like:
-
-> ```
-> /tmp/tmp.IyYQQlHaJP
-> └── base
->     ├── configMap.yaml
->     ├── deployment.yaml
->     ├── kustomization.yaml
->     └── service.yaml
-> ```
-
-
-One could immediately apply these resources to a
-cluster:
-
-> ```
-> kubectl apply -f $DEMO_HOME/base
-> ```
-
-to instantiate the _hello_ service.  `kubectl`
-would only recognize the resource files.
-
-### The Base Kustomization
-
-The `base` directory has a [kustomization] file:
-
-<!-- @showKustomization @test -->
-```
-more $BASE/kustomization.yaml
-```
-
-Optionally, run `kustomize` on the base to emit
-customized resources to `stdout`:
-
-<!-- @buildBase @test -->
-```
-kustomize build $BASE
-```
-
-### Customize the base
-
-A first customization step could be to change the _app
-label_ applied to all resources:
-
-<!-- @addLabel @test -->
-```
-sed -i 's/app: hello/app: my-hello/' \
-    $BASE/kustomization.yaml
-```
-
-See the effect:
-<!-- @checkLabel @test -->
-```
-kustomize build $BASE | grep -C 3 app:
-```
-
-## Create Overlays
-
-Create a _staging_ and _production_ [overlay]:
-
- * _Staging_ enables a risky feature not enabled in production.
- * _Production_ has a higher replica count.
- * Web server greetings from these cluster
-   [variants] will differ from each other.
-
-<!-- @overlayDirectories @test -->
-```
-OVERLAYS=$DEMO_HOME/overlays
-mkdir -p $OVERLAYS/staging
-mkdir -p $OVERLAYS/production
-```
-
-#### Staging Kustomization
-
-In the `staging` directory, make a kustomization
-defining a new name prefix, and some different labels.
-
-<!-- @makeStagingKustomization @test -->
-```
-cat <<'EOF' >$OVERLAYS/staging/kustomization.yaml
-namePrefix: staging-
-commonLabels:
-  variant: staging
-  org: acmeCorporation
-commonAnnotations:
-  note: Hello, I am staging!
-bases:
-- ../../base
-patches:
-- map.yaml
-EOF
-```
-
-#### Staging Patch
-
-Add a configMap customization to change the server
-greeting from _Good Morning!_ to _Have a pineapple!_
-
-Also, enable the _risky_ flag.
-
-<!-- @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
-
-In the production directory, make a kustomization
-with a different name prefix and labels.
-
-<!-- @makeProductionKustomization @test -->
-```
-cat <<EOF >$OVERLAYS/production/kustomization.yaml
-namePrefix: production-
-commonLabels:
-  variant: production
-  org: acmeCorporation
-commonAnnotations:
-  note: Hello, I am production!
-bases:
-- ../../base
-patches:
-- deployment.yaml
-EOF
-```
-
-
-#### Production Patch
-
-Make a production patch that increases the replica
-count (because production takes more traffic).
-
-<!-- @productionDeployment @test -->
-```
-cat <<EOF >$OVERLAYS/production/deployment.yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: the-deployment
-spec:
-  replicas: 10
-EOF
-```
-
-## Compare overlays
-
-
-`DEMO_HOME` now contains:
-
- - a _base_ directory - a slightly customized clone
-   of the original configuration, and
-
- - an _overlays_ directory, containing the kustomizations
-   and patches required to create distinct _staging_
-   and _production_ [variants] in a cluster.
-
-Review the directory structure and differences:
-
-<!-- @listFiles @test -->
-```
-tree $DEMO_HOME
-```
-
-Expecting something like:
-
-> ```
-> /tmp/tmp.IyYQQlHaJP1
-> ├── base
-> │   ├── configMap.yaml
-> │   ├── deployment.yaml
-> │   ├── kustomization.yaml
-> │   └── service.yaml
-> └── overlays
->     ├── production
->     │   ├── deployment.yaml
->     │   └── kustomization.yaml
->     └── staging
->         ├── kustomization.yaml
->         └── map.yaml
-> ```
-
-Compare the output directly
-to see how _staging_ and _production_ differ:
-
-<!-- @compareOutput -->
-```
-diff \
-  <(kustomize build $OVERLAYS/staging) \
-  <(kustomize build $OVERLAYS/production) |\
-  more
-```
-
-The first part of the difference output should look
-something like
-
-> ```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)
-> ```
-
-
-## Deploy
-
-The individual resource sets are:
-
-<!-- @buildStaging @test -->
-```
-kustomize build $OVERLAYS/staging
-```
-
-<!-- @buildProduction @test -->
-```
-kustomize build $OVERLAYS/production
-```
-
-To deploy, pipe the above commands to kubectl apply:
-
-> ```
-> kustomize build $OVERLAYS/staging |\
->     kubectl apply -f -
-> ```
-
-> ```
-> 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
-```
-
-Run kustomize again to see the new 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)
-```
-
-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.

demos/helloWorld/kustomization.yaml

@@ -1,9 +0,0 @@
-# Example configuration for the webserver
-# at https://github.com/monopole/hello
-commonLabels:
-  app: hello
-
-resources:
-- deployment.yaml
-- configMap.yaml
-- service.yaml

demos/ldap/README.md

@@ -1,281 +0,0 @@
-[base]: ../../docs/glossary.md#base
-[gitops]: ../../docs/glossary.md#gitops
-[kustomization]: ../../docs/glossary.md#kustomization
-[overlay]: ../../docs/glossary.md#overlay
-[overlays]: ../../docs/glossary.md#overlay
-[variant]: ../../docs/glossary.md#variant
-[variants]: ../../docs/glossary.md#variant
-
-# Demo: LDAP with variants
-
-Steps:
-
- 1. Clone an existing configuration as a [base].
- 1. Customize it.
- 1. Create two different [overlays] (_staging_ and _production_)
-    from the customized base.
- 1. Run kustomize and kubectl to deploy staging and production.
-
-First define a place to work:
-
-<!-- @makeWorkplace @test -->
-```
-DEMO_HOME=$(mktemp -d)
-```
-
-Alternatively, use
-
-> ```
-> DEMO_HOME=~/ldap
-> ```
-
-## Establish the base
-
-To use [overlays] to create [variants], we must
-first establish a common [base].
-
-To keep this document shorter, the base resources are
-off in a supplemental data directory rather than
-declared here as HERE documents.  Download them:
-
-<!-- @downloadBase @test -->
-```
-BASE=$DEMO_HOME/base
-mkdir -p $BASE
-
-CONTENT="https://raw.githubusercontent.com\
-/kubernetes-sigs/kustomize\
-/master/demos/ldap"
-
-curl -s -o "$BASE/#1" "$CONTENT/base\
-/{deployment.yaml,kustomization.yaml,service.yaml,env.startup.txt}"
-```
-
-Look at the directory:
-
-<!-- @runTree @test -->
-```
-tree $DEMO_HOME
-```
-
-Expect something like:
-
-> ```
-> /tmp/tmp.IyYQQlHaJP
-> └── base
->     ├── deployment.yaml
->     ├── env.startup.txt
->     ├── kustomization.yaml
->     └── service.yaml
-> ```
-
-
-One could immediately apply these resources to a
-cluster:
-
-> ```
-> kubectl apply -f $DEMO_HOME/base
-> ```
-
-to instantiate the _ldap_ service.  `kubectl`
-would only recognize the resource files.
-
-### The Base Kustomization
-
-The `base` directory has a [kustomization] file:
-
-<!-- @showKustomization @test -->
-```
-more $BASE/kustomization.yaml
-```
-
-Optionally, run `kustomize` on the base to emit
-customized resources to `stdout`:
-
-<!-- @buildBase @test -->
-```
-kustomize build $BASE
-```
-
-### Customize the base
-
-A first customization step could be to set the name prefix to all resources:
-
-<!-- @namePrefix @test -->
-```
-cd $BASE
-kustomize edit set nameprefix "my-"
-```
-
-See the effect:
-<!-- @checkNameprefix @test -->
-```
-kustomize build $BASE | grep -C 3 "my-"
-```
-
-## Create Overlays
-
-Create a _staging_ and _production_ [overlay]:
-
- * _Staging_ adds a configMap.
- * _Production_ has a higher replica count and a persistent disk.
- * [variants] will differ from each other.
-
-<!-- @overlayDirectories @test -->
-```
-OVERLAYS=$DEMO_HOME/overlays
-mkdir -p $OVERLAYS/staging
-mkdir -p $OVERLAYS/production
-```
-
-#### Staging Kustomization
-
-Download the staging customization and patch.
-
-<!-- @downloadStagingKustomization @test -->
-```
-curl -s -o "$OVERLAYS/staging/#1" "$CONTENT/overlays/staging\
-/{config.env,deployment.yaml,kustomization.yaml}"
-```
-
-The staging customization adds a configMap.
-> ```cat $OVERLAYS/staging/kustomization.yaml
-> (...truncated)
-> configMapGenerator:
->   - name: env-config
->     files:
->       - config.env
-> ```
-as well as 2 replica
-> ```cat $OVERLAYS/staging/deployment.yaml
-> apiVersion: apps/v1beta2
-> kind: Deployment
-> metadata:
->   name: ldap
-> spec:
->   replicas: 2
-> ```
-
-#### Production Kustomization
-
-Download the production customization and patch.
-<!-- @downloadProductionKustomization @test -->
-```
-curl -s -o "$OVERLAYS/production/#1" "$CONTENT/overlays/production\
-/{deployment.yaml,kustomization.yaml}"
-```
-
-The production customization adds 6 replica as well as a consistent disk.
-> ```cat $OVERLAYS/production/deployment.yaml
-> apiVersion: apps/v1beta2
-> kind: Deployment
-> metadata:
->   name: ldap
-> spec:
->   replicas: 6
->   template:
->     spec:
->       volumes:
->         - name: ldap-data
->           emptyDir: null
->           gcePersistentDisk:
->             pdName: ldap-persistent-storage
-> ```
-
-## Compare overlays
-
-
-`DEMO_HOME` now contains:
-
- - a _base_ directory - a slightly customized clone
-   of the original configuration, and
-
- - an _overlays_ directory, containing the kustomizations
-   and patches required to create distinct _staging_
-   and _production_ [variants] in a cluster.
-
-Review the directory structure and differences:
-
-<!-- @listFiles @test -->
-```
-tree $DEMO_HOME
-```
-
-Expecting something like:
-
-> ```
-> /tmp/tmp.IyYQQlHaJP1
-> ├── base
-> │   ├── deployment.yaml
-> │   ├── env.startup.txt
-> │   ├── kustomization.yaml
-> │   └── service.yaml
-> └── overlays
->     ├── production
->     │   ├── deployment.yaml
->     │   └── kustomization.yaml
->     └── staging
->         ├── config.env
->         ├── deployment.yaml
->         └── kustomization.yaml
-> ```
-
-Compare the output directly
-to see how _staging_ and _production_ differ:
-
-<!-- @compareOutput -->
-```
-diff \
-  <(kustomize build $OVERLAYS/staging) \
-  <(kustomize build $OVERLAYS/production) |\
-  more
-```
-
-The difference output should look something like
-
-> ```diff
-> (...truncated)
-> <   name: staging-my-ldap-configmap-kftftt474h
-> ---
-> >   name: production-my-ldap-configmap-k27f7hkg4f
-> 85c75
-> <   name: staging-my-ldap-service
-> ---
-> >   name: production-my-ldap-service
-> 97c87
-> <   name: staging-my-ldap
-> ---
-> >   name: production-my-ldap
-> 99c89
-> <   replicas: 2
-> ---
-> >   replicas: 6
-> (...truncated)
-> ```
-
-
-## Deploy
-
-The individual resource sets are:
-
-<!-- @buildStaging @test -->
-```
-kustomize build $OVERLAYS/staging
-```
-
-<!-- @buildProduction @test -->
-```
-kustomize build $OVERLAYS/production
-```
-
-To deploy, pipe the above commands to kubectl apply:
-
-> ```
-> kustomize build $OVERLAYS/staging |\
->     kubectl apply -f -
-> ```
-
-> ```
-> kustomize build $OVERLAYS/production |\
->    kubectl apply -f -
-> ```

demos/ldap/overlays/production/kustomization.yaml

@@ -1,5 +0,0 @@
-bases:
-  - ../../base
-patches:
-  - deployment.yaml
-namePrefix: production-

demos/ldap/overlays/staging/kustomization.yaml

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

demos/mySql/README.md

@@ -1,203 +0,0 @@
-# Demo: MySql
-
-This example takes some off-the-shelf k8s resources
-designed for MySQL, and customizes them to suit a
-production scenario.
-
-In the production environment we want:
-
-- MySQL resource names to be prefixed by 'prod-'.
-- MySQL resources to have 'env: prod' labels.
-- MySQL to use persistent disk for storing data.
-
-First make a place to work:
-<!-- @makeDemoHome @test -->
-```
-DEMO_HOME=$(mktemp -d)
-```
-
-### Download resources
-
-To keep this document shorter, the base resources
-needed to run MySql on a k8s cluster are off in a
-supplemental data directory rather than declared here
-as HERE documents.
-
-Download them:
-
-<!-- @downloadResources @test -->
-```
-curl -s  -o "$DEMO_HOME/#1.yaml" "https://raw.githubusercontent.com\
-/kubernetes-sigs/kustomize\
-/master/demos/mySql\
-/{deployment,secret,service}.yaml"
-```
-
-### Initialize kustomization.yaml
-
-The `kustomize` program gets its instructions from
-a file called `kustomization.yaml`.
-
-Start this file:
-
-<!-- @kustomizeYaml @test -->
-```
-touch $DEMO_HOME/kustomization.yaml
-```
-
-### Add the resources
-
-<!-- @addResources @test -->
-```
-cd $DEMO_HOME
-
-kustomize edit add resource secret.yaml
-kustomize edit add resource service.yaml
-kustomize edit add resource deployment.yaml
-
-cat kustomization.yaml
-```
-
-`kustomization.yaml`'s resources section should contain:
-
-> ```
-> resources:
-> - secret.yaml
-> - service.yaml
-> - deployment.yaml
-> ```
-
-### Name Customization
-
-Arrange for the MySQL resources to begin with prefix
-_prod-_ (since they are meant for the _production_
-environment):
-
-<!-- @customizeLabel @test -->
-```
-cd $DEMO_HOME
-
-kustomize edit set nameprefix 'prod-'
-
-cat kustomization.yaml
-```
-
-`kustomization.yaml` should have updated value of namePrefix field:
-
-> ```
-> namePrefix: prod-
-> ```
-
-This `namePrefix` directive adds _prod-_ to all
-resource names.
-
-<!-- @genNamePrefixConfig @test -->
-```
-kustomize build $DEMO_HOME
-```
-
-The output should contain:
-
-> ```
-> apiVersion: v1
-> data:
->   password: YWRtaW4=
-> kind: Secret
-> metadata:
->   ....
->   name: prod-mysql-pass-d2gtcm2t2k
-> ---
-> apiVersion: v1
-> kind: Service
-> metadata:
->   ....
->   name: prod-mysql
-> spec:
->   ....
-> ---
-> apiVersion: apps/v1beta2
-> kind: Deployment
-> metadata:
->   ....
->   name: prod-mysql
-> spec:
->   selector:
->     ....
-> ```
-
-### Label Customization
-
-We want resources in production environment to have
-certain labels so that we can query them by label
-selector.
-
-`kustomize` does not have `edit set label` command to add
-a label, but one can always edit `kustomization.yaml` directly:
-
-<!-- @customizeLabels @test -->
-```
-sed -i 's/app: helloworld/app: prod/' \
-    $DEMO_HOME/kustomization.yaml
-```
-
-At this point, running `kustomize build` will
-generate MySQL configs with name-prefix 'prod-' and
-labels `env:prod`.
-
-### Storage customization
-
-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
-resources.
-
-<!-- @createPatchFile @test -->
-```
-cat <<'EOF' > $DEMO_HOME/persistent-disk.yaml
-apiVersion: apps/v1beta2 # for versions before 1.9.0 use apps/v1beta2
-kind: Deployment
-metadata:
-  name: mysql
-spec:
-  template:
-    spec:
-      volumes:
-      - name: mysql-persistent-storage
-        emptyDir: null
-        gcePersistentDisk:
-          pdName: mysql-persistent-storage
-EOF
-```
-
-Add the patch file to `kustomization.yaml`:
-
-<!-- @specifyPatch @test -->
-```
-cat <<'EOF' >> $DEMO_HOME/kustomization.yaml
-patches:
-- persistent-disk.yaml
-EOF
-```
-
-Lets break this down:
-
-- In the first step, we created a YAML file named
-  `persistent-disk.yaml` to patch the resource defined
-  in deployment.yaml
-
-- Then we added `persistent-disk.yaml` to list of
-  `patches` in `kustomization.yaml`. `kustomize build`
-  will apply this patch to the deployment resource with
-  the name `mysql` as defined in the patch.
-
-
-The output of the following command can now be applied
-to the cluster (i.e. piped to `kubectl apply`) to
-create the production environment.
-
-<!-- @finalInflation @test -->
-```
-kustomize build $DEMO_HOME  # | kubectl apply -f -
-```

demos/mySql/secret.yaml

@@ -1,9 +0,0 @@
-apiVersion: v1
-kind: Secret
-metadata:
-  creationTimestamp: null
-  name: mysql-pass-d2gtcm2t2k
-type: Opaque
-data:
-  # Default password is "admin".
-  password: YWRtaW4=

demos/springboot/README.md

@@ -1,307 +0,0 @@
-# Demo: SpringBoot
-
-In this tutorial, you will learn - how to use `kustomize` to customize a basic Spring Boot application's
-k8s configuration for production use cases.
-
-In the production environment we want to customize the following:
-
-- add application specific configuration for this Spring Boot application
-- configure prod DB access configuration
-- resource names to be prefixed by 'prod-'.
-- resources to have 'env: prod' labels.
-- JVM memory to be properly set.
-- health check and readiness check.
-
-First make a place to work:
-<!-- @makeDemoHome @test -->
-```
-DEMO_HOME=$(mktemp -d)
-```
-
-### Download resources
-
-To keep this document shorter, the base resources
-needed to run springboot on a k8s cluster are off in a
-supplemental data directory rather than declared here
-as HERE documents.
-
-Download them:
-
-<!-- @downloadResources @test -->
-```
-CONTENT="https://raw.githubusercontent.com\
-/kubernetes-sigs/kustomize\
-/master/demos/springboot"
-
-curl -s -o "$DEMO_HOME/#1.yaml" \
-  "$CONTENT/base/{deployment,service}.yaml"
-```
-
-### Initialize kustomization.yaml
-
-The `kustomize` program gets its instructions from
-a file called `kustomization.yaml`.
-
-Start this file:
-
-<!-- @kustomizeYaml @test -->
-```
-touch $DEMO_HOME/kustomization.yaml
-```
-
-### Add the resources
-
-<!-- @addResources @test -->
-```
-cd $DEMO_HOME
-
-kustomize edit add resource service.yaml
-kustomize edit add resource deployment.yaml
-
-cat kustomization.yaml
-```
-
-`kustomization.yaml`'s resources section should contain:
-
-> ```
-> resources:
-> - service.yaml
-> - deployment.yaml
-> ```
-
-### Add configMap generator
-
-<!-- @addConfigMap @test -->
-```
-echo "app.name=Kustomize Demo" >$DEMO_HOME/application.properties
-
-kustomize edit add configmap demo-configmap \
-  --from-file application.properties
-
-cat kustomization.yaml
-```
-
-`kustomization.yaml`'s configMapGenerator section should contain:
-
-> ```
-> configMapGenerator:
-> - files:
->   - application.properties
->   name: demo-configmap
-> ```
-
-### Customize configMap
-
-We want to add database credentials for the prod environment. In general, these credentials can be put into the file `application.properties`.
-However, for some cases, we want to keep the credentials in a different file and keep application specific configs in `application.properties`.
- With this clear separation, the credentials and application specific things can be managed and maintained flexibly by different teams.
-For example, application developers only tune the application configs in `application.properties` and operation teams or SREs
-only care about the credentials.
-
-For Spring Boot application, we can set an active profile through the environment variable `spring.profiles.active`. Then
-the application will pick up an extra `application-<profile>.properties` file. With this, we can customize the configMap in two
-steps. Add an environment variable through the patch and add a file to the configMap.
-
-<!-- @customizeConfigMap @test -->
-```
-cat <<EOF >$DEMO_HOME/patch.yaml
-apiVersion: apps/v1beta2
-kind: Deployment
-metadata:
-  name: sbdemo
-spec:
-  template:
-    spec:
-      containers:
-        - name: sbdemo
-          env:
-          - name: spring.profiles.active
-            value: prod
-EOF
-
-kustomize edit add patch patch.yaml
-
-cat <<EOF >$DEMO_HOME/application-prod.properties
-spring.jpa.hibernate.ddl-auto=update
-spring.datasource.url=jdbc:mysql://<prod_database_host>:3306/db_example
-spring.datasource.username=root
-spring.datasource.password=admin
-EOF
-
-kustomize edit add configmap \
-  demo-configmap --from-file application-prod.properties
-
-cat kustomization.yaml
-```
-
-`kustomization.yaml`'s configMapGenerator section should contain:
-> ```
-> configMapGenerator:
-> - files:
->   - application.properties
->   - application-prod.properties
->   name: demo-configmap
-> ```
-
-### Name Customization
-
-Arrange for the resources to begin with prefix
-_prod-_ (since they are meant for the _production_
-environment):
-
-<!-- @customizeLabel @test -->
-```
-cd $DEMO_HOME
-kustomize edit set nameprefix 'prod-'
-```
-
-`kustomization.yaml` should have updated value of namePrefix field:
-
-> ```
-> namePrefix: prod-
-> ```
-
-This `namePrefix` directive adds _prod-_ to all
-resource names, as can be seen by building the
-resources:
-
-<!-- @build1 @test -->
-```
-kustomize build $DEMO_HOME | grep prod-
-```
-
-### Label Customization
-
-We want resources in production environment to have
-certain labels so that we can query them by label
-selector.
-
-`kustomize` does not have `edit set label` command to
-add a label, but one can always edit
-`kustomization.yaml` directly:
-
-<!-- @customizeLabels @test -->
-```
-cat <<EOF >>$DEMO_HOME/kustomization.yaml
-commonLabels:
-  env: prod
-EOF
-```
-
-Confirm that the resources now all have names prefixed
-by `prod-` and the label tuple `env:prod`:
-
-<!-- @build2 @test -->
-```
-kustomize build $DEMO_HOME | grep -C 3 env
-```
-
-### Download Patch for JVM memory
-
-When a Spring Boot application is deployed in a k8s cluster, the JVM is running inside a container. We want to set memory limit for the container and make sure
-the JVM is aware of that limit. In K8s deployment, we can set the resource limits for containers and inject these limits to
-some environment variables by downward API. When the container starts to run, it can pick up the environment variables and
-set JVM options accordingly.
-
-Download the patch `memorylimit_patch.yaml`. It contains the memory limits setup.
-
-<!-- @downloadPatch @test -->
-```
-curl -s  -o "$DEMO_HOME/#1.yaml" \
-  "$CONTENT/overlays/production/{memorylimit_patch}.yaml"
-
-cat $DEMO_HOME/memorylimit_patch.yaml
-```
-
-The output contains
-
-> ```
-> apiVersion: apps/v1beta2
-> kind: Deployment
-> metadata:
->   name: sbdemo
-> spec:
->   template:
->     spec:
->       containers:
->         - name: sbdemo
->           resources:
->             limits:
->               memory: 1250Mi
->             requests:
->               memory: 1250Mi
->           env:
->           - name: MEM_TOTAL_MB
->             valueFrom:
->               resourceFieldRef:
->                 resource: limits.memory
-> ```
-
-### Download Patch for health check
-We also want to add liveness check and readiness check in the production environment. Spring Boot application
-has end points such as `/actuator/health` for this. We can customize the k8s deployment resource to talk to Spring Boot end point.
-
-Download the patch `healthcheck_patch.yaml`. It contains the liveness probes and readyness probes.
-
-<!-- @downloadPatch @test -->
-```
-curl -s  -o "$DEMO_HOME/#1.yaml" \
-  "$CONTENT/overlays/production/{healthcheck_patch}.yaml"
-
-cat $DEMO_HOME/healthcheck_patch.yaml
-```
-
-The output contains
-
-> ```
-> apiVersion: apps/v1beta2
-> kind: Deployment
-> metadata:
->   name: sbdemo
-> spec:
->   template:
->     spec:
->       containers:
->         - name: sbdemo
->           livenessProbe:
->             httpGet:
->               path: /actuator/health
->               port: 8080
->             initialDelaySeconds: 10
->             periodSeconds: 3
->           readinessProbe:
->             initialDelaySeconds: 20
->             periodSeconds: 10
->             httpGet:
->               path: /actuator/info
->               port: 8080
-> ```
-
-### Add patches
-
-Add these patches to the kustomization:
-
-<!-- @addPatch @test -->
-```
-cd $DEMO_HOME
-kustomize edit add patch memorylimit_patch.yaml
-kustomize edit add patch healthcheck_patch.yaml
-```
-
-`kustomization.yaml` should have patches field:
-
-> ```
-> patches:
-> - patch.yaml
-> - memorylimit_patch.yaml
-> - healthcheck_patch.yaml
-> ```
-
-The output of the following command can now be applied
-to the cluster (i.e. piped to `kubectl apply`) to
-create the production environment.
-
-<!-- @finalBuild @test -->
-```
-kustomize build $DEMO_HOME  # | kubectl apply -f -
-```

demos/springboot/overlays/production/kustomization.yaml

@@ -1,7 +0,0 @@
-bases:
-- ../../base
-patches:
-- patch.yaml
-- healthcheck_patch.yaml
-- memorylimit_patch.yaml
-namePrefix: production-

demos/springboot/overlays/production/patch.yaml

@@ -1,13 +0,0 @@
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: demo-configmap
-data:
-  application.properties: |
-    app.name=Staging Kinflate Demo
-    spring.jpa.hibernate.ddl-auto=update
-    spring.datasource.url=jdbc:mysql://<production_db_ip>:3306/db_example
-    spring.datasource.username=root
-    spring.datasource.password=admin
-    server.tomcat.max-threads=20
-    server.tomcat.min-spare-threads=3

demos/springboot/overlays/staging/kustomization.yaml

@@ -1,11 +0,0 @@
-bases:
-- ../../base
-namePrefix: staging-
-configMapGenerator:
-- name: demo-configmap
-  behavior: merge
-  files:
-    - application.properties
-  literals:
-    - foo=bar
-  env: staging.env

docs/FAQ.md

@@ -0,0 +1,39 @@
+# 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.
+
+At the moment (in v2.0.3), however, there's no
+(released) analogous way to share patch files and other
+transformer configuration data between kustomizations.
+
+As a stop-gap until we add base-like behavior for
+transformers, we've added a flag to disable the check:
+
+
+```
+kustomize build --load_restrictor none $target
+```
+
+This flag is not in v2.0.3, but is available from head
+(`go install sigs.k8s.io/kustomize`).

docs/INSTALL.md

@@ -0,0 +1,47 @@
+[release page]: https://github.com/kubernetes-sigs/kustomize/releases
+[Go]: https://golang.org
+
+## Installation
+
+For linux, macOs and Windows,
+download a binary from the
+[release page].
+
+Or try this command:
+```
+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.12 or higher:
+
+<!-- @installkustomize @test -->
+```
+go install sigs.k8s.io/kustomize/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,50 @@
+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.md) - 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
+
+ * [2.1](v_2.1.0.md) - Date TBD, target late May 2019
+
+ * [2.0](v_2.0.0.md) - Mar 2019.
+   kustomize [v2.0.3] is available in [kubectl v1.14][kubectl].
+
+ * [1.0](v_1.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,46 @@
+# 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].
+
+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/fields.md

@@ -0,0 +1,504 @@
+# 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.md) 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.md) 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.md) 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,27 +76,20 @@ 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.
 
-A base is usable in isolation, i.e. one should
-be able to [apply] a base to a cluster directly.
-
 For simple [gitops] management, a base configuration
 could be the _sole content of a git repository
 dedicated to that purpose_.  Same with [overlays].
 Changes in a repo could generate a build, test and
 deploy cycle.
 
-Some of the demos for [kustomize] will break from this
-idiom and store all demo config files in directories
-_next_ to the `kustomize` code so that the code and
-demos can be more easily maintained by the same group
-of people.
 
 ## bespoke configuration
 
@@ -100,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
@@ -127,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
 
@@ -162,21 +263,21 @@ It's often abbreviated as _k8s_.
 
 An object, expressed in a YAML or JSON file, with the
 [fields required] by kubernetes.  Basically just a
-`kind` field to identify the type, a `metadata/name`
-field to identify the variant, and an `apiVersion`
-field to identify the version (if there's more than one
-version).
+_kind_ field to identify the type, a _metadata/name_
+field to identify the particular instance, and an
+_apiVersion_ field to identify the version (if there's
+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].
 
@@ -206,23 +307,27 @@ 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 supports the typical notion of a
-_development_, _QA_, _staging_ and _production_
-environment variants.
+An overlay may act as a base to another overlay.
 
-The configuration of these environments is specified in
-individual overlays (one per environment) that all
-refer to a common base that holds common configuration.
-One configures the cluster like this:
+Overlays make the most sense when there is _more than
+one_, because they create different [variants] of a
+common base - e.g.  _development_, _QA_, _staging_ and
+_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.
+
+One configures a cluster like this:
 
 > ```
 >  kustomize build someapp/overlays/staging |\
@@ -232,10 +337,10 @@ One configures the cluster like this:
 >      kubectl apply -f -
 > ```
 
-Usage of the base is implicit (the overlay's kustomization
-points to the base).
+Usage of the base is implicit - the overlay's
+kustomization points to the base.
 
-An overlay may act as a base to another overlay.
+See also [root].
 
 ## package
 
@@ -246,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.md).
 
 ## 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.
+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
 
@@ -289,30 +441,34 @@ 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 file called
-`kustomization.yaml` (i.e. 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
 
 A _variant_ is the outcome, in a cluster, of applying
 an [overlay] to a [base].
 
-> E.g., a _staging_ and _production_ overlay both modify some
-> common base to create distinct variants.
->
-> The _staging_ variant is the set of resources
-> exposed to quality assurance testing, or to some
-> external users who'd like to see what the next
-> version of production will look like.
->
-> The _production_ variant is the set of resources
-> exposed to production traffic, and thus may employ
-> deployments with a large number of replicas and higher
-> cpu and memory requests.
+E.g., a _staging_ and _production_ overlay both modify
+some common base to create distinct variants.
+
+The _staging_ variant is the set of resources exposed
+to quality assurance testing, or to some external users
+who'd like to see what the next version of production
+will look like.
+
+The _production_ variant is the set of resources
+exposed to production traffic, and thus may employ
+deployments with a large number of replicas and higher
+cpu and memory requests.

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: haha
+  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,115 +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.
-# ----------------------------------------------------
-
-
-# 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"
-
-# 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

docs/plugins.md

@@ -0,0 +1,348 @@
+# kustomize plugins
+
+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 that exceeds the power of the
+   builtin transformations (`namePrefix`,
+   `commonLabels`, etc.).
+
+## 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}
+> ```
+
+This is exactly like the syntax of the `resources`
+field.
+
+The value of each entry in a `resources`,
+`generators` or `transformers` list must be a
+relative path to a YAML file, or a path or URL
+to a [kustomization].
+
+[kustomization]: glossary.md#kustomization
+
+In the former case the YAML is read from disk directly,
+and in the latter case a kustomization is performed,
+and its YAML output is merged with the YAML read
+directly from files.  The net result in all three cases
+is a set of YAML objects.
+
+Each object resulting from a `generators` or
+`transformers` field 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_.
+
+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 generator 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/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 tarball (source, test, 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 is in some sense a
+generator in that it emits resources for further
+processing).
+
+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 specified order of transformers in the
+`transformers` field should be respected, as
+transformers cannot be expected to be commutative.
+
+A `kustomize build` that tries to use plugins but
+omits the flag
+
+> `--enable_alpha_plugins`
+
+will fail with a warning about plugin use.
+
+Flag use is an opt-in acknowledging the absence of
+plugin provenance.  It's meant to give pause to
+someone who blindly downloads a kustomization from
+the internet and attempts to run it, without
+realizing that it might attempt to run 3rd party
+code in plugin form.  The plugin would have to be
+installed already, but nevertheless the flag is a
+reminder.
+
+
+## Writing 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: more restrictions on plugin to allow the same exec
+> plugin to be specified in a config under 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
+> - 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
+
+[Go plugin]: https://golang.org/pkg/plugin/
+
+A [Go plugin] for kustomize looks like this:
+
+> ```
+> package main
+>
+> import (
+>	"sigs.k8s.io/kustomize/pkg/ifc"
+>	"sigs.k8s.io/kustomize/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
+
+
+#### Examples
+
+ * [secret generator] - Generate secrets from a database.
+ * [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.
+ * All the builtin plugins [here](../plugin/builtin).
+   User authored plugins are
+   on the same footing as builtin operations.
+
+A 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
+```
+
+#### Caveats
+
+Go plugins allow kustomize extensions that run
+without the cost marshalling/unmarshalling all
+resource data to/from a subprocess for each plugin
+run.
+
+[ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format
+
+Go plugins work as [defined][Go plugin], but fall
+short of common notions associated with the word
+_plugin_.  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.
+
+Exec plugins also lack provenance, but won't
+complain about compilation skew.
+
+In either case, a sensible way to share a plugin
+is as a tar file of source code, tests and
+associated data, unpackable under
+`$XDG_CONFIG_HOME/kustomize/plugin` (exactly where
+one would develop a plugin).
+
+[Go modules]: https://github.com/golang/go/wiki/Modules
+
+In the case of a Go plugin, an end user accepting
+a shared plugin must compile both kustomize and
+the plugin.  Tooling could be built to make Go
+_plugin sharing_ easier, but this requires some
+critical mass of _plugin authoring_, which in turn
+is hampered by confusion around sharing.
+[Go modules], once they are more widely adopted,
+will solve one of the biggest plugin sharing
+difficulties - ambiguous plugin vs host
+dependencies.

docs/v_1.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 2018: [DAM] authored by Brian Grant
+
+[DAM]: https://docs.google.com/document/d/1cLPGweVEYrVqQvBLJg6sxV-TrE5Rm2MNOBA_cxZP2WU

docs/v_2.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/v_2.1.0.md

@@ -0,0 +1,242 @@
+# 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.md
+[root]: glossary.md#kustomization-root
+[transformer configs]: ../examples/transformerconfigs
+[v1.0.9]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v1.0.9
+[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.0.3
+[v2.1.0]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.1.0
+[versioning policy]: versioningPolicy.md
+
+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.
+
+## 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_restrictions none $target
+```
+
+allows a `kustomization.yaml` file used in this
+build to refer to files outside its own directory
+(i.e. outside its [root]).
+
+This is an opt-in to suppress a security feature
+that denies this precise behavior.
+
+This feature should only be used to allow multiple
+overlays (e.g. prod, staging and dev) to share a
+patch file.  To share _resources_, use a relative
+path or URL to a kustomization directory in the
+`resources` directive.
+
+## 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/versioningPolicy.md

@@ -0,0 +1,219 @@
+# Versioning
+
+Running `kustomize` means one is running a
+particular version of a program, reading a
+particular version of a [kustomization] file.
+
+## Program Versioning
+
+The command `kustomize version` prints a three
+field version tag (e.g. `1.0.11`) 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.
+
+## 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]: ../build/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#resources
-[workflowBespoke]: workflowBespoke.jpg
-[workflowOts]: workflowOts.jpg
+[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/
 
 # 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
 > ```
@@ -64,10 +68,15 @@ specified in the base.
 Run kustomize, and pipe the output to [apply].
 
 > ```
-> kustomize ~/ldap/overlays/staging | kubectl apply -f -
-> kustomize ~/ldap/overlays/production | kubectl apply -f -
+> kustomize build ~/ldap/overlays/staging | kubectl apply -f -
+> 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
 
@@ -85,13 +94,13 @@ is periodically consulted for updates.
 
 The [base] directory is maintained in a repo whose
 upstream is an [OTS] configuration, in this case
-https://github.com/kinflate/ldap.
+some user's `ldap` repo:
 
 > ```
 > mkdir ~/ldap
 > git clone https://github.com/$USER/ldap ~/ldap/base
 > cd ~/ldap/base
-> git remote add upstream git@github.com:kustomize/ldap
+> git remote add upstream git@github.com:$USER/ldap
 > ```
 
 #### 3) create [overlays]
@@ -107,17 +116,25 @@ The [overlays] are siblings to each other and to the
 > mkdir -p ~/ldap/overlays/production
 > ```
 
+The user can maintain the `overlays` directory in a
+distinct repository.
 
 #### 4) bring up [variants]
 
 > ```
-> kustomize ~/ldap/overlays/staging | kubectl apply -f -
-> kustomize ~/ldap/overlays/production | kubectl apply -f -
+> kustomize build ~/ldap/overlays/staging | kubectl apply -f -
+> 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 optionally [rebase] their [base] to
+The user can periodically [rebase] their [base] to
 capture changes made in the upstream repository.
 
 > ```

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 get sigs.k8s.io/kustomize
+```

docs/zh/README.md

@@ -0,0 +1,46 @@
+[English](../README.md) | 简体中文
+
+# 文档
+
+ * [安装说明](INSTALL.md)
+
+ * [示例](../../examples) - 各种使用流程和概念的详细演示。
+
+ * [术语表](../glossary.md) - 用于消除术语歧义。
+
+ * [kustomization.yaml](kustomization.yaml) - 包含 
+ [kustomization](../glossary.md#kustomization) 所有字段的示例文件。
+
+ * [插件](../plugins.md) - 使用自定义的资源生成器和资源转换器来拓展 kustomize 功能。
+
+ * [工作流](workflows.md) - 使用定制及使用现成配置使用的一些步骤。
+
+ * [FAQ](../FAQ.md)
+
+
+## 发行说明
+
+ * [2.1](../v_2.1.0.md) - 日期待定，预计2019年5月下旬。
+
+ * [2.0](../v_2.0.0.md) - 2019年3月
+   可以在 [kubectl v1.14][kubectl] 中使用 kustomize [v2.0.3] 。
+
+ * [1.0](../v_1.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/kustomization.yaml

@@ -0,0 +1,287 @@
+# Copyright 2018 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# ----------------------------------------------------
+# Example kustomization.yaml content.
+#
+# This file declares the customization provided by
+# the kustomize program.
+#
+# Since customization is, by definition, _custom_,
+# there are no sensible default values for the fields
+# in this file.
+#
+# The field values used below are merely examples, not
+# to be copied literally.  The values won't work if
+# they happen to be references to external files that
+# don't exist.
+#
+# In practice, fields with no value should simply be
+# omitted from kustomization.yaml to reduce the content
+# visible in configuration reviews.
+# ----------------------------------------------------
+# Kustomization 的 apiVersion 和 kind 
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+# 为所有 resources 添加 namespace
+namespace: my-namespace
+
+# 该字段的值将添加在所有资源的名称之前
+# 例如 将资源名称 “wordpress” 变为 “alices-wordpress” 
+namePrefix: alices-
+
+# 该字段的值将添加在所有资源的名称后面
+# 例如 将资源名称 “wordpress” 变为 “wordpress-v2”
+# 如果资源类型为 ConfigMap 或 Secret ，则在哈希值之前附加后缀
+nameSuffix: -v2
+
+# 为所有资源和 selectors 增加 Labels
+commonLabels:
+  someName: someValue
+  owner: alice
+  app: bingo
+
+# 和 Labels 一样， 增加 Annotations
+# 为 key:value 键值对
+commonAnnotations:
+  oncallPager: 800-555-1212
+
+# 此列表中的每条记录都必须是一个存在的 YAML 资源描述文件
+# 一个 YAML 资源描述文件可以含有多个由（“---”）分隔的资源。
+# kustomize 将读取这些YAML文件中的资源，对其进行修改并
+# 发布在 kustomize 的输出中。
+#
+# 此列表中的每个条目都应解析为包含 kustomization 文件的目录，否则定制将失败
+#
+# 该条目可以是指向本地目录的相对路径
+# 也可以是指向远程仓库中的目录的 URL
+# URL 应该遵循 hashicorp/go-getter 中的 URL 格式
+# https://github.com/hashicorp/go-getter#url-format
+#
+# 此字段的存在意味着此文件（您正在阅读的文件）是 _overlay_
+# 它将进一步定制这些来自 _bases_ 文件中的配置
+#
+# 典型用例：开发，演示和生产环境
+# 这些环境大部分相同但有些关键方式存在差异（镜像标签，一些服务器参数等，与公共 base 不同的配置）
+resources:
+- some-service.yaml
+- sub-dir/some-deployment.yaml
+- ../../base
+- github.com/kubernetes-sigs/kustomize/examples/multibases?ref=v1.0.6
+- github.com/Liujingfang1/mysql
+- github.com/Liujingfang1/kustomize/examples/helloWorld?ref=test-branch
+
+# 列表中的每个条目都将创建一个 ConfigMap （它是n个 ConfigMap 的生成器）
+# 下面的示例创建了两个 ConfigMaps
+# 一个具有给定文件的名称和内容
+# 另一个包含 key/value 键值对数据
+# 每个 configMapGenerator 项都可以使用 [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
+
+# 此列表中的每个条目都会导致创建一个Secret资源（n个 secrets 的生成器）
+secretGenerator:
+- name: app-tls
+  files:
+    - secret/tls.cert
+    - secret/tls.key
+  type: "kubernetes.io/tls"
+- name: app-tls-namespaced
+  # 你可以给生成的 secret 定义一个 namespace ，默认为 ”default“
+  namespace: apps
+  files:
+    - tls.crt=catsecret/tls.cert
+    - tls.key=secret/tls.key
+  type: "kubernetes.io/tls"
+- name: env_file_secret
+  # 文件路径以 k=v 键值对的形式，每行一个键值对
+  envs:
+    - env.txt
+  type: Opaque
+
+# generatorOptions 修改所有 ConfigMapGenerator 和 SecretGenerator 的行为
+generatorOptions:
+  # 为所有生成的资源添加 labels
+  labels:
+    kustomize.generated.resources: somevalue
+  # 为所有生成的资源添加 annotations
+  annotations:
+    kustomize.generated.resource: somevalue
+  # disableNameSuffixHash 为 true 时将禁止默认的在名称后添加哈希值后缀的行为
+  disableNameSuffixHash: true
+
+# 此列表中的每个条目都应可以解析为部分或完整的资源定义文件
+#
+# 这些（也可能是部分的）资源文件中的 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 列表中的每个条目都应可以解析为 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
+
+# 此列表中的每个条目都应该是 openAPI 定义中自定义资源定义（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.json
+- crds/typeB.json
+
+# 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 等
+#
+# 变量引用，即字符串 '$(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
+
+# 修改镜像的名称、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` 修改为 `my-registry/my-postgres:v1`,
+# - 将 nginx 的 tag 从 `1.7.9` 修改为 `1.8.0`,
+# - 将 镜像名称从 `my-demo-app` 修改为 `my-app`,
+# - 将 alpine 的 tag  从 `3.7` 修改为 digest 值
+#
+# 可以在 *kustomization* 中添加以下内容：
+
+images:
+  - name: postgres
+    newName: my-registry/my-postgres
+    newTag: v1
+  - name: nginx
+    newTag: 1.8.0
+  - name: my-demo-app
+    newName: my-app
+  - name: alpine
+    digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3

docs/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

@@ -0,0 +1,72 @@
+English | [简体中文](zh/README.md)
+
+# Examples
+
+These examples assume that `kustomize` is on your `$PATH`.
+
+They are covered by [pre-commit](../travis/pre-commit.sh)
+tests, and should work with HEAD
+
+<!-- @installkustomize @test -->
+```
+go get sigs.k8s.io/kustomize/cmd/kustomize
+```
+
+Basic Usage
+
+  * [configGenerations](configGeneration.md) -
+   Rolling update when ConfigMapGenerator changes.
+   
+  * [combineConfigs](combineConfigs.md) -
+   Mixing configuration data from different owners
+   (e.g. devops/SRE and developers).
+  
+  * [generatorOptions](generatorOptions.md) -
+   Modifying behavior of all ConfigMap and Secret generators. 
+
+  * [vars](wordpress/README.md) - Injecting k8s runtime data into
+     container arguments (e.g. to point wordpress to a SQL service) by vars.
+ 
+  * [image names and tags](image.md) - Updating image names and tags without applying a patch.
+ 
+  * [remote target](remoteBuild.md) - Building a kustomization from a github URL
+ 
+  * [json patch](jsonpatch.md) - Apply a json patch in a kustomization    
+
+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
+   
+
+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.md
+
+[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

@@ -0,0 +1,213 @@
+[patch]: ../docs/glossary.md#patch
+[resource]: ../docs/glossary.md#resource
+[variant]: ../docs/glossary.md#variant
+
+## ConfigMap generation and rolling updates
+
+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 
+
+> ```
+> # declare ConfigMap as a resource
+> resources:
+> - configmap.yaml
+> 
+> # declare ConfigMap from a ConfigMapGenerator
+> configMapGenerator:
+> - name: a-configmap
+>   files:
+>     - configs/configfile
+>     - configs/another_configfile
+> ```
+
+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.
+
+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.
+
+### Establish base and staging
+
+Establish the base with a configMapGenerator
+<!-- @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
+```
+
+Establish the staging with a patch applied to the ConfigMap
+<!-- @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
+
+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 $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](https://github.com/kubernetes-sigs/kustomize/issues/242).
+
+### 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 ConfigMap it modifies is declared from a configMapGenerator.
+
+<!-- @showMapBase @test -->
+```
+grep -C 4 configMapGenerator $BASE/kustomization.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 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

@@ -0,0 +1,311 @@
+[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
+
+Steps:
+
+ 1. Clone an existing configuration as a [base].
+ 1. Customize it.
+ 1. Create two different [overlays] (_staging_ and _production_)
+    from the customized base.
+ 1. Run kustomize and kubectl to deploy staging and production.
+
+First define a place to work:
+
+<!-- @makeWorkplace @test -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+Alternatively, use
+
+> ```
+> DEMO_HOME=~/hello
+> ```
+
+## Establish the base
+
+Let's run the [hello] service.
+
+To use [overlays] to create [variants], we must
+first establish a common [base].
+
+To keep this document shorter, the base resources are
+off in a supplemental data directory rather than
+declared here as HERE documents.  Download them:
+
+<!-- @downloadBase @test -->
+```
+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"
+```
+
+Look at the directory:
+
+<!-- @runTree @test -->
+```
+tree $DEMO_HOME
+```
+
+Expect something like:
+
+> ```
+> /tmp/tmp.IyYQQlHaJP
+> └── base
+>     ├── configMap.yaml
+>     ├── deployment.yaml
+>     ├── kustomization.yaml
+>     └── service.yaml
+> ```
+
+
+One could immediately apply these resources to a
+cluster:
+
+> ```
+> kubectl apply -f $DEMO_HOME/base
+> ```
+
+to instantiate the _hello_ service.  `kubectl`
+would only recognize the resource files.
+
+### The Base Kustomization
+
+The `base` directory has a [kustomization] file:
+
+<!-- @showKustomization @test -->
+```
+more $BASE/kustomization.yaml
+```
+
+Optionally, run `kustomize` on the base to emit
+customized resources to `stdout`:
+
+<!-- @buildBase @test -->
+```
+kustomize build $BASE
+```
+
+### Customize the base
+
+A first customization step could be to change the _app
+label_ applied to all resources:
+
+<!-- @addLabel @test -->
+```
+sed -i.bak 's/app: hello/app: my-hello/' \
+    $BASE/kustomization.yaml
+```
+
+See the effect:
+<!-- @checkLabel @test -->
+```
+kustomize build $BASE | grep -C 3 app:
+```
+
+## Create Overlays
+
+Create a _staging_ and _production_ [overlay]:
+
+ * _Staging_ enables a risky feature not enabled in production.
+ * _Production_ has a higher replica count.
+ * Web server greetings from these cluster
+   [variants] will differ from each other.
+
+<!-- @overlayDirectories @test -->
+```
+OVERLAYS=$DEMO_HOME/overlays
+mkdir -p $OVERLAYS/staging
+mkdir -p $OVERLAYS/production
+```
+
+#### Staging Kustomization
+
+In the `staging` directory, make a kustomization
+defining a new name prefix, and some different 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
+
+Add a configMap customization to change the server
+greeting from _Good Morning!_ to _Have a pineapple!_
+
+Also, enable the _risky_ flag.
+
+<!-- @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
+
+In the production directory, make a kustomization
+with a different name prefix and 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
+
+Make a production patch that increases the replica
+count (because production takes more traffic).
+
+<!-- @productionDeployment @test -->
+```
+cat <<EOF >$OVERLAYS/production/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: the-deployment
+spec:
+  replicas: 10
+EOF
+```
+
+## Compare overlays
+
+
+`DEMO_HOME` now contains:
+
+ - a _base_ directory - a slightly customized clone
+   of the original configuration, and
+
+ - an _overlays_ directory, containing the kustomizations
+   and patches required to create distinct _staging_
+   and _production_ [variants] in a cluster.
+
+Review the directory structure and differences:
+
+<!-- @listFiles @test -->
+```
+tree $DEMO_HOME
+```
+
+Expecting something like:
+
+> ```
+> /tmp/tmp.IyYQQlHaJP1
+> ├── base
+> │   ├── configMap.yaml
+> │   ├── deployment.yaml
+> │   ├── kustomization.yaml
+> │   └── service.yaml
+> └── overlays
+>     ├── production
+>     │   ├── deployment.yaml
+>     │   └── kustomization.yaml
+>     └── staging
+>         ├── kustomization.yaml
+>         └── map.yaml
+> ```
+
+Compare the output directly
+to see how _staging_ and _production_ differ:
+
+<!-- @compareOutput -->
+```
+diff \
+  <(kustomize build $OVERLAYS/staging) \
+  <(kustomize build $OVERLAYS/production) |\
+  more
+```
+
+The first part of the difference output should look
+something like
+
+> ```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)
+> ```
+
+
+## Deploy
+
+The individual resource sets are:
+
+<!-- @buildStaging @test -->
+```
+kustomize build $OVERLAYS/staging
+```
+
+<!-- @buildProduction @test -->
+```
+kustomize build $OVERLAYS/production
+```
+
+To deploy, pipe the above commands to kubectl apply:
+
+> ```
+> kustomize build $OVERLAYS/staging |\
+>     kubectl apply -f -
+> ```
+
+> ```
+> kustomize build $OVERLAYS/production |\
+>    kubectl apply -f -
+> ```

examples/helloWorld/kustomization.yaml

@@ -0,0 +1,9 @@
+# Example configuration for the webserver
+# at https://github.com/monopole/hello
+commonLabels:
+  app: hello
+
+resources:
+- deployment.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

@@ -24,7 +24,7 @@
 #
 # This script assumes that the process running it has
 # checked out the kubernetes-sigs/kustomize repo, and
-# has cd'ed into it (i.e. the directory above "demos")
+# has cd'ed into it (i.e. the directory above "examples")
 # before running it.
 #
 # At time of writing, its 'call point' was in
@@ -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
@@ -79,6 +79,6 @@ function runTest {
 
 setUpEnv
 
-pushd demos
+pushd examples
 runTest ldap/integration_test.sh ldap/base
 popd

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/README.md

@@ -0,0 +1,281 @@
+[base]: ../../docs/glossary.md#base
+[gitops]: ../../docs/glossary.md#gitops
+[kustomization]: ../../docs/glossary.md#kustomization
+[overlay]: ../../docs/glossary.md#overlay
+[overlays]: ../../docs/glossary.md#overlay
+[variant]: ../../docs/glossary.md#variant
+[variants]: ../../docs/glossary.md#variant
+
+# Demo: LDAP with variants
+
+Steps:
+
+ 1. Clone an existing configuration as a [base].
+ 1. Customize it.
+ 1. Create two different [overlays] (_staging_ and _production_)
+    from the customized base.
+ 1. Run kustomize and kubectl to deploy staging and production.
+
+First define a place to work:
+
+<!-- @makeWorkplace @test -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+Alternatively, use
+
+> ```
+> DEMO_HOME=~/ldap
+> ```
+
+## Establish the base
+
+To use [overlays] to create [variants], we must
+first establish a common [base].
+
+To keep this document shorter, the base resources are
+off in a supplemental data directory rather than
+declared here as HERE documents.  Download them:
+
+<!-- @downloadBase @test -->
+```
+BASE=$DEMO_HOME/base
+mkdir -p $BASE
+
+CONTENT="https://raw.githubusercontent.com\
+/kubernetes-sigs/kustomize\
+/master/examples/ldap"
+
+curl -s -o "$BASE/#1" "$CONTENT/base\
+/{deployment.yaml,kustomization.yaml,service.yaml,env.startup.txt}"
+```
+
+Look at the directory:
+
+<!-- @runTree @test -->
+```
+tree $DEMO_HOME
+```
+
+Expect something like:
+
+> ```
+> /tmp/tmp.IyYQQlHaJP
+> └── base
+>     ├── deployment.yaml
+>     ├── env.startup.txt
+>     ├── kustomization.yaml
+>     └── service.yaml
+> ```
+
+
+One could immediately apply these resources to a
+cluster:
+
+> ```
+> kubectl apply -f $DEMO_HOME/base
+> ```
+
+to instantiate the _ldap_ service.  `kubectl`
+would only recognize the resource files.
+
+### The Base Kustomization
+
+The `base` directory has a [kustomization] file:
+
+<!-- @showKustomization @test -->
+```
+more $BASE/kustomization.yaml
+```
+
+Optionally, run `kustomize` on the base to emit
+customized resources to `stdout`:
+
+<!-- @buildBase @test -->
+```
+kustomize build $BASE
+```
+
+### Customize the base
+
+A first customization step could be to set the name prefix to all resources:
+
+<!-- @namePrefix @test -->
+```
+cd $BASE
+kustomize edit set nameprefix "my-"
+```
+
+See the effect:
+<!-- @checkNameprefix @test -->
+```
+kustomize build $BASE | grep -C 3 "my-"
+```
+
+## Create Overlays
+
+Create a _staging_ and _production_ [overlay]:
+
+ * _Staging_ adds a configMap.
+ * _Production_ has a higher replica count and a persistent disk.
+ * [variants] will differ from each other.
+
+<!-- @overlayDirectories @test -->
+```
+OVERLAYS=$DEMO_HOME/overlays
+mkdir -p $OVERLAYS/staging
+mkdir -p $OVERLAYS/production
+```
+
+#### Staging Kustomization
+
+Download the staging customization and patch.
+
+<!-- @downloadStagingKustomization @test -->
+```
+curl -s -o "$OVERLAYS/staging/#1" "$CONTENT/overlays/staging\
+/{config.env,deployment.yaml,kustomization.yaml}"
+```
+
+The staging customization adds a configMap.
+> ```cat $OVERLAYS/staging/kustomization.yaml
+> (...truncated)
+> configMapGenerator:
+>   - name: env-config
+>     files:
+>       - config.env
+> ```
+as well as 2 replica
+> ```cat $OVERLAYS/staging/deployment.yaml
+> apiVersion: apps/v1beta2
+> kind: Deployment
+> metadata:
+>   name: ldap
+> spec:
+>   replicas: 2
+> ```
+
+#### Production Kustomization
+
+Download the production customization and patch.
+<!-- @downloadProductionKustomization @test -->
+```
+curl -s -o "$OVERLAYS/production/#1" "$CONTENT/overlays/production\
+/{deployment.yaml,kustomization.yaml}"
+```
+
+The production customization adds 6 replica as well as a consistent disk.
+> ```cat $OVERLAYS/production/deployment.yaml
+> apiVersion: apps/v1beta2
+> kind: Deployment
+> metadata:
+>   name: ldap
+> spec:
+>   replicas: 6
+>   template:
+>     spec:
+>       volumes:
+>         - name: ldap-data
+>           emptyDir: null
+>           gcePersistentDisk:
+>             pdName: ldap-persistent-storage
+> ```
+
+## Compare overlays
+
+
+`DEMO_HOME` now contains:
+
+ - a _base_ directory - a slightly customized clone
+   of the original configuration, and
+
+ - an _overlays_ directory, containing the kustomizations
+   and patches required to create distinct _staging_
+   and _production_ [variants] in a cluster.
+
+Review the directory structure and differences:
+
+<!-- @listFiles @test -->
+```
+tree $DEMO_HOME
+```
+
+Expecting something like:
+
+> ```
+> /tmp/tmp.IyYQQlHaJP1
+> ├── base
+> │   ├── deployment.yaml
+> │   ├── env.startup.txt
+> │   ├── kustomization.yaml
+> │   └── service.yaml
+> └── overlays
+>     ├── production
+>     │   ├── deployment.yaml
+>     │   └── kustomization.yaml
+>     └── staging
+>         ├── config.env
+>         ├── deployment.yaml
+>         └── kustomization.yaml
+> ```
+
+Compare the output directly
+to see how _staging_ and _production_ differ:
+
+<!-- @compareOutput -->
+```
+diff \
+  <(kustomize build $OVERLAYS/staging) \
+  <(kustomize build $OVERLAYS/production) |\
+  more
+```
+
+The difference output should look something like
+
+> ```diff
+> (...truncated)
+> <   name: staging-my-ldap-configmap-kftftt474h
+> ---
+> >   name: production-my-ldap-configmap-k27f7hkg4f
+> 85c75
+> <   name: staging-my-ldap-service
+> ---
+> >   name: production-my-ldap-service
+> 97c87
+> <   name: staging-my-ldap
+> ---
+> >   name: production-my-ldap
+> 99c89
+> <   replicas: 2
+> ---
+> >   replicas: 6
+> (...truncated)
+> ```
+
+
+## Deploy
+
+The individual resource sets are:
+
+<!-- @buildStaging @test -->
+```
+kustomize build $OVERLAYS/staging
+```
+
+<!-- @buildProduction @test -->
+```
+kustomize build $OVERLAYS/production
+```
+
+To deploy, pipe the above commands to kubectl apply:
+
+> ```
+> kustomize build $OVERLAYS/staging |\
+>     kubectl apply -f -
+> ```
+
+> ```
+> kustomize build $OVERLAYS/production |\
+>    kubectl apply -f -
+> ```

examples/ldap/overlays/production/kustomization.yaml

@@ -0,0 +1,5 @@
+resources:
+  - ../../base
+patchesStrategicMerge:
+  - deployment.yaml
+namePrefix: production-

examples/ldap/overlays/staging/kustomization.yaml

@@ -0,0 +1,9 @@
+resources:
+- ../../base
+patchesStrategicMerge:
+ - deployment.yaml
+namePrefix: staging-
+configMapGenerator:
+- 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-