Merge pull request #39283 from Srivaralakshmi/ExamplesSBOExposing

Document changes to annotation examples

Author: Preeticp

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

@@ -23,10 +23,27 @@ metadata:
 ----
 
 
+== Exposing a constant value as the binding item
+The following examples show how to expose a constant value from the `PostgresCluster` custom resource (CR):
+
+.Example: Exposing a constant value
+[source,yaml]
+----
+apiVersion: postgres-operator.crunchydata.com/v1beta1
+kind: PostgresCluster
+metadata:
+  name: hippo
+  namespace: my-postgresql
+  annotations:
+    "service.binding/type": "postgresql" <1>
+----
+<1> Binding `type` to be exposed with the `postgresql` value.
+
+
 == Exposing an entire config map or secret that is referenced from a resource
-The following examples show how to expose an entire secret as annotations:
+The following examples show how to expose an entire secret through annotations:
 
-.Example: Exposing an entire secret as annotations
+.Example: Exposing an entire secret through annotations
 [source,yaml]
 ----
 apiVersion: postgres-operator.crunchydata.com/v1beta1
@@ -50,9 +67,9 @@ data:
   user: "Z3Vlc3Q="
 ----
 
-The following example shows how to expose an entire config map as OLM descriptors:
+The following example shows how to expose an entire config map through OLM descriptors:
 
-.Example: Exposing an entire config map as OLM descriptors
+.Example: Exposing an entire config map through OLM descriptors
 [source,yaml]
 ----
 - path: data.dbConfiguration
@@ -67,9 +84,9 @@ If you intend to project all the values from a `ConfigMap` service resource, you
 
 
 == 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 as annotations:
+The following examples show how to expose a specific entry from a config map through annotations:
 
-.Example: Exposing an entry from a config map as annotations
+.Example: Exposing an entry from a config map through annotations
 [source,yaml]
 ----
 apiVersion: postgres-operator.crunchydata.com/v1beta1
@@ -94,9 +111,9 @@ data:
   user: "hippo"
 ----
 
-The following example shows how to expose a specific entry from a config map as OLM descriptors:
+The following example shows how to expose a specific entry from a config map through OLM descriptors:
 
-.Example: Exposing an entry from a config map as OLM descriptors
+.Example: Exposing an entry from a config map through OLM descriptors
 [source,yaml]
 ----
 - path: data.dbConfiguration
@@ -107,14 +124,14 @@ The following example shows how to expose a specific entry from a config map as
 
 This example uses the `path` attribute with an `X-Descriptors` update for `service.binding` and `sourceKey` by providing the following information:
 
-* Name of the binding key that is to be injected
+* Name of the binding key that is to be projected
 * Name of the key in the Secret service resource
 
 
 == Exposing a resource definition value
-The following example shows how to expose a resource definition value as annotations:
+The following example shows how to expose a resource definition value through annotations:
 
-.Example: Exposing a resource definition value as annotations
+.Example: Exposing a resource definition value through annotations
 [source,yaml]
 ----
 apiVersion: postgres-operator.crunchydata.com/v1beta1
@@ -127,9 +144,9 @@ metadata:
     ...
 ----
 
-The following example shows how to expose a resource definition value as OLM descriptors:
+The following example shows how to expose a resource definition value through OLM descriptors:
 
-.Example: Exposing  a resource definition value as OLM descriptors
+.Example: Exposing a resource definition value through OLM descriptors
 [source,yaml]
 ----
 - path: data.connectionURL
@@ -143,9 +160,9 @@ If required values are available as attributes of backing service resources, ann
 
 
 == Exposing entries of a collection with the key and value from each entry
-Following is the example for exposing the entries of a collection with the key and value from each entry as annotations:
+The following example shows how to expose the entries of a collection with the key and value from each entry through annotations:
 
-.Example: Exposing the entries of a collection as annotations
+.Example: Exposing the entries of a collection through annotations
 [source,yaml]
 ----
 apiVersion: postgres-operator.crunchydata.com/v1beta1
@@ -176,9 +193,9 @@ The following example shows how the previous entries of a collection in annotati
 /bindings/<binding-name>/uri_404 => black-hole.example.com
 ----
 
-Following is the example for exposing the entries of a collection with the key and value from each entry as OLM descriptors:
+The following example shows how to expose the entries of a collection with the key and value from each entry through OLM descriptors:
 
