Document Optional annotation feature

Fixing SME review comments

Fixing QE review comments

Fixing peer review comments

updates to add Anchoring IDs in module files and for Additional resources titles in assembly

Author: Srivaralakshmi

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

@@ -14,9 +14,12 @@ 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-setting-annotations-mapping-optional.adoc[leveloffset=+1]
 include::modules/sbo-rbac-requirements.adoc[leveloffset=+1]
 include::modules/sbo-categories-of-exposable-binding-data.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
+[id="additional-resources_exposing-binding-data"]
 == Additional resources
 * link:https://github.com/openshift/console/blob/master/frontend/packages/operator-lifecycle-manager/src/components/descriptors/reference/reference.md[OLM Descriptor Reference].
 * xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-generating-csvs[Defining cluster service versions (CSVs)].

modules/sbo-categories-of-exposable-binding-data.adoc

@@ -11,7 +11,7 @@ The {servicebinding-title} enables you to expose the binding data values from th
 
 This section provides examples to show how you can use the various categories of exposable binding data. You must modify these examples to suit your work environment and requirements.
 
-
+[id="exposing-a-string-from-a-resource_{context}"]
 == Exposing a string from a resource
 The following example shows how to expose the string from the `metadata.name` field of the `PostgresCluster` custom resource (CR) as a username:
 
@@ -28,7 +28,7 @@ metadata:
     ...
 ----
 
-
+[id="exposing-a-constant-value-as-the-binding-item_{context}"]
 == Exposing a constant value as the binding item
 The following examples show how to expose a constant value from the `PostgresCluster` custom resource (CR):
 
@@ -45,7 +45,7 @@ metadata:
 ----
 <1> Binding `type` to be exposed with the `postgresql` value.
 
-
+[id="exposing-an-entire-config-map-or-secret-that-is-referenced-from-a-resource_{context}"]
 == Exposing an entire config map or secret that is referenced from a resource
 The following examples show how to expose an entire secret through annotations:
 
@@ -88,7 +88,7 @@ This example uses the `path` attribute with a `urn:alm:descriptor:io.kubernetes:
 
 If you intend to project all the values from a `ConfigMap` service resource, you must specify it as an attribute in the backing service CR. For example, if the attribute is part of the `.spec` section, you can create and use a `specDescriptors` array. Or, if the attribute is part of the `.status` section, you can create and use a `statusDescriptors` array.
 
-
+[id="exposing-a-specific-entry-from-a-config-map-or-secret-that-is-referenced-from-a-resource_{context}"]
 == Exposing a specific entry from a config map or secret that is referenced from a resource
 The following examples show how to expose a specific entry from a config map through annotations:
 
@@ -133,7 +133,7 @@ This example uses the `path` attribute with an `X-Descriptors` update for `servi
 * Name of the binding key that is to be projected
 * Name of the key in the Secret service resource
 
-
+[id="exposing-a-resource-definition-value_{context}"]
 == Exposing a resource definition value
 The following example shows how to expose a resource definition value through annotations:
 
@@ -164,7 +164,7 @@ The previous example uses the `connectionURL` attribute that points to the requi
 
 If required values are available as attributes of backing service resources, annotating these values using `X-Descriptors` identifies them as the binding data.
 
-
+[id="exposing-entries-of-a-collection-with-the-key-and-value-from-each-entry_{context}"]
 == Exposing entries of a collection with the key and value from each entry
 The following example shows how to expose the entries of a collection with the key and value from each entry through annotations:
 
@@ -228,7 +228,7 @@ status:
 The previous example helps you to project all those values with keys such as `primary`,
 `secondary`, and so on.
 
-
+[id="exposing-items-of-a-collection-with-one-key-per-item_{context}"]
 == Exposing items of a collection with one key per item
 The following example shows how to expose the items of a collection with one key per item through annotations:
 
@@ -281,7 +281,7 @@ spec:
   - power
 ----
 
-
+[id="exposing-values-of-collection-entries-with-one-key-per-entry-value_{context}"]
 == Exposing values of collection entries with one key per entry value
 The following example shows how to expose the values of collection entries with one key per entry value through annotations:
 

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

