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
+
+[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.  This method may be used when the preceding methods would not be able to configure custom path locations correctly.  You may define `ClusterWorkloadResourceMapping.servicebindings.io` resources, which specifies where binding data will be projected for a given workload kind.
+
+.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 the `ClusterWorkloadResourceMapping` resource, which must be qualified as the `plural.group` of the mapped workload resource.  For example, `cronjobs.batch` for CronJobs.
+<2> Version of the resource that is being mapped.  Any version that is not specified can be matched with the "*" wildcard.
+<3> Optional: Identifier of the `.annotations` field in a pod, specified with a fixed JSONPath.  The default value is `.spec.template.spec.annotations`.
+<4> Identifies 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 container, specified with a fixed JSONPath.  The default value is `.name`.
+<6> Optional: Identifier of the `.env` field in a container, specified with a fixed JSONPath.  The default value is `.env`.
+<7> Optional: Identifier of the `.volumeMounts` field in a container, specified with a fixed JSONPath.  The default value is `.volumeMounts`.
+<8> Optional: Identifier of the `.volumes` field in a pod, specified with a fixed JSONPath.  The default 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.
+====
+
+[NOTE]
+====
+* Most of these fields are optional, and the {servicebinding-title} assumes PodSpec-compatible defaults when they are not specified.
+* The {servicebinding-title} requires that each of these fields is structurally equivalent to the corresponding field in a Pod deployment.  For example, the contents of the `.env` field in a workload resource must be able to accept the same structure of data that the `.env` field in a Pod resource would.  Otherwise, projecting binding information into such a workload may result in unexpected behavior from the {servicebinding-title}.
+====
+
+Using the previous schema, you 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.
+====