Skip to content

Commit f984b9c

Browse files
PreeticpPreeticp
authored
Merge pull request #36310 from Srivaralakshmi/SBO-expose-project-bindingmetadata
Document for Exposing binding data
2 parents 08d72d8 + 8ea90d0 commit f984b9c

File tree

5 files changed

+575
-1
lines changed

5 files changed

+575
-1
lines changed

‎_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1614,6 +1614,8 @@ Topics:
16141614
File: installing-sbo
16151615
- Name: Getting started with service binding
16161616
File: getting-started-with-service-binding
1617+
- Name: Exposing binding data from a service
1618+
File: exposing-binding-data-from-a-service
16171619
- Name: Connecting an application to a service using the Developer perspective
16181620
File: odc-connecting-an-application-to-a-service-using-the-developer-perspective
16191621
- Name: Projecting binding data

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[id="exposing-binding-data-from-a-service"]
2+
= Exposing binding data from a service
3+
include::modules/common-attributes.adoc[]
4+
include::modules/servicebinding-document-attributes.adoc[]
5+
:context: exposing-binding-data-from-a-service
6+
7+
toc::[]
8+
9+
Application developers need access to backing services to build and connect workloads. Connecting workloads to backing services is always a challenge because each service provider requires a different way to access their secrets and consume them in a workload.
10+
11+
The {servicebinding-title} enables application developers to easily bind workloads together with operator-managed backing services, without any manual procedures to configure the binding connection. For the {servicebinding-title} to provide the binding data, as an Operator provider or user who creates backing services, you must expose the binding data to be automatically detected by the {servicebinding-title}. Then, the {servicebinding-title} automatically collects the binding data from the backing service and shares it with a workload to provide a consistent and predictable experience.
12+
13+
include::modules/sbo-methods-of-exposing-binding-data.adoc[leveloffset=+1]
14+
15+
include::modules/sbo-categories-of-exposable-binding-data.adoc[leveloffset=+1]
16+
17+
== Additional resources
18+
//Commenting out the link to avoid Build errors. The entire SBO section is new with topics. Links will work fine when all the SBO doc PRs will be merged.
19+
* link:https://github.com/openshift/console/blob/master/frontend/packages/operator-lifecycle-manager/src/components/descriptors/reference/reference.md[OLM Descriptor Reference].
20+
* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-generating-csvs[Defining cluster service versions (CSVs)].
21+
* Projecting binding data.

‎applications/odc-viewing-application-composition-using-topology-view.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ include::modules/odc-removing-services-from-application.adoc[leveloffset=+1]
3030

3131
include::modules/odc-labels-and-annotations-used-for-topology-view.adoc[leveloffset=+1]
3232

33-
.Additional resources
33+
== Additional resources
3434

