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.  When they are not specified, the {servicebinding-title} assumes defaults compatible with `Pod` resources.
+* 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 data into such a workload might 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]
+====
+The following behavior occurs only in the `binding.operators.coreos.com` API group:
+
+. If a `ServiceBinding` resource with the `bindAsFiles: false` flag value is created together with one of these mappings, then environment variables are projected into the `.envFrom` field underneath each `path` field specified in the corresponding `ClusterWorkloadResourceMapping` resource.
+. As a cluster administrator, you can specify both a `ClusterWorkloadResourceMapping` resource and the `.spec.application.bindingPath.containersPath` field in a `ServiceBinding.bindings.coreos.com` resource for binding purposes.  The {servicebinding-title} attempts to project binding data into the locations specified in both of these methods.  This behavior is equivalent to adding a container entry to the corresponding `ClusterWorkloadResourceMapping` resource with the `path: $containersPath` attribute, with all other values taking their default value.
+====