docs: document workload resource mapping

Signed-off-by: Andy Sadler <[email protected]>

Author: sadlerap

docs/userguide/modules/creating-service-bindings/pages/custom-path-injection.adoc

@@ -79,7 +79,7 @@ spec:
 NOTE: This feature is only available for `ServiceBinding` in the
 `binding.operators.coreos.com` API group.
 
-SBO provides an API to inject a binding secret name into a custom application resource field.
+SBO provides an API to project a binding secret name into a custom application resource field.
 Here is an example CR with the secret in a custom location:
 
 [source,yaml]
@@ -132,3 +132,83 @@ metadata:
 spec:
     secret: binding-request-72ddc0c540ab3a290e138726940591debf14c581
 ....
+
+== Workload resource mapping
+
+The specification also provides a way of defining exactly where binding data needs to be projected
+into, which may work in situations where the above methods won't work.  This is done by defining
+`ClusterWorkloadResourceMapping.servicebindings.io` resources, which define where binding data gets
+projected for a given workload kind.  This works for both CoreOS and specification service binding
+resources.
+
+The schema of these resources looks like the following:
+[source,yaml]
+....
+apiVersion: servicebinding.io/v1alpha3
+kind: ClusterWorkloadResourceMapping
+metadata:
+  name: # string <1>
+  ...
+spec:
+  versions: # required, at least one entry must be defined
+  - version: # string <2>
+    annotations: # string (Fixed JSONPath), optional <3>
+    containers: # optional
+    - path: # string (JSONPath) <4>
+      name: # string (Fixed JSONPath), optional <5>
+      env: # string (Fixed JSONPath), optional <6>
+      volumeMounts: # string (Fixed JSONPath), optional <7>
+    volumes: # string (Fixed JSONPath), optional <8>
+....
+<1> the name of this resource (must be qualified as `plural.group`, i.e. `cronjobs.batch` for CronJobs)
+<2> the version of the resource we're mapping (can match all unspecified versions with the wildcard "*")
+<3> where annotations live with a fixed JSONPath (default: `.spec.template.spec.annotations`)
+<4> where containers live with a JSONPath (if no entries are defined, SBO defaults to two paths:
+`.spec.template.spec.containers` and `.spec.template.spec.initContainers` with all other fields
+set as their default).
+<5> corresponds to the `.name` field in a pod. Defaults to `.name`.
+<6> corresponds to the `.env` environment variables. Defaults to `.env`.
+<7> corresponds to where the volume mounts of a pod lives. Defaults to `.volumeMounts`.
+<8> where volumes live with a fixed JSONPath (default: `.spec.template.spec.volumes`)
+
+[IMPORTANT]
+====
+In this context, a "Fixed JSONPath" is a subset of the JSONPath grammar that accepts only the
+following operations:
+
+. Field lookup: `.spec.template`
+. Array indexing: `.spec['template']`
+
+All other operations are forbidden.
+====
+
+Most of these fields are optional, and SBO assumes PodSpec-compatible defaults when not specified.
+SBO requires that each of these fields is semantically equivalent to the corresponding field in a Pod
+deployment; failing to maintain this may result in unexpected behavior.
+
+Using the above schema, we can define the following YAML as an example mapping for `CronJob.batch/v1`
+resources:
+
+[source,yaml]
+....
+apiVersion: servicebinding.io/v1alpha3
+kind: ClusterWorkloadResourceMapping
+metadata:
+ name: cronjobs.batch
+spec:
+  versions:
+  - version: "v1"
+    annotations: .spec.jobTemplate.spec.template.metadata.annotations
+    containers:
+    - path: .spec.jobTemplate.spec.template.spec.containers[*]
+    - path: .spec.jobTemplate.spec.template.spec.initContainers[*]
+    volumes: .spec.jobTemplate.spec.template.spec.volumes
+....
+
+NOTE: There is some behavior in the CoreOS API that doesn't exist in the specification API:
+
+. If a `ServiceBinding` resource with `bindAsFiles: false` is created with one of these mappings,
+then environment variables will be projected into `.envFrom` underneath each `path` field specified
+in the corresponding `ClusterWorkloadResourceMapping` resource.
+. Both this and the `containersPath` field documented above can be used at the same time.  This would
+be equivalent to adding a container entry with `path: $(containersPath)`.