@@ -26,6 +26,7 @@ You must expose the binding data from the backing service. Depending on your wor
 ** Declaring binding data through Operator Lifecycle Manager (OLM) descriptors
 ** Detection of binding data through owned resources
 
+[id="provisioned-service_{context}"]
 == Provisioned service
 Provisioned service represents a backing service CR with a reference to a `Secret` resource placed in the `.status.binding.name` field of the backing service CR.
 
@@ -109,7 +110,7 @@ spec:
 
 This method exposes all the keys in the `hippo-pguser-hippo` referenced `Secret` resource as binding data that is to be projected into the workload.
 
-
+[id="direct-secret-reference_{context}"]
 == Direct secret reference
 You can use this method, if all the required binding data values are available in a `Secret` resource that you can reference in your Service Binding definition. In this method, a `ServiceBinding` resource directly references a `Secret` resource to connect to a service. All the keys in the `Secret` resource are exposed as binding data.
 
@@ -144,6 +145,7 @@ spec:
     name: hippo-pguser-hippo
 ----
 
+[id="declaring-binding-data-through-CRD-or-CR-annotations_{context}"]
 == Declaring binding data through CRD or CR annotations
 You can use this method to annotate the resources of the backing service to expose the binding data with specific annotations. Adding annotations under the `metadata` section alters the CRs and CRDs of the backing services. {servicebinding-title} detects the annotations added to the CRs and CRDs and then creates a `Secret` resource with the values extracted based on the annotations.
 
@@ -203,7 +205,7 @@ data:
   user: "hippo"
 ----
 
-
+[id="declaring-binding-data-through-olm-descriptors_{context}"]
 == Declaring binding data through OLM descriptors
 You can use this method if your backing service is provided by an Operator. If your Operator is distributed as an OLM bundle, you can add OLM descriptors to describe the binding data that is to be exposed. The OLM descriptors are part of Cluster Service Version resources. The {servicebinding-title} detects the OLM descriptors and then creates a `Secret` resource with the values extracted based on the detected OLM descriptors.
 
@@ -240,6 +242,7 @@ The following examples show how to define an X-Descriptor depending on the resou
 * The absence of the `Secret` or `ConfigMap` specific X-Descriptors indicates that the descriptor is referencing the binding data value at the given path.
 ====
 
+[id="detection-of-binding-data-through-owned-resources_{context}"]
 == Detection of binding data through owned resources
 You can use this method if your backing service owns one or more Kubernetes resources such as route, service, config map, or secret that you can use to detect the binding data. In this method, the {servicebinding-title} detects the binding data from resources owned by the backing service CR.
 

modules/sbo-setting-annotations-mapping-optional.adoc

@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc
+
+:_content-type: PROCEDURE
+[id="sbo-setting-annotations-mapping-optional_{context}"]
+= Setting annotations mapping to be optional
+
+You can have optional fields in the annotations. For example, a path to the credentials might not be present if the service endpoint does not require authentication. In such cases, a field might not exist in the target path of the annotations. As a result, {servicebinding-title} generates an error, by default. 
+
+As a service provider, to indicate whether you require annotations mapping, you can set a value for the `optional` flag in your annotations when enabling services. {servicebinding-title} provides annotations mapping only if the target path is available. When the target path is not available, the {servicebinding-title} skips the optional mapping and continues with the projection of the existing mappings without throwing any errors.
+
+.Procedure
+
+* To make a field in the annotations optional, set the `optional` flag value to `true`:
++
+.Example
+[source,yaml]
+----
+apiVersion: apps.example.org/v1beta1
+kind: Database
+metadata:
+  name: my-db
+  namespace: my-petclinic
+  annotations:
+    service.binding/username: path={.spec.name},optional=true
+    ...
+----
+
+[NOTE]
+====
+* If you set the `optional` flag value to `false` and the {servicebinding-title} is unable to find the target path, the Operator fails the annotations mapping.
+* If the `optional` flag has no value set, the {servicebinding-title} considers the value as `false` by default and fails the annotations mapping. 
+====