Merge pull request #939 from kbhawkey/doc-images-take2

add tutorial for custom images transformer

examples/transformerconfigs/README.md

@@ -3,11 +3,12 @@
 Kustomize creates new resources by applying a series of transformations to an original
 set of resources. Kustomize provides the following default transformers:
 
+- annotations
+- images
+- labels
+- name reference
 - namespace
 - prefix/suffix
-- label
-- annotation
-- name reference
 - variable reference
 
 A `fieldSpec` list, in a transformer's configuration, determines which resource types and which fields
@@ -27,6 +28,31 @@ create: false
 
 If `create` is set to `true`, the transformer creates the path to the field in the resource if the path is not already found. This is most useful for label and annotation transformers, where the path for labels or annotations may not be set before the transformation.
 
+## Images transformer
+
+The default images transformer updates the specified image key values found in paths that include
+`containers` and `initcontainers` sub-paths.
+If found, the `image` key value is customized by the values set in the `newName`, `newTag`, and `digest` fields.
+The `name` field should match the `image` key value in a resource.
+
+Example kustomization.yaml:
+
+```yaml
+images:
+  - name: postgres
+    newName: my-registry/my-postgres
+    newTag: v1
+  - name: nginx
+    newTag: 1.8.0
+  - name: my-demo-app
+    newName: my-app
+  - name: alpine
+    digest: sha256:25a0d4
+```
+
+Image transformer configurations can be customized by creating a list of `images` containing the `path` and `kind` fields.
+The images transformation tutorial shows how to specify the default images transformer and customize the [images transformer configuration](images/README.md).
+
 ## Prefix/suffix transformer
 
 The prefix/suffix transformer adds a prefix/suffix to the `metadata/name` field for all resources. Here is the default prefix transformer configuration:
@@ -36,9 +62,22 @@ namePrefix:
 - path: metadata/name
 ```
 
-## Label transformer
+Example kustomization.yaml:
+
+```yaml
+
+namePrefix:
+  alices-
+
+nameSuffix:
+  -v2
+```
+
+## Labels transformer
 
-The label transformer adds labels to the `metadata/labels` field for all resources. It also adds labels to the `spec/selector` field in all Service resources as well as the `spec/selector/matchLabels` field in all Deployment resources.
+The labels transformer adds labels to the `metadata/labels` field for all resources. It also adds labels to the `spec/selector` field in all Service resources as well as the `spec/selector/matchLabels` field in all Deployment resources.
+
+Example:
 
 ```yaml
 commonLabels:
@@ -55,6 +94,29 @@ commonLabels:
   kind: Deployment
 ```
 
+Example kustomization.yaml:
+
+```yaml
+commonLabels:
+  someName: someValue
+  owner: alice
+  app: bingo
+```
+
+## Annotations transformer
+
+The annotations transformer adds annotations to the `metadata/annotations` field for all resources.
+Annotations are also added to `spec/template/metadata/annotations` for Deployment,
+ReplicaSet, DaemonSet, StatefulSet, Job, and CronJob resources, and `spec/jobTemplate/spec/template/metadata/annotations`
+for CronJob resources.
+
+Example kustomization.yaml
+
+```yaml
+commonAnnotations:
+  oncallPager: 800-555-1212
+```
+
 ## Name reference transformer
 
 Name reference transformer's configuration is different from all other transformers. It contains a list of `nameReferences`, which represent all of the possible fields that a type could be used as a reference in other types of resources. A `nameReference` contains a type such as ConfigMap as well as a list of `fieldSpecs` where ConfigMap is referenced in other resources. Here is an example:
@@ -99,7 +161,7 @@ nameReference:
 
 ## Customizing transformer configurations
 
-Kustomize has a default set of transformer configurations. You can save the default transformer configurations to a local directory by calling `kustomize config save -d`, and modify and use these configurations. Kustomize also supports adding new transformer configurations to kustomization.yaml. This tutorial shows how to customize those configurations to:
+In addition to the default transformers, you can create custom transformer configurations. Save the default transformer configurations to a local directory by calling `kustomize config save -d`, and modify and use these configurations. This tutorial shows how to create custom transformer configurations:
 
 - [support a CRD type](crd/README.md)
 - add extra fields for variable substitution

examples/transformerconfigs/images/README.md

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

examples/transformerconfigs/images/kustomization.yaml

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

examples/transformerconfigs/images/mykind.yaml

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

examples/transformerconfigs/images/resources.yaml

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