-.Example: Exposing the entries of a collection as OLM descriptors
+.Example: Exposing the entries of a collection through OLM descriptors
 [source,yaml]
 ----
 - path: bootstrap
@@ -206,9 +223,9 @@ The previous example helps you to project all those values with keys such as `pr
 
 
 == Exposing items of a collection with one key per item
-Following is the example for exposing the items of a collection with one key per item as annotations:
+The following example shows how to expose the items of a collection with one key per item through annotations:
 
-.Example: Exposing the items of a collection as annotations
+.Example: Exposing the items of a collection through annotations
 [source,yaml]
 ----
 apiVersion: postgres-operator.crunchydata.com/v1beta1
@@ -234,9 +251,9 @@ The following example shows how the previous items of a collection in annotation
 /bindings/<binding-name>/tags_2 => power
 ----
 
-Following is the example for exposing the items of a collection with one key per item as OLM descriptors:
+The following example shows how to expose the items of a collection with one key per item through OLM descriptors:
 
-.Example: Exposing the items of a collection as OLM descriptors
+.Example: Exposing the items of a collection through OLM descriptors
 [source,yaml]
 ----
 - path: spec.tags
@@ -257,9 +274,9 @@ spec:
 
 
 == Exposing values of collection entries with one key per entry value
-Following is the example for exposing the values of collection entries with one key per entry value as annotations:
+The following example shows how to expose the values of collection entries with one key per entry value through annotations:
 
-.Example: Exposing the values of collection entries as annotations
+.Example: Exposing the values of collection entries through annotations
 [source,yaml]
 ----
 apiVersion: postgres-operator.crunchydata.com/v1beta1
@@ -288,9 +305,9 @@ The following example shows how the previous values of a collection in annotatio
 /bindings/<binding-name>/url_2 => black-hole.example.com
 ----
 
-Following is the example for exposing the values of collection entries with one key per entry value as OLM descriptors:
+The following example shows how to expose the values of collection entries with one key per entry value through OLM descriptors:
 
-.Example: Exposing the values of collection entries as OLM descriptors
+.Example: Exposing the values of collection entries through OLM descriptors
 [source,yaml]
 ----
 - path: bootstrap

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

@@ -16,8 +16,8 @@ The service you intend to connect to is compliant with the Service Binding speci
 You must expose the binding data from the backing service. Depending on your workload requirements and environment, you can choose any of the following methods to expose the binding data:
 +
 ** Direct secret reference
-** Generation of an intermediate secret through custom resource definition (CRD) or CR annotations
-** Generation of an intermediate secret through Operator Lifecycle Manager (OLM) descriptors
+** Declaring binding data through custom resource definition (CRD) or CR annotations
+** Declaring binding data through Operator Lifecycle Manager (OLM) descriptors
 ** Detection of binding data through owned resources
 
 == Provisioned service
@@ -143,7 +143,7 @@ You can use this method to annotate the resources of the backing service to expo
 
 The following examples show the annotations that are added under the `metadata` section and a referenced `ConfigMap` object from a resource:
 
-.Example: Exposing binding data from a `Secret` object in the `metadata.annotations.dbsecret` custom field
+.Example: Exposing binding data from a `Secret` object defined in the CR annotations
 [source,yaml]
 ----
 apiVersion: postgres-operator.crunchydata.com/v1beta1
@@ -156,7 +156,21 @@ metadata:
     ...
 ----
 
-.Example: Exposing binding data from a `ConfigMap` object in the `metadata.annotations.dbconfig` custom field
+The previous example places the name of the secret name in the `{.metadata.name}-pguser-{.metadata.name}` template that resolves to `hippo-pguser-hippo`. The template can contain multiple JSONPath expressions.
+
+.Example: Referenced `Secret` object from a resource
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: hippo-pguser-hippo
+data:
+  password: "MTBz"
+  user: "Z3Vlc3Q="
+----
+
+.Example: Exposing binding data from a `ConfigMap` object defined in the CR annotations
 [source,yaml]
 ----
 apiVersion: postgres-operator.crunchydata.com/v1beta1
@@ -169,7 +183,7 @@ metadata:
     ...
 ----
 
-The previous example places the name of the config map in the `metadata.annotations.dbconfig` custom field and specifies to expose a single key from the config map.
+The previous example places the name of the config map in the `{.metadata.name}-config` template that resolves to `hippo-config`. The template can contain multiple JSONPath expressions.
 
 .Example: Referenced `ConfigMap` object from a resource
 [source,yaml]