3535
* See xref:../applications/creating_applications/odc-creating-applications-using-developer-perspective.adoc#odc-importing-codebase-from-git-to-create-application_odc-creating-applications-using-developer-perspective[Importing a codebase from Git to create an application] for more information on creating an application from Git.
3636
* See Connecting an application to a service using the Developer perspective.

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

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
[id="sbo-categories-of-exposable-binding-data_{context}"]
2+
= Categories of exposable binding data
3+
4+
The {servicebinding-title} enables you to expose the binding data values from the backing service resources and custom resource definitions (CRDs).
5+
6+
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.
7+
8+
9+
== Exposing a string from a resource
10+
The following example shows how to expose the string from the `metadata.name` field of the `PostgresCluster` custom resource (CR) as a username:
11+
12+
.Example
13+
[source,yaml]
14+
----
15+
apiVersion: postgres-operator.crunchydata.com/v1beta1
16+
kind: PostgresCluster
17+
metadata:
18+
name: hippo
19+
namespace: my-postgresql
20+
annotations:
21+
service.binding/username: path={.metadata.name}
22+
...
23+
----
24+
25+
26+
== Exposing an entire config map or secret that is referenced from a resource
27+
The following examples show how to expose an entire secret as annotations:
28+
29+
.Example: Exposing an entire secret as annotations
30+
[source,yaml]
31+
----
32+
apiVersion: postgres-operator.crunchydata.com/v1beta1
33+
kind: PostgresCluster
34+
metadata:
35+
name: hippo
36+
namespace: my-postgresql
37+
annotations:
38+
service.binding: 'path={.metadata.name}-pguser-{.metadata.name},objectType=Secret'
39+
----
40+
41+
.Example: The referenced secret from the backing service resource
42+
[source,yaml]
43+
----
44+
apiVersion: v1
45+
kind: Secret
46+
metadata:
47+
name: hippo-pguser-hippo
48+
data:
49+
password: "MTBz"
50+
user: "Z3Vlc3Q="
51+
----
52+
53+
The following example shows how to expose an entire config map as OLM descriptors:
54+
55+
.Example: Exposing an entire config map as OLM descriptors
56+
[source,yaml]
57+
----
58+
- path: data.dbConfiguration
59+
x-descriptors:
60+
- urn:alm:descriptor:io.kubernetes:ConfigMap
61+
- service.binding
62+
----
63+
64+
This example uses the `path` attribute with a `urn:alm:descriptor:io.kubernetes:ConfigMap` entry to indicate that the path points to the `ConfigMap` service resource.
65+
66+
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.
67+
68+
69+
== Exposing a specific entry from a config map or secret that is referenced from a resource
70+
The following examples show how to expose a specific entry from a config map as annotations:
71+
72+
.Example: Exposing an entry from a config map as annotations
73+
[source,yaml]
74+
----
75+
apiVersion: postgres-operator.crunchydata.com/v1beta1
76+
kind: PostgresCluster
77+
metadata:
78+
name: hippo
79+
namespace: my-postgresql
80+
annotations:
81+
service.binding: 'path={.metadata.name}-config,objectType=ConfigMap,sourceKey=user'
82+
----
83+
84+
.Example: The referenced config map from the backing service resource
85+
The binding data should have a key with name as `db_timeout` and value as `10s`:
86+
[source,yaml]
87+
----
88+
apiVersion: v1
89+
kind: ConfigMap
90+
metadata:
91+
name: hippo-config
92+
data:
93+
db_timeout: "10s"
94+
user: "hippo"
95+
----
96+
97+
The following example shows how to expose a specific entry from a config map as OLM descriptors:
98+
99+
.Example: Exposing an entry from a config map as OLM descriptors
100+
[source,yaml]
101+
----
102+
- path: data.dbConfiguration
103+
x-descriptors:
104+
- urn:alm:descriptor:io.kubernetes:ConfigMap
105+
- service.binding:my_certificate:sourceKey=certificate
106+
----
107+
108+
This example uses the `path` attribute with an `X-Descriptors` update for `service.binding` and `sourceKey` by providing the following information:
109+
110+
* Name of the binding key that is to be injected
111+
* Name of the key in the Secret service resource
112+
113+
114+
== Exposing a resource definition value
115+
The following example shows how to expose a resource definition value as annotations:
116+
117+
.Example: Exposing a resource definition value as annotations
118+
[source,yaml]
119+
----
120+
apiVersion: postgres-operator.crunchydata.com/v1beta1
121+
kind: PostgresCluster
122+
metadata:
123+
name: hippo
124+
namespace: my-postgresql
125+
annotations:
126+
service.binding/username: path={.metadata.name}
127+
...
128+
----
129+
130+
The following example shows how to expose a resource definition value as OLM descriptors:
131+
132+
.Example: Exposing a resource definition value as OLM descriptors
133+
[source,yaml]
134+
----
135+
- path: data.connectionURL
136+
x-descriptors:
137+
- service.binding:uri
138+
----
139+
140+
The previous example uses the `connectionURL` attribute that points to the required resource definition value that is to be projected as `uri`.
141+
142+
If required values are available as attributes of backing service resources, annotating these values using `X-Descriptors` identifies them as the binding data.
143+
144+
145+
== Exposing entries of a collection with the key and value from each entry
146+
Following is the example for exposing the entries of a collection with the key and value from each entry as annotations:
147+
148+
.Example: Exposing the entries of a collection as annotations
149+
[source,yaml]
150+
----
151+
apiVersion: postgres-operator.crunchydata.com/v1beta1
152+
kind: PostgresCluster
153+
metadata:
154+
name: hippo
155+
namespace: my-postgresql
156+
annotations:
157+
"service.binding/uri": "path={.status.connections},elementType=sliceOfMaps,sourceKey=type,sourceValue=url"
158+
spec:
159+
...
160+
status:
161+
connections:
162+
- type: primary
163+
url: primary.example.com
164+
- type: secondary
165+
url: secondary.example.com
166+
- type: '404'
167+
url: black-hole.example.com
168+
----
169+
170+
The following example shows how the previous entries of a collection in annotations are projected into the bound application.
171+
172+
.Example: Binding data files
173+
----
174+
/bindings/<binding-name>/uri_primary => primary.example.com
175+
/bindings/<binding-name>/uri_secondary => secondary.example.com
176+
/bindings/<binding-name>/uri_404 => black-hole.example.com
177+
----
178+
179+
Following is the example for exposing the entries of a collection with the key and value from each entry as OLM descriptors:
180+
181+
.Example: Exposing the entries of a collection as OLM descriptors
182+
[source,yaml]
183+
----
184+
- path: bootstrap
185+
x-descriptors:
186+
- service.binding:endpoints:elementType=sliceOfMaps:sourceKey=type:sourceValue=url
187+
----
188+
189+
The previous example uses the `path` attribute with an `X-Descriptors` update for the required entries of a collection.
190+
191+
.Example: Configuration from a backing service resource
192+
[source,yaml]
193+
----
194+
status:
195+
connections:
196+
- type: primary
197+
url: primary.example.com
198+
- type: secondary
199+
url: secondary.example.com
200+
- type: '404'
201+
url: black-hole.example.com
202+
----
203+
204+
The previous example helps you to project all those values with keys such as `primary`,
205+
`secondary`, and so on.
206+
207+
208+
== Exposing items of a collection with one key per item
209+
Following is the example for exposing the items of a collection with one key per item as annotations:
210+
211+
.Example: Exposing the items of a collection as annotations
212+
[source,yaml]
213+
----
214+
apiVersion: postgres-operator.crunchydata.com/v1beta1
215+
kind: PostgresCluster
216+
metadata:
217+
name: hippo
218+
namespace: my-postgresql
219+
annotations:
220+
"service.binding/tags": "path={.spec.tags},elementType=sliceOfStrings"
221+
spec:
222+
tags:
223+
- knowledge
224+
- is
225+
- power
226+
----
227+
228+
The following example shows how the previous items of a collection in annotations are projected into the bound application.
229+
230+
.Example: Binding data files
231+
----
232+
/bindings/<binding-name>/tags_0 => knowledge
233+
/bindings/<binding-name>/tags_1 => is
234+
/bindings/<binding-name>/tags_2 => power
235+
----
236+
237+
Following is the example for exposing the items of a collection with one key per item as OLM descriptors:
238+
239+
.Example: Exposing the items of a collection as OLM descriptors
240+
[source,yaml]
241+
----
242+
- path: spec.tags
243+
x-descriptors:
244+
- service.binding:tags:elementType=sliceOfStrings
245+
----
246+
247+
The previous example uses the `path` attribute with an `X-Descriptors` update for the required items of a collection.
248+
249+
.Example: Configuration from a backing service resource
250+
----
251+
spec:
252+
tags:
253+
- knowledge
254+
- is
255+
- power
256+
----
257+
258+
259+
== Exposing values of collection entries with one key per entry value
260+
Following is the example for exposing the values of collection entries with one key per entry value as annotations:
261+
262+
.Example: Exposing the values of collection entries as annotations
263+
[source,yaml]
264+
----
265+
apiVersion: postgres-operator.crunchydata.com/v1beta1
266+
kind: PostgresCluster
267+
metadata:
268+
name: hippo
269+
namespace: my-postgresql
270+
annotations:
271+
"service.binding/url": "path={.spec.connections},elementType=sliceOfStrings,sourceValue=url"
272+
spec:
273+
connections:
274+
- type: primary
275+
url: primary.example.com
276+
- type: secondary
277+
url: secondary.example.com
278+
- type: '404'
279+
url: black-hole.example.com
280+
----
281+
282+
The following example shows how the previous values of a collection in annotations are projected into the bound application.
283+
284+
.Example: Binding data files
285+
----
286+
/bindings/<binding-name>/url_0 => primary.example.com
287+
/bindings/<binding-name>/url_1 => secondary.example.com
288+
/bindings/<binding-name>/url_2 => black-hole.example.com
289+
----
290+
291+
Following is the example for exposing the values of collection entries with one key per entry value as OLM descriptors:
292+
293+
.Example: Exposing the values of collection entries as OLM descriptors
294+
[source,yaml]
295+
----
296+
- path: bootstrap
297+
x-descriptors:
298+
- service.binding:endpoints:elementType=sliceOfStrings:sourceValue=url
299+
----

0 commit comments

Comments
 (0)