Update kustomize documentation

Add tree/directory structure for clarity. Update title for last section. Add example of using transformer configuration.

Signed-off-by: Scott Lowe <[email protected]>

docs/book/src/tasks/using-kustomize.md

@@ -9,8 +9,24 @@ may be integrated into `clusterctl` to help address this need, but in the meanti
 `kustomize` as a solution to this need.
 
 This document provides a few examples of using `kustomize` with Cluster API. All of these examples 
-assume that the "base" (unmodified) Cluster API configuration (perhaps generated using 
-`clusterctl config cluster`) is in a directory whose relative path is `../../base`.
+assume that you are using a directory structure that looks something like this:
+
+```
+.
+├── base
+│   ├── base.yaml
+│   └── kustomization.yaml
+└── overlays
+    ├── custom-ami
+    │   ├── custom-ami.json
+    │   └── kustomization.yaml
+    └── mhc
+        ├── kustomization.yaml
+        └── workload-mhc.yaml
+```
+
+In the overlay directories, the "base" (unmodified) Cluster API configuration (perhaps generated using 
+`clusterctl config cluster`) would be referenced as a resource in `kustomization.yaml` using `../../base`.
 
 ## Example: Using Kustomize to Specify Custom Images
 
@@ -33,7 +49,7 @@ patchesJson6902:
       version: v1alpha3
 ```
 
-The referenced JSON 6902 patch looks like this:
+The referenced JSON 6902 patch in `custom-ami.json` would look something like this:
 
 ```json
 [
@@ -48,7 +64,7 @@ configuration would catch all nodes in the workload cluster.
 ## Example: Adding a MachineHealthCheck for a Workload Cluster
 
 Users could also use `kustomize` to combine additional resources, like a MachineHealthCheck (MHC), with the 
-base Cluster API manifest. In an overlay, specify the following in `kustomization.yaml`:
+base Cluster API manifest. In an overlay directory, specify the following in `kustomization.yaml`:
 
 ```yaml
 ---
@@ -82,16 +98,25 @@ spec:
     timeout: 300s
 ```
 
+You would want to ensure the `clusterName` field in the MachineHealthCheck manifest appropriately 
+matches the name of the workload cluster, taking into account any transformations you may have specified 
+in `kustomization.yaml` (like the use of "namePrefix" or "nameSuffix").
+
 Running `kustomize build .` with this configuration would append the MHC to the base 
 Cluster API manifest, thus creating the MHC at the same time as the workload cluster.
 
-## Configuring Kustomize for Cluster API
+## Modifying Names
+
+The `kustomize` "namePrefix" and "nameSuffix" transformers are not currently "Cluster API aware." 
+Although it is possible to use these transformers with Cluster API manifests, doing so requires separate 
+patches for Clusters versus infrastructure-specific equivalents (like an AzureCluster or a vSphereCluster). 
+This can significantly increase the complexity of using `kustomize` for this use case.
 
-Although `kustomize` can be used with Cluster API without any changes, modifying the transformer 
-configurations for `kustomize` can make it more effective with Cluster API. For example, changes to 
-the `nameReference` transformer in `kustomize` will enable `kustomize` to know about the references 
-between Cluster API objects in a manifest. See [here](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/transformerconfigs) 
-for more information on transformer configurations.
+Modifying the transformer configurations for `kustomize` can make it more effective with Cluster API. 
+For example, changes to the `nameReference` transformer in `kustomize` will enable `kustomize` to know 
+about the references between Cluster API objects in a manifest. See 
+[here](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/transformerconfigs) for more 
+information on transformer configurations.
 
 Add the following content to the `namereference.yaml` transformer configuration:
 
@@ -150,5 +175,21 @@ Add the following content to the `namereference.yaml` transformer configuration:
     kind: MachineDeployment
 ```
 
-This will enable the use of the `namePrefix` and `nameSuffix` directives in `kustomization.yaml` 
-and ensure that _all_ references to the names are properly updated.
+Including this custom configuration in a `kustomization.yaml` would then enable the use of simple 
+"namePrefix" and/or "nameSuffix" directives, like this:
+
+```yaml
+---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - ../../base
+configurations:
+  - namereference.yaml
+namePrefix: "blue-"
+nameSuffix: "-dev"
+```
+
+Running `kustomize build. ` with this configuration would modify the name of all the Cluster API 
+objects _and_ the associated referenced objects, adding "blue-" at the beginning and appending "-dev" 
+at the end.