new kustomize sample (#2136)

* wip first stab

* rebase of next

* updates to the kustomize files

* updates to README

* update per PR feedback

* removed the README's in overlays

* update to the readme

* using tree command because of nested folders

* updated the pkg get to point to next

package-examples/helloworld-set/README.md

@@ -16,7 +16,7 @@ setters in it.
 Get the example package on to local using `kpt pkg get`
 
 ```shell
-$ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/helloworld-set
+$ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/helloworld-set@next
 
 fetching package /package-examples/helloworld-set from https://github.com/GoogleContainerTools/kpt to helloworld-set
 ```

package-examples/helloworld-tshirt/README.md

@@ -18,7 +18,7 @@ resource sizes.
 Get the example package on to local using `kpt pkg get`
 
 ```shell
-$ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/helloworld-tshirt
+$ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/helloworld-tshirt@next
 
 fetching package /package-examples/helloworld-tshirt from https://github.com/GoogleContainerTools/kpt to helloworld-tshirt
 ```

package-examples/helloworld/README.md

@@ -14,7 +14,7 @@ doesn't do anything beyond declaring the current directory as a `kpt` package.
 Get the example package on to local using `kpt pkg get`
 
 ```shell
-$ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/helloworld
+$ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/helloworld@next
 
 fetching package /package-examples/helloworld from https://github.com/GoogleContainerTools/kpt to helloworld
 ```

package-examples/kustomize-pkg/Kptfile

@@ -0,0 +1,6 @@
+apiVersion: kpt.dev/v1alpha2
+kind: Kptfile
+metadata:
+  name: kustomize-pkg
+info:
+  description: kustomize kpt package

package-examples/kustomize-pkg/README.md

@@ -0,0 +1,162 @@
+# kustomize-pkg
+
+This is a simple package that shows how kpt packages can be used instead of remote bases in kustomize.  That allows you to take advantage of kpt's rebase and local, in-place edits.
+
+## Steps
+
+1. [Fetch the package](#fetch-the-package)
+2. [View the package contents](#view-the-package-contents)
+3. [kustomize the config](#kustomize-the-config)
+4. [Render the kustomization](#render-the-kustomization)
+5. [Apply the package](#apply-the-package)
+6. [Clean up resources](#clean-up-resources)
+
+### Fetch the package
+
+Get the example package on to local using `kpt pkg get`. Note that this package is for this example, wihin that package we are also using the nginx sub-package which is an alternative to having a remote base. 
+
+```shell
+$ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/kustomize-pkg@next
+
+fetching package /package-examples/kustomize-pkg from https://github.com/GoogleContainerTools/kpt to kustomize-pkg
+```
+
+
+### View the package contents
+
+List the package contents in a tree structure.
+
+```shell
+$ tree kustomize-pkg
+
+kustomize-pkg
+├── Kptfile
+├── README.md
+├── bases
+│   └── nginx
+│       ├── Kptfile
+│       ├── deployment.yaml
+│       ├── kustomization.yaml
+│       └── svc.yaml
+└── overlays
+    ├── dev
+    │   ├── Kptfile
+    │   ├── kustomization.yaml
+    │   └── pass-patch.yaml
+    └── prod
+        ├── Kptfile
+        ├── kustomization.yaml
+        └── pass-patch.yaml
+```
+
+### kustomize the config
+
+Kustomize is a great tool for out of place hydration, but we don't recommend that you mix kpt packages and remote bases.  It's best to have a clear delienation what you are using each tools for: kpt for packages and remote resources, kustomize for hydration like adding labels, setting namespaces and overlays.
+
+In the example below what was a remote base is now fetched locally as a kpt package and kustomize is used for hydration.
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+- ../../bases/nginx
+- Kptfile
+patches:
+- path: pass-patch.yaml
+  target:
+    kind: Deployment
+commonLabels:
+    environ: dev
+namePrefix: dev-
+```
+
+### Render the kustomization
+
+You can see the final configuration that the patch is going to render. The major difference between this and in place edit is that you can't just go to the file and look at it in isolation, you need to run `kustomize build` and examine the final results.
+
+```shell
+$ kustomize build kustomize-pkg/overlays/dev
+
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app: nginx
+    environ: dev
+  name: dev-my-nginx-svc
+spec:
+  ports:
+  - port: 80
+  selector:
+    app: nginx
+    environ: dev
+  type: LoadBalancer
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    environ: dev
+  name: dev-my-nginx
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: nginx
+      environ: dev
+  template:
+    metadata:
+      labels:
+        app: nginx
+        environ: dev
+    spec:
+      containers:
+      - image: nginx:1.14.1
+        name: nginx
+        ports:
+        - containerPort: 80
+---
+apiVersion: kpt.dev/v1alpha2
+info:
+  description: sample description
+kind: Kptfile
+metadata:
+  labels:
+    environ: dev
+  name: dev-dev
+
+
+### Apply the package
+
+It is possible to use kustomize build and kpt live apply, but it does require passing the inventory information to `kpt live apply` from `kustomize build` output.  It is best to have Kptfiles with inventory information in overlay folders in case the variants of the package are deployed to the same cluster.  Every variant of this application will need to be mapped to it\'s own inventory for pruning.  In case you have two variants that use the same inventory information the consequent deploy might wipe out the previous variant.
+
+```shell
+$ kpt live init kustomize-pkg/overlays/dev
+
+initializing Kptfile inventory info (namespace: default)...success
+```
+
+You might have noticed that the overlays have Kptfiles and they are added to the kustomization.yaml so the contents are passed all the way through the kustomize build.
+
+Kustomize build will need to be piped to kpt live apply:
+
+```shell
+$ kustomize build kustomize-pkg/overlays/dev | kpt live apply - 
+
+service/dev-my-nginx-svc created
+deployment.apps/dev-my-nginx created
+2 resource(s) applied. 2 created, 0 unchanged, 0 configured, 0 failed
+0 resource(s) pruned, 0 skipped, 0 failed
+```
+
+### Clean up resources
+
+You can use kpt to prune and clean up resources from your build by using `kpt live destroy`.  As long as the inventory information is passed in kpt will know how to clean everything up:
+
+```shell
+$ kustomize build kustomize-pkg/overlays/dev | kpt live destroy - 
+
+deployment.apps/dev-my-nginx deleted
+service/dev-my-nginx-svc deleted
+2 resource(s) deleted, 0 skipped
+```

package-examples/kustomize-pkg/bases/nginx/Kptfile

@@ -0,0 +1,21 @@
+apiVersion: kpt.dev/v1alpha2
+kind: Kptfile
+metadata:
+  name: nginx
+upstream:
+  type: git
+  git:
+    repo: https://github.com/GoogleContainerTools/kpt
+    directory: package-examples/nginx
+    ref: v0.2
+  updateStrategy: resource-merge
+upstreamLock:
+  type: git
+  git:
+    repo: https://github.com/GoogleContainerTools/kpt
+    directory: package-examples/nginx
+    ref: package-examples/nginx/v0.2
+    commit: 4d2aa98b45ddee4b5fa45fbca16f2ff887de9efb
+pipeline:
+  validators:
+    - image: gcr.io/kpt-fn/kubeval:v0.1

package-examples/helloworld-kustomize/resources/deploy.yaml → package-examples/kustomize-pkg/bases/nginx/deployment.yaml

@@ -11,31 +11,22 @@
 # 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.
-
-# This file configures the hello-world app which serves public web traffic.
 apiVersion: apps/v1
 kind: Deployment
-metadata:
-  name: helloworld-gke
-  labels:
-    app: hello
-    version: "0.1.0"
+metadata: # kpt-merge: /my-nginx
+  name: my-nginx
 spec:
-  replicas: 5
+  replicas: 3
   selector:
     matchLabels:
-      app: hello
+      app: nginx
   template:
     metadata:
       labels:
-        app: hello
+        app: nginx
     spec:
       containers:
-        - name: helloworld-gke
-          image: gcr.io/kpt-dev/helloworld-gke:0.3.0
+        - name: nginx
+          image: nginx:1.14.1
           ports:
-            - name: http
-              containerPort: 80
-          env:
-            - name: PORT
-              value: "80"
+            - containerPort: 80

package-examples/kustomize-pkg/bases/nginx/kustomization.yaml

@@ -0,0 +1,3 @@
+resources:
+- deployment.yaml
+- svc.yaml

package-examples/helloworld-kustomize/resources/service.yaml → package-examples/kustomize-pkg/bases/nginx/svc.yaml

@@ -1,4 +1,4 @@
-# Copyright 2019 Google LLC
+# Copyright 2021 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -11,22 +11,15 @@
 # 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.
-
-# The hello service provides a load-balancing proxy over the hello-app
-# pods. By specifying the type as a 'LoadBalancer', Kubernetes Engine will
-# create an external HTTP load balancer.
 apiVersion: v1
 kind: Service
-metadata:
-  name: helloworld-gke
+metadata: # kpt-merge: /my-nginx-svc
+  name: my-nginx-svc
   labels:
-    app: hello
-    version: '0.1.0'
+    app: nginx
 spec:
   type: LoadBalancer
   selector:
-    app: hello
+    app: nginx
   ports:
-  - protocol: TCP
-    port: 80
-    targetPort: http
+    - port: 80

package-examples/kustomize-pkg/overlays/dev/Kptfile

@@ -0,0 +1,6 @@
+apiVersion: kpt.dev/v1alpha2
+kind: Kptfile
+metadata:
+  name: dev
+info:
+  description: sample description