Add example for transformer configurations: crd

examples/README.md

@@ -42,3 +42,6 @@ go get sigs.k8s.io/kustomize
  * [remote target](remoteBuild.md) - Building a kustomization from a github URL
 
  * [json patch](jsonpatch.md) - Apply a json patch in a kustomization
+
+ * [transformer configs](transformerconfigs/README.md) - Customize transformer configurations
+

examples/transformerconfigs/README.md

@@ -0,0 +1,96 @@
+# Transformer Configurations
+
+Kustomize computes the resources by applying a series of transformers:
+- namespace transformer
+- prefix transformer
+- label transformer
+- annotation transformer
+- name reference transformer
+- variable reference transformer
+
+Each transformer takes a list of resources and modifies certain fields. The modification is based on the transformer's rule.
+The fields to update is the transformer's configuration, which is a list of filedspec that can be represented in YAML format.
+
+## fieldSpec
+FieldSpec is a type to represent a path to a field in one kind of resources. It has following format
+```
+group: some-group
+version: some-version
+kind: some-kind
+path: path/to/the/field
+create: false
+```
+If `create` is set to true, it indicates the transformer to create the path if it is not found in the resources. This is most useful for label and annotation transformers, where the path for labels or annotations may not be set before the transformation.
+
+## prefix transformer
+Name prefix transformer adds prefix to the `metadata/name` field for all resources with following configuration:
+```
+namePrefix:
+- path: metadata/name
+```
+
+## label transformer
+Label transformer adds labels to `metadata/labels` field for all resources. It also adds labels to `spec/selector` field in all Service and to `spec/selector/matchLabels` field in all Deployment.
+```
+commonLabels:
+- path: metadata/labels
+  create: true
+
+- path: spec/selector
+  create: true
+  version: v1
+  kind: Service
+
+- path: spec/selector/matchLabels
+  create: true
+  kind: Deployment
+  (etc.)  
+```
+
+## name reference transformer
+Name reference transformer's configuration is different from all other transformers. It contains a list of namebackreferences, which represented all the possible fields that a type could be used as a reference in other types of resources. A namebackreference contains a type such as ConfigMap as well as a list of FieldSpecs where ConfigMap is referenced. Here is an example.
+```
+kind: ConfigMap
+version: v1
+FieldSpecs:
+- kind: Pod
+  version: v1
+  path: spec/volumes/configMap/name
+- kind: Deployment
+  path: spec/template/spec/volumes/configMap/name
+- kind: Job
+  path: spec/template/spec/volumes/configMap/name
+  (etc.)
+```
+Name reference transformer configuration contains a list of such namebackreferences for ConfigMap, Secret, Service, Role, ServiceAccount and so on.
+```
+nameReference:
+- kind: ConfigMap
+  version: v1
+  fieldSpecs:
+  - path: spec/volumes/configMap/name
+    version: v1
+    kind: Pod
+  - path: spec/containers/env/valueFrom/configMapKeyRef/name
+    version: v1
+    kind: Pod
+    (etc.)
+- kind: Secret
+  version: v1
+  fieldSpecs:
+  - path: spec/volumes/secret/secretName
+    version: v1
+    kind: Pod
+  - path: spec/containers/env/valueFrom/secretKeyRef/name
+    version: v1
+    kind: Pod
+    (etc.)    
+```
+
+## cusotmizing transformer configurations
+
+Kustomize has a default set of configurations. They can be saved to local directory through `kustomize config save -d`. kusotmize allows modifying those configuration files and using them in `kustomize build` through `-t`.  This tutorial shows how to customize those configurations to
+- [support a crd type](crd/README.md)
+- disabling adding commonLabels to fields in some kind of resources
+- add extra fields for variable substitution
+- add extra fields for name reference

examples/transformerconfigs/crd/README.md

