Merge pull request #40086 from Srivaralakshmi/SBO_RBAC

Document RBAC requirements and fix section title levels

Author: Preeticp

applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc

@@ -12,6 +12,7 @@ The {servicebinding-title} enables application developers to easily bind workloa
 
 include::modules/sbo-methods-of-exposing-binding-data.adoc[leveloffset=+1]
 include::modules/sbo-data-model.adoc[leveloffset=+1]
+include::modules/sbo-rbac-requirements.adoc[leveloffset=+1]
 include::modules/sbo-categories-of-exposable-binding-data.adoc[leveloffset=+1]
 
 == Additional resources

modules/sbo-advanced-binding-options.adoc

@@ -7,8 +7,8 @@
 
 Advanced binding options are available only for the `binding.operators.coreos.com` API group.
 
-=== Changing the binding names before projecting 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 host and port fields of the database are exposed by the the PostgreSQL database service to use for binding. The Spring PetClinic sample application can access this exposed binding data through the binding names.
+== 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.
 
 .Example: Spring PetClinic sample application in the `ServiceBinding` CR
 [source,yaml]
@@ -63,7 +63,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.
 
-=== Composing custom binding data
+== Composing custom binding data
 As an application developer, you can compose custom binding data under the following circumstances:
 
 * The backing service does not expose binding data.

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

@@ -11,7 +11,7 @@ For such secondary workload resources, the location of the container path is arb
 
 {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.
 
-=== Configuring the custom location of the container path
+== Configuring the custom location of the container path
 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
@@ -95,7 +95,7 @@ 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}.
 
-=== Configuring the custom location of the secret path
+== Configuring the custom location of the secret path
 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

modules/sbo-rbac-requirements.adoc

@@ -0,0 +1,40 @@
+// Module included in the following assemblies:
+//
+// *openshift-docs/applications/connecting_applications_to_services/exposing-binding-data-from-a-service
+[id="sbo-rbac-requirements_{context}"]
+= RBAC requirements
+
+To expose the backing service binding data using the {servicebinding-title}, you require certain Role-based access control (RBAC) permissions. Specify certain verbs under the `rules` field of the `ClusterRole` resource to grant the RBAC permissions for the backing service resources. When you define these `rules`, you allow the {servicebinding-title} to read the binding data of the backing service resources throughout the cluster.
+
+The {servicebinding-title} performs requests against the Kubernetes API using a dedicated service account. By default, this account has permissions to bind services to workloads, both represented by the following standard Kubernetes or OpenShift objects:
+
+* `Deployments`
+* `DaemonSets`
+* `ReplicaSets`
+* `StatefulSets`
+* `DeploymentConfigs`
+
+The Operator service account is bound to an aggregated cluster role, allowing Operator providers or cluster administrators to enable binding custom service resources to workloads. To grant the required permissions within a `ClusterRole`, label it with the `servicebinding.io/controller` flag and set the flag value to `true`. The following example shows how to allow the {servicebinding-title} to `get`, `watch`, and `list` the custom resources (CRs) of Crunchy PostgreSQL Operator:
+
+.Example: Enable binding to PostgreSQL database instances provisioned by Crunchy PostgreSQL Operator
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: postgrescluster-reader
+  labels:
+     servicebinding.io/controller: "true"
+rules:
+- apiGroups:
+    - postgres-operator.crunchydata.com
+  resources:
+    - postgresclusters
+  verbs:
+    - get
+    - watch
+    - list
+  ...
+----
+
+This cluster role can be deployed during the installation of the backing service Operator.