Merge pull request #46315 from Srivaralakshmi/SBO_WorkloadResourceMapping

RHDEVDOCS-3491 - Document support for Workload Resource Mapping

Author: JStickler

applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc

@@ -7,7 +7,6 @@ include::_attributes/servicebinding-document-attributes.adoc[]
 
 toc::[]
 
-[role="_abstract"]
 Application developers must bind a workload to one or more backing services by using a binding secret. This secret is generated for the purpose of storing information to be consumed by the workload.
 
 As an example, consider that the service you want to connect to is already exposing the binding data. In this case, you would also need a workload to be used along with the `ServiceBinding` custom resource (CR). By using this `ServiceBinding` CR, the workload sends a binding request with the details of the services to bind with.
@@ -42,6 +41,11 @@ include::modules/sbo-advanced-binding-options.adoc[leveloffset=+1]
 include::modules/sbo-binding-workloads-that-are-not-compliant-with-PodSpec.adoc[leveloffset=+1]
 include::modules/sbo-unbinding-workloads-from-a-backing-service.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
+[id="additional-resources_binding-workloads-sbo"]
 == Additional resources
 * xref:../../applications/connecting_applications_to_services/understanding-service-binding-operator.adoc#binding-a-workload-together-with-a-backing-service[Binding a workload together with a backing service].
-* xref:../../applications/connecting_applications_to_services/getting-started-with-service-binding.adoc#connecting-the-spring-petclinic-sample-application-to-the-postgresql-database-service[Connecting the Spring PetClinic sample application to the PostgreSQL database service].
+* xref:../../applications/connecting_applications_to_services/getting-started-with-service-binding.adoc#connecting-the-spring-petclinic-sample-application-to-the-postgresql-database-service[Connecting the Spring PetClinic sample application to the PostgreSQL database service].
+* xref:../../operators/understanding/crds/crd-managing-resources-from-crds.adoc#crd-creating-custom-resources-from-file_crd-managing-resources-from-crds[Creating custom resources from a file]
+* link:https://redhat-developer.github.io/service-binding-operator/userguide/binding-workloads-using-sbo/custom-path-injection.html#_workload_resource_mapping[Example schema of the ClusterWorkloadResourceMapping resource]. 
+

modules/sbo-binding-workloads-that-are-not-compliant-with-PodSpec.adoc

@@ -6,14 +6,16 @@
 [id="sbo-binding-workloads-that-are-not-compliant-with-PodSpec_{context}"]
 = Binding secondary workloads that are not compliant with PodSpec
 
-[role="_abstract"]
 A typical scenario in service binding involves configuring the backing service, the workload (Deployment), and {servicebinding-title}. Consider a scenario that involves a secondary workload (which can also be an application Operator) that is not compliant with PodSpec and is between the primary workload (Deployment) and {servicebinding-title}.
 
 For such secondary workload resources, the location of the container path is arbitrary. For service binding, if the secondary workload in a CR is not compliant with the PodSpec, you must specify the location of the container path. Doing so projects the binding data into the container path specified in the secondary workload of the `ServiceBinding` custom resource (CR), for example, when you do not want the binding data inside a pod.
 
-{servicebinding-title} provides an option to configure the value of where the container path or secret path is and bind these paths at a custom location. This option is available only for the `binding.operators.coreos.com` API group when the binding data is projected as environment variables.
+In {servicebinding-title}, you can configure the path of where containers or secrets reside within a workload and bind these paths at a custom location.
 
+[id="configuring-custom-location-of-container-path_{context}"]
 == Configuring the custom location of the container path
+This custom location is available for the `binding.operators.coreos.com` API group when {servicebinding-title} projects the binding data as environment variables.
+
 Consider a secondary workload CR, which is not compliant with the PodSpec and has containers located at the `spec.containers` path:
 
 .Example: Secondary workload CR
@@ -99,7 +101,10 @@ spec:
 <1> Unique array of containers with values generated by the {servicebinding-title}. These values are based on the backing service CR.
 <2> Name of the `Secret` resource generated by the {servicebinding-title}.
 
+[id="configuring-custom-location-of-secret-path_{context}"]
 == Configuring the custom location of the secret path
+This custom location is available for the `binding.operators.coreos.com` API group when {servicebinding-title} projects the binding data as environment variables.
+
 Consider a secondary workload CR, which is not compliant with the PodSpec, with only the secret at the `spec.secret` path:
 
 .Example: Secondary workload CR
@@ -154,4 +159,68 @@ spec:
     secret: binding-request-72ddc0c540ab3a290e138726940591debf14c581 <1>
 ...
 ----
-<1> Unique name of the `Secret` resource generated by the {servicebinding-title}.
+<1> The unique name of the `Secret` resource that {servicebinding-title} generates.
+
+[id="workload-resource-mapping_{context}"]
+== 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`.
+* You must define `ClusterWorkloadResourceMapping` resources only under the `servicebinding.io` API group. However, the `ClusterWorkloadResourceMapping` resources interact with `ServiceBinding` resources under both the `binding.operators.coreos.com` and `servicebinding.io` API groups.
+====
+
+If you cannot configure custom path locations by using the configuration method for container path, you can define exactly where binding data needs to be projected. Specify where to project the binding data for a given workload kind by defining the `ClusterWorkloadResourceMapping` resources in the `servicebinding.io` API group.
+
+The following example shows how to define a mapping for the `CronJob.batch/v1` resources.
+
+.Example: Mapping for `CronJob.batch/v1` resources
+[source,yaml]
+----
+apiVersion: servicebinding.io/v1alpha3
+kind: ClusterWorkloadResourceMapping
+metadata:
+ name: cronjobs.batch <1>
+spec:
+  versions:
+  - version: "v1" <2>
+    annotations: .spec.jobTemplate.spec.template.metadata.annotations <3>
+    containers:
+    - path: .spec.jobTemplate.spec.template.spec.containers[*] <4>
+    - path: .spec.jobTemplate.spec.template.spec.initContainers[*]
+      name: .name <5>
+      env: .env <6>
+      volumeMounts: .volumeMounts <7>
+    volumes: .spec.jobTemplate.spec.template.spec.volumes <8>
+----
+<1> Name of the `ClusterWorkloadResourceMapping` resource, which must be qualified as the `plural.group` of the mapped workload resource.
+<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> Identifier of the `.containers` and `.initContainers` fields in a pod, specified with a JSONPath. If no entries under the `containers` field 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. However, if you specify an entry, then you must define the `.path` field.
+<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 not accepted.
+
+* Most of these fields are optional. When they are not specified, the {servicebinding-title} assumes defaults compatible with `PodSpec` 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}.
+====
+
+.Behavior specific to the `binding.operators.coreos.com` API group
+You can expect the following behaviors when `ClusterWorkloadResourceMapping` resources interact with `ServiceBinding` resources under 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 a `ClusterWorkloadResourceMapping` resource and the `.spec.application.bindingPath.containersPath` field. 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.

modules/sbo-methods-of-exposing-binding-data.adoc

@@ -101,7 +101,7 @@ spec:
     apiVersion: example.com/v1alpha1
     kind: AccountService
     name: prod-account-service
-  application:
+  workload:
     apiVersion: apps/v1
     kind: Deployment
     name: spring-petclinic