@@ -0,0 +1,171 @@
+## Transformer Configurations - CRD
+
+This tutorial shows how to add transformer configurations to support a CRD type.
+
+### Get Default Config
+Get the default transformer configurations by
+
+<!-- @saveConfig @test -->
+```
+kustomize config save -d ~/.kustomize/config
+```
+The default configurations are save in directory `~/.kustomize/config` as several files
+
+> ```
+>  commonannotations.yaml  commonlabels.yaml  nameprefix.yaml  namereference.yaml  namespace.yaml  varreference.yaml
+> ```
+
+### Add Config for a CRD
+All transformers will be involved for a CRD type. The default configurations already include some common fieldSpec for all types:
+
+- nameprefix is added to `.metadata.name`
+- namespace is added to `.metadata.namespace`
+- labels is added to `.metadata.labels`
+- annotations is added to `.metadata.annotations`
+
+Thus those fieldSpec don't need to be added to support a CRD type.
+Consider a CRD type `MyKind` with fields
+- `.spec.secretRef.name` reference a Secret
+- `.spec.beeRef.name` reference an instance of CRD `Bee`
+- `.spec.containers.command` as the list of container commands
+- `.spec.selectors` as the label selectors
+
+Add following file to configure the transformers for the above fields
+<!-- @addConfig @test -->
+```
+cat > ~/.kustomize/config/mykind.yaml << EOF
+
+commonLabels:
+- path: spec/selectors
+  create: true
+  kind: MyKind
+
+nameReference:
+- kind: Bee
+  fieldSpecs:
+  - path: spec/beeRef/name
+    kind: MyKind
+- kind: Secret
+  fieldSpecs:
+  - path: spec/secretRef/name
+    kind: MyKind
+
+varReference:
+- path: spec/containers/command
+  kind: MyKind
+- path: spec/beeRef/action
+  kind: MyKind
+
+EOF
+```
+
+### Apply config
+Create a kustomization with a `MyKind` instance.
+
+<!-- @createKustomization @test -->
+```
+DEMO_HOME=$(mktemp -d)
+
+cat > $DEMO_HOME/kustomization.yaml << EOF
+resources:
+- resources.yaml
+
+namePrefix: test-
+
+commonLabels:
+  foo: bar
+
+vars:
+- name: BEE_ACTION
+  objref:
+    kind: Bee
+    name: bee
+    apiVersion: v1beta1
+  fieldref:
+    fieldpath: spec.action
+EOF
+
+cat > $DEMO_HOME/resources.yaml << EOF
+apiVersion: v1
+kind: Secret
+metadata:
+  name: crdsecret
+data:
+  PATH: YmJiYmJiYmIK
+---
+apiVersion: v1beta1
+kind: Bee
+metadata:
+  name: bee
+spec:
+  action: fly
+---
+apiVersion: jingfang.example.com/v1beta1
+kind: MyKind
+metadata:
+  name: mykind
+spec:
+  secretRef:
+    name: crdsecret
+  beeRef:
+    name: bee
+    action: \$(BEE_ACTION)
+  containers:
+  - command:
+    - "echo"
+    - "\$(BEE_ACTION)"
+    image: myapp
+EOF
+```
+
+Run `kustomize build` with customized transformer configurations and verify that
+the namereference is correctly resolved.
+
+<!-- @build @test -->
+```
+test 2 == \
+$(kustomize build $DEMO_HOME -t ~/.kustomize/config | grep -A 2 ".*Ref" | grep "test-" | wc -l); \
+echo $?    
+```
+
+Run `kustomize build` with customized transformer configurations and verify that
+the vars correctly resolved.
+
+<!-- @verify @test -->
+```
+test 0 == \
+$(kustomize build $DEMO_HOME -t ~/.kustomize/config | grep "BEE_ACTION" | wc -l); \
+echo $?    
+```
+
+To understand this better, compare the output using default transformer configurations.
+
+<!-- @compareOutput -->
+```
+diff \
+ <(kustomize build $DEMO_HOME) \
+ <(kustomize build $DEMO_HOME -t ~/.kustomize/config ) |\
+ more
+```
+
+The difference output should look something like
+> ```
+> 20,21c20,21
+> <     action: $(BEE_ACTION)
+> <     name: bee
+> ---
+> >     action: fly
+> >     name: test-bee
+> 25c25
+> <     - $(BEE_ACTION)
+> ---
+> >     - fly
+> 28c28,30
+> <     name: crdsecret
+> ---
+> >     name: test-crdsecret
+> >   selectors:
+> >     foo: bar
+> ```
+
+

examples/transformerconfigs/crd/kustomization.yaml

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

examples/transformerconfigs/crd/resources.yaml

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