Merge pull request #46026 from Srivaralakshmi/SBO_LabelSelector

RHDEVDOCS-4073 - Document on binding workloads using the label selector feature as per the spec 1.0

Author: JStickler

modules/sbo-advanced-binding-options.adoc

@@ -6,11 +6,15 @@
 [id="sbo-advanced-binding-options_{context}"]
 = Advanced binding options
 
-[role="_abstract"]
-Advanced binding options are available only for the `binding.operators.coreos.com` API group.
+You can define the `ServiceBinding` custom resource (CR) to use the following advanced binding options:
 
+* Changing binding names: This option is available only for the `binding.operators.coreos.com` API group.
+* Composing custom binding data: This option is available only for the `binding.operators.coreos.com` API group.
+* Binding workloads using label selectors: This option is available for both the `binding.operators.coreos.com` and `servicebinding.io` API groups.
+
+[id="changing-binding-names_{context}"]
 == Changing the binding names before projecting them into the workload
-You can specify the rules to change the binding names in the .spec.namingStrategy attribute of the `ServiceBinding` custom resource (CR). For example, consider a Spring PetClinic sample application that connects to the PostgreSQL database. In this case, the PostgreSQL database service exposes the host and port fields of the database to use for binding. The Spring PetClinic sample application can access this exposed binding data through the binding names.
+You can specify the rules to change the binding names in the `.spec.namingStrategy` attribute of the `ServiceBinding` CR. For example, consider a Spring PetClinic sample application that connects to the PostgreSQL database. In this case, the PostgreSQL database service exposes the `host` and `port` fields of the database to use for binding. The Spring PetClinic sample application can access this exposed binding data through the binding names.
 
 .Example: Spring PetClinic sample application in the `ServiceBinding` CR
 [source,yaml]
@@ -67,6 +71,7 @@ The following items describe the expressions defined in the `POSTGRESQL_{{ .serv
 
 Similar to the previous example, you can define the string templates in `namingStrategy` to define how each key of the binding names should be prepared by the service binding request.
 
+[id="composing-custom-binding-data_{context}"]
 == Composing custom binding data
 As an application developer, you can compose custom binding data under the following circumstances:
 
@@ -114,5 +119,65 @@ spec:
 ----
 <1> Name of the backing service resource.
 <2> Optional identifier.
-<3> Generated JSON name that is to be projected as the file content or environment value. The JSON name contains the attributes of the backing service custom resource.
-<4> Generated JSON value that is to be projected as the file content or environment value. The JSON value contains the attributes of the backing service custom resource.
+<3> The JSON name that the {servicebinding-title} generates. The {servicebinding-title} projects this JSON name as the name of a file or environment variable.
+<4> The JSON value that the {servicebinding-title} generates. The {servicebinding-title} projects this JSON value as a file or environment variable. The JSON value contains the attributes from your specified field of the backing service custom resource.
+
+[id="binding-workloads-using-a-label-selector_{context}"]
+== Binding workloads using a label selector
+You can use a label selector to specify the workload to bind. If you declare a service binding using the label selectors to pick up workloads, the {servicebinding-title} periodically attempts to find and bind new workloads that match the given label selector.
+
+For example, as a cluster administrator, you can bind a service to every `Deployment` in a namespace with the `environment: production` label by setting an appropriate `labelSelector` field in the `ServiceBinding` CR. This enables the {servicebinding-title} to bind each of these workloads with one `ServiceBinding` CR.
+
+.Example `ServiceBinding` CR in the `binding.operators.coreos.com/v1alpha1` API
+[source,yaml]
+----
+apiVersion: binding.operators.coreos.com/v1alpha1
+kind: ServiceBinding
+metadata:
+  name: multi-application-binding
+  namespace: service-binding-demo
+spec:
+  application:
+    labelSelector: <1>
+      matchLabels:
+        environment: production
+    group: apps
+    version: v1
+    resource: deployments
+  services:
+    group: ""
+    version: v1
+    kind: Secret
+    name: super-secret-data
+----
+<1> Specifies the workload that is being bound.
+
+.Example `ServiceBinding` CR in the `servicebinding.io` API
+[source,yaml]
+----
+apiVersion: servicebindings.io/v1alpha3
+kind: ServiceBinding
+metadata:
+  name: multi-application-binding
+  namespace: service-binding-demo
+spec:
+  workload:
+    selector: <1>
+      matchLabels:
+        environment: production
+    apiVersion: app/v1
+    kind: Deployment
+  service:
+    apiVersion: v1
+    kind: Secret
+    name: super-secret-data
+----
+<1> Specifies the workload that is being bound.
+
+[IMPORTANT]
+====
+If you define the following pairs of fields, {servicebinding-title} refuses the binding operation and generates an error:
+
+* The `name` and `labelSelector` fields in the `binding.operators.coreos.com/v1alpha1` API.
+* The `name` and `selector` fields in the `servicebinding.io` API (Spec API).
+====