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,86 @@ metadata:
 spec:
     secret: binding-request-72ddc0c540ab3a290e138726940591debf14c581
 ....
+
+== Workload resource mapping
+
+NOTE: Workload resource mapping is available for the secondary workloads of the ServiceBinding custom
+resource (CR) for both the API groups: `binding.operators.coreos.com` and `servicebinding.io`.
+
+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.
+
+.Example Schema of the `ClusterWorkloadResourceMapping` resource
+[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> Name of this resource, which must be qualified as `plural.group`.  For example, `cronjobs.batch` for CronJobs.
+<2> Version of the resource we're mapping.  Any version not specified can be matched with the "*" wildcard.
+<3> Optional: where annotations live, specified with a fixed JSONPath.  The default value is `.spec.template.spec.annotations`.
+<4> Optional: where containers live, specified with a JSONPath.  If no entries are defined, the {servicebinding-title} defaults to two paths: `.spec.template.spec.containers` and `.spec.template.spec.initContainers` with all other fields set as their default).
+<5> Optional: Identifier of the `.name` field in a pod.  The default value is `.name`.
+<6> Optional: Identifier of `.env` environment variables.  The default value is `.env`.
+<7> Optional: Identifier of the volume mounts of a pod lives.  The default value is `.volumeMounts`.
+<8> Optional: where volumes live, specified with a fixed JSONPath.  The defaults value is `.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, one 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 does not 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 `ClusterWorkloadResourceMapping.servicebinding.io` resources and the
+`.spec.application.bindingPath.containersPath` field will be considered for binding purposes.  This
+behavior would be equivalent to adding an entry to the corresponding `ClusterWorkloadResourceMapping`
+resource with `path: {containersPath}`, with all other values taking their default value.