openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-07 09:46:53 +01:00
Code Issues Releases Activity

Quick start updates, Example updates, and Updates to SBO topics for modular-docs template and content type attributes alignment

Browse Source 
Fixing review comments

Fixing some more review comments

Fixed the RBAC requirements topic

Updated note section

Fixing the note section

Fixing the output in the note section

Fix QE review comments
This commit is contained in:
Srivaralakshmi
2022-02-13 20:39:56 +05:30
parent fc1c824509
commit 2fd1d2a9a6
21 changed files with 202 additions and 210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc
View File

@@ -7,29 +7,27 @@ include::modules/servicebinding-document-attributes.adoc[]
toc::[]
[role="_abstract"]
Application developers must bind a workload to one or more backing services by using a binding secret. This secret is generated for the purpose of storing information to be consumed by the workload.
As an example, consider that the service you want to connect to is already exposing the binding data. In this case, you would also need a workload to be used along with the `ServiceBinding` custom resource (CR). By using this `ServiceBinding` CR, the workload sends a binding request with the details of the services to bind with.
.Example of `ServiceBinding` CR
[source,yaml]
----
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
name: spring-petclinic-rest
namespace: my-postgresql
name: spring-petclinic-pgcluster
namespace: my-petclinic
spec:
services: <1>
- group: postgres-operator.crunchydata.com
version: v1beta1
kind: PostgresCluster
name: hippo
- group: ""
version: v1
kind: Secret
name: hippo-pguser-hippo
application: <2>
name: spring-petclinic-rest
name: spring-petclinic
group: apps
version: v1
resource: deployments

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

@@ -7,6 +7,7 @@ include::modules/servicebinding-document-attributes.adoc[]
toc::[]
[role="_abstract"]
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.
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.

9
applications/connecting_applications_to_services/getting-started-with-service-binding.adoc
View File

@@ -7,6 +7,7 @@ include::modules/servicebinding-document-attributes.adoc[]
toc::[]
[role="_abstract"]
{servicebinding-title} manages the data plane for workloads and backing services. This guide provides instructions with examples to help you create a database instance, deploy an application, and use {servicebinding-title} to create a binding connection between the application and the database service.
// Prerequisites for getting started with Service Binding Operator
@@ -15,9 +16,13 @@ toc::[]
* You have access to an {product-title} cluster using an account with `cluster-admin` permissions.
* You have installed the `oc` CLI.
* You have installed PostgreSQL `psql` CLI.
* You have installed {servicebinding-title} from OperatorHub.
* You have installed the Crunchy Postgres for Kubernetes Operator from OperatorHub using the *v5* Update channel. The installed Operator is available in an appropriate namespace, such as the `my-postgresql` namespace.
* You have installed the Crunchy Postgres for Kubernetes Operator from OperatorHub using the *v5* Update channel. The installed Operator is available in an appropriate namespace, such as the `my-petclinic` namespace.
+
[NOTE]
====
You can create the namespace using the `oc create namespace my-petclinic` command.
====
//Creating a PostgreSQL database instance
include::modules/sbo-creating-a-postgresql-database-instance.adoc[leveloffset=+1]

1
applications/connecting_applications_to_services/installing-sbo.adoc
View File

@@ -7,6 +7,7 @@ include::modules/servicebinding-document-attributes.adoc[]
toc::[]
[role="_abstract"]
This guide walks cluster administrators through the process of installing the {servicebinding-title} to an {product-title} cluster.
You can install {servicebinding-title} on {product-title} 4.7 and later.

23
applications/connecting_applications_to_services/odc-connecting-an-application-to-a-service-using-the-developer-perspective.adoc
View File

@@ -5,6 +5,7 @@ include::modules/common-attributes.adoc[]
include::modules/servicebinding-document-attributes.adoc[]
:context: odc-connecting-an-application-to-a-service-using-the-developer-perspective
[role="_abstract"]
In addition to grouping multiple components within an application, you can also use the *Topology* view to connect components with each other. You can either use a binding connector or a visual one to connect components.
A binding connection between the components can be established only if the target node is an Operator-backed service. This is indicated by the *Create a binding connector* tool-tip which appears when you drag an arrow to such a target node. When an application is connected to a service using a binding connector a `ServiceBinding` resource is created. Then, the Service Binding Operator controller projects the necessary binding data into the application deployment. After the request is successful, the application is redeployed establishing an interaction between the connected components.
@@ -18,8 +19,8 @@ This procedure walks you through an example of creating a visual connection betw
.Prerequisites
* Ensure that you have created and deployed a Spring PetClinic sample application using the *Developer* perspective.
* Ensure that you have created and deployed a Crunchy PostgreSQL database instance using the *Developer* perspective. This instance has the following three components: `hippo-backup`, `hippo-instance`, and `hippo-pgbouncer`.
* You have created and deployed a Spring PetClinic sample application using the *Developer* perspective.
* You have created and deployed a Crunchy PostgreSQL database instance using the *Developer* perspective. This instance has the following four components: `hippo-backup`, `hippo-instance`, `hippo-repo-host`, and `hippo-pgbouncer`.
.Procedure
@@ -28,7 +29,7 @@ This procedure walks you through an example of creating a visual connection betw
.Visual connector
image::odc_connector.png[]
. Click and drag the arrow towards the `hippo-pgbouncer` deployment to connect the Spring PetClinic sample application with it.
. Click on the `spring-petclinic-rest` deployment to see the *Overview* panel. Under the *Details* tab, click the edit icon in the *Annotations* section to see the *Key = `app.openshift.io/connects-to`* and *Value = `[{"apiVersion":"apps/v1","kind":"Deployment","name":"hippo-pgbouncer"}]`* annotation added to the deployment.
. Click the `spring-petclinic` deployment to see the *Overview* panel. Under the *Details* tab, click the edit icon in the *Annotations* section to see the *Key = `app.openshift.io/connects-to`* and *Value = `[{"apiVersion":"apps/v1","kind":"Deployment","name":"hippo-pgbouncer"}]`* annotation added to the deployment.
Similarly you can create other applications and components and establish visual connections between them.
@@ -42,13 +43,13 @@ This procedure walks through an example of creating a binding connection between
The PostreSQL Database Operator then creates and manages the `Database` resource, which exposes the binding information in secrets, config maps, status, and spec attributes.
.Prerequisites
* Ensure that you have created and deployed a Spring PetClinic sample application using the *Developer* perspective.
* Ensure that you have installed the {servicebinding-title} from the OperatorHub.
* Ensure that you have installed the *Crunchy Postgres for Kubernetes* Operator from the OperatorHub using `v5` *Update* channel.
* Ensure that you have created and deployed a Crunchy PostgreSQL database instance using the *Developer* perspective. This instance has the following three components: `hippo-backup`, `hippo-instance`, and `hippo-pgbouncer`.
* You have created and deployed a Spring PetClinic sample application using the *Developer* perspective.
* You have installed the {servicebinding-title} from the OperatorHub.
* You have installed the *Crunchy Postgres for Kubernetes* Operator from the OperatorHub using `v5` *Update* channel.
* You have created and deployed a Crunchy PostgreSQL database instance using the *Developer* perspective. This instance has the following four components: `hippo-backup`, `hippo-instance`, `hippo-repo-host`, and `hippo-pgbouncer`.
.Procedure
. Switch to the *Developer* perspective and ensure that you are in the appropriate project, for example, `my-postgresql`. In the *Topology* view, hover over the Spring PetClinic sample application to see a dangling arrow on the node.
. Switch to the *Developer* perspective and ensure that you are in the appropriate project, for example, `my-petclinic`. In the *Topology* view, hover over the Spring PetClinic sample application to see a dangling arrow on the node.
. Click and drag the arrow towards the *hippo* database Postgres Cluster to make a binding connection with the Spring PetClinic sample application.
+
Alternatively, in the *+Add* view, click the *YAML* option to see the *Import YAML* screen. Use the YAML editor and add the `ServiceBinding` resource:
@@ -59,8 +60,8 @@ Alternatively, in the *+Add* view, click the *YAML* option to see the *Import YA
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
name: spring-petclinic-rest
namespace: my-postgresql
name: spring-petclinic-pgcluster
namespace: my-petclinic
spec:
services:
- group: postgres-operator.crunchydata.com
@@ -68,7 +69,7 @@ spec:
kind: PostgresCluster
name: hippo
application:
name: spring-petclinic-rest
name: spring-petclinic
group: apps
version: v1
resource: deployments

1
applications/connecting_applications_to_services/projecting-binding-data.adoc
View File

@@ -7,6 +7,7 @@ include::modules/servicebinding-document-attributes.adoc[]
toc::[]
[role="_abstract"]
This section provides information on how you can consume the binding data.
== Consumption of binding data

1
applications/connecting_applications_to_services/understanding-service-binding-operator.adoc
View File

@@ -8,6 +8,7 @@ include::modules/servicebinding-document-attributes.adoc[]
toc::[]
[role="_abstract"]
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 suggests a different way to access their secrets and consume them in a workload. In addition, manual configuration and maintenance of this binding together of workloads and backing services make the process tedious, inefficient, and error-prone.
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.

BIN
images/odc-binding-connector.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 189 KiB

After

Width:  |  Height:  |  Size: 95 KiB

BIN
images/odc_connecting_multiple_applications.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 214 KiB

After

Width:  |  Height:  |  Size: 119 KiB

BIN
images/odc_connector.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 175 KiB

After

Width:  |  Height:  |  Size: 102 KiB

13
modules/sbo-advanced-binding-options.adoc
View File

@@ -2,9 +2,11 @@
//
// * /applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc
:_content-type: CONCEPT
[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.
== Changing the binding names before projecting them into the workload
@@ -15,7 +17,7 @@ You can specify the rules to change the binding names in the .spec.namingStrateg
----
...
application:
name: spring-petclinic-rest
name: spring-petclinic
group: apps
version: v1
resource: deployments
@@ -37,6 +39,7 @@ You can specify the rules to change the binding names in the .spec.namingStrateg
If `namingStrategy` is not defined and the binding names are projected as environment variables, then the `host: hippo-pgbouncer` value in the backing service and the projected environment variable would appear as shown in the following example:
.Example
[source,yaml]
----
DATABASE_HOST: hippo-pgbouncer
----
@@ -48,6 +51,7 @@ where:
After applying the `POSTGRESQL_{{ .service.kind | upper }}_{{ .name | upper }}_ENV` naming strategy, the list of custom binding names prepared by the service binding request appears as shown in the following example:
.Example
[source,yaml]
----
POSTGRESQL_DATABASE_HOST_ENV: hippo-pgbouncer
POSTGRESQL_DATABASE_PORT_ENV: 5432
@@ -73,12 +77,13 @@ For example, consider a case where the backing service CR exposes the host, port
You can compose custom binding data using attributes in the Kubernetes resource representing the backing service.
.Example
[source,yaml]
----
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
name: spring-petclinic-rest
namespace: my-postgresql
name: spring-petclinic-pgcluster
namespace: my-petclinic
spec:
services:
- group: postgres-operator.crunchydata.com
@@ -92,7 +97,7 @@ spec:
name: hippo-pguser-hippo
id: postgresSecret
application:
name: spring-petclinic-rest
name: spring-petclinic
group: apps
version: v1
resource: deployments

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

@@ -2,12 +2,14 @@
//
// * /applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc
:_content-type: PROCEDURE
[id="sbo-binding-workloads-that-are-not-compliant-with-PodSpec_{context}"]
= Binding secondary workloads that are not compliant with PodSpec
[role="_abstract"]
A typical scenario in service binding involves configuring the backing service, the workload (Deployment), and {servicebinding-title}. Consider a scenario that involves a secondary workload (which can also be an application Operator) that is not compliant with PodSpec and is between the primary workload (Deployment) and {servicebinding-title}.
For such secondary workload resources, the location of the container path is arbitrary. For service binding, if the secondary workload in a CR is not compliant with the PodSpec, you must specify the location of the container path. Doing so projects the binding data into the container path specified in the secondary workload of the `ServiceBinding` CR, for example, when you do not want the binding data inside a pod.
For such secondary workload resources, the location of the container path is arbitrary. For service binding, if the secondary workload in a CR is not compliant with the PodSpec, you must specify the location of the container path. Doing so projects the binding data into the container path specified in the secondary workload of the `ServiceBinding` custom resource (CR), for example, when you do not want the binding data inside a pod.
{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.
@@ -26,18 +28,20 @@ spec:
- name: hello-world
image: quay.io/baijum/secondary-workload:latest
ports:
- containerPort: 9966
- containerPort: 8080
----
The following example shows how to configure the `spec.containers` path by specifying a value in the `ServiceBinding` CR and to bind this path to a `spec.application.bindingPath.containersPath` custom location:
[discrete]
.Procedure
* Configure the `spec.containers` path by specifying a value in the `ServiceBinding` CR and bind this path to a `spec.application.bindingPath.containersPath` custom location:
+
.Example: `ServiceBinding` CR with the `spec.containers` path in a custom location
[source,yaml]
----
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
name: spring-petclinic-rest
name: spring-petclinic-pgcluster
spec:
services:
- group: postgres-operator.crunchydata.com
@@ -51,7 +55,7 @@ spec:
name: hippo-pguser-hippo
id: postgresSecret
application: <1>
name: spring-petclinic-rest
name: spring-petclinic
group: apps
version: v1
resource: deployments
@@ -89,7 +93,7 @@ spec:
image: quay.io/baijum/secondary-workload:latest
name: hello-world
ports:
- containerPort: 9966
- containerPort: 8080
resources: {}
----
<1> Unique array of containers with values generated by the {servicebinding-title}. These values are based on the backing service CR.
@@ -109,15 +113,17 @@ spec:
secret: ""
----
The following example shows how to configure the `spec.secret` path by specifying a value in the `ServiceBinding` CR and to bind this path at a `spec.application.bindingPath.secretPath` custom location:
[discrete]
.Procedure
* Configure the `spec.secret` path by specifying a value in the `ServiceBinding` CR and bind this path at a `spec.application.bindingPath.secretPath` custom location:
+
.Example: `ServiceBinding` CR with the `spec.secret` path in a custom location
[source,yaml]
----
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
name: spring-petclinic-rest
name: spring-petclinic-pgcluster
spec:
...
application: <1>

26
modules/sbo-categories-of-exposable-binding-data.adoc
View File

@@ -1,6 +1,12 @@
// Module included in the following assemblies:
//
// * /applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc
:_content-type: CONCEPT
[id="sbo-categories-of-exposable-binding-data_{context}"]
= Categories of exposable binding data
[role="_abstract"]
The {servicebinding-title} enables you to expose the binding data values from the backing service resources and custom resource definitions (CRDs).
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.
@@ -16,7 +22,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-postgresql
namespace: my-petclinic
annotations:
service.binding/username: path={.metadata.name}
...
@@ -33,7 +39,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-postgresql
namespace: my-petclinic
annotations:
"service.binding/type": "postgresql" <1>
----
@@ -50,7 +56,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-postgresql
namespace: my-petclinic
annotations:
service.binding: 'path={.metadata.name}-pguser-{.metadata.name},objectType=Secret'
----
@@ -93,7 +99,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-postgresql
namespace: my-petclinic
annotations:
service.binding: 'path={.metadata.name}-config,objectType=ConfigMap,sourceKey=user'
----
@@ -138,7 +144,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-postgresql
namespace: my-petclinic
annotations:
service.binding/username: path={.metadata.name}
...
@@ -169,7 +175,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-postgresql
namespace: my-petclinic
annotations:
"service.binding/uri": "path={.status.connections},elementType=sliceOfMaps,sourceKey=type,sourceValue=url"
spec:
@@ -187,6 +193,7 @@ status:
The following example shows how the previous entries of a collection in annotations are projected into the bound application.
.Example: Binding data files
[source,text]
----
/bindings/<binding-name>/uri_primary => primary.example.com
/bindings/<binding-name>/uri_secondary => secondary.example.com
@@ -232,7 +239,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-postgresql
namespace: my-petclinic
annotations:
"service.binding/tags": "path={.spec.tags},elementType=sliceOfStrings"
spec:
@@ -245,6 +252,7 @@ spec:
The following example shows how the previous items of a collection in annotations are projected into the bound application.
.Example: Binding data files
[source,text]
----
/bindings/<binding-name>/tags_0 => knowledge
/bindings/<binding-name>/tags_1 => is
@@ -264,6 +272,7 @@ The following example shows how to expose the items of a collection with one key
The previous example uses the `path` attribute with an `X-Descriptors` update for the required items of a collection.
.Example: Configuration from a backing service resource
[source,yaml]
----
spec:
tags:
@@ -283,7 +292,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-postgresql
namespace: my-petclinic
annotations:
"service.binding/url": "path={.spec.connections},elementType=sliceOfStrings,sourceValue=url"
spec:
@@ -299,6 +308,7 @@ spec:
The following example shows how the previous values of a collection in annotations are projected into the bound application.
.Example: Binding data files
[source,text]
----
/bindings/<binding-name>/url_0 => primary.example.com
/bindings/<binding-name>/url_1 => secondary.example.com

105
modules/sbo-connecting-spring-petclinic-sample-app-to-postgresql-database-service.adoc
View File

@@ -9,29 +9,25 @@ To connect the sample application to the database service, you must create a `Se
. Create a `ServiceBinding` CR to project the binding data:
+
[source,terminal]
----
$ oc apply -f - << EOD
$ oc apply -n my-petclinic -f - << EOD
---
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
name: spring-petclinic-rest
namespace: my-postgresql
name: spring-petclinic-pgcluster
spec:
services: <1>
services: <1>
- group: postgres-operator.crunchydata.com
version: v1beta1
kind: PostgresCluster <2>
name: hippo
- group: ""
version: v1
kind: Secret
name: hippo-pguser-hippo
application: <3>
name: spring-petclinic-rest
group: apps
version: v1
resource: deployments
application: <3>
name: spring-petclinic
group: apps
version: v1
resource: deployments
EOD
----
<1> Specifies a list of service resources.
@@ -41,82 +37,61 @@ EOD
The output verifies that the `ServiceBinding` CR is created to project the binding data into the sample application.
+
.Example output
[source,terminal]
----
servicebinding.binding.operators.coreos.com/spring-petclinic-rest created
servicebinding.binding.operators.coreos.com/spring-petclinic created
----
. To verify that the binding is successful, check the status conditions of the binding resource:
. Verify that the request for service binding is successful:
+
[source,terminal]
----
$ oc get servicebindings spring-petclinic-rest -n my-postgresql -o jsonpath-as-json='{.status.conditions}'
$ oc get servicebindings -n my-petclinic
----
+
.Example output
[source,terminal]
----
[
[
{
"lastTransitionTime": "2021-09-06T13:42:28Z",
"message": "",
"reason": "DataCollected",
"status": "True",
"type": "CollectionReady",
},
{
"lastTransitionTime": "2021-09-06T13:42:28Z",
"message": "",
"reason": "ApplicationUpdated",
"status": "True",
"type": "InjectionReady",
},
{
"lastTransitionTime": "2021-09-06T13:42:28Z",
"message": "",
"reason": "ApplicationsBound",
"status": "True",
"type": "Ready",
},
],
]
NAME READY REASON AGE
spring-petclinic-pgcluster True ApplicationsBound 7s
----
+
By default, the values from the binding data of the database service are projected as files into the workload container that runs the sample application.
By default, the values from the binding data of the database service are projected as files into the workload container that runs the sample application. For example, all the values from the Secret resource are projected into the `bindings/spring-petclinic-pgcluster` directory.
+
[NOTE]
====
Optionally, you can also verify that the files in the application contain the projected binding data, by printing out the directory contents:
. To verify that the files in the application contain the projected binding data, use the following command in shell to print out the contents:
+
[source,terminal]
----
$ for i in username password host port type; do oc exec -it deploy/spring-petclinic-rest -n my-postgresql -- /bin/bash -c 'find /bindings/*/'$i' -exec echo -n {}:" " \; -exec cat {} \;'; echo; done
$ for i in username password host port type; do oc exec -it deploy/spring-petclinic -n my-petclinic -- /bin/bash -c 'cd /tmp; find /bindings/*/'$i' -exec echo -n {}:" " \; -exec cat {} \;'; echo; done
----
+
.Example output: With all the values from the secret resource
[source,text]
----
/bindings/spring-petclinic-rest/username: hippo
/bindings/spring-petclinic-rest/password: w0ZB<0j1W|K;+4*TlK7-w^z/
/bindings/spring-petclinic-rest/host: hippo-pgbouncer
/bindings/spring-petclinic-rest/port: 5432
/bindings/spring-petclinic-rest/type: postgresql
/bindings/spring-petclinic-pgcluster/username: hippo
/bindings/spring-petclinic-pgcluster/password: KXKF{nAI,I-J6zLt:W+FKnze
/bindings/spring-petclinic-pgcluster/host: hippo-primary.my-petclinic.svc
/bindings/spring-petclinic-pgcluster/port: 5432
/bindings/spring-petclinic-pgcluster/type: postgresql
----
====
. Set up the port forwarding from the application port to access the sample application from your local environment:
+
[source,terminal]
----
$ oc port-forward --address 0.0.0.0 svc/spring-petclinic-rest 9966:80 -n my-postgresql
----
. Access link:http://localhost:9966/petclinic[http://localhost:9966/petclinic].
+
You can now remotely access the Spring PetClinic sample application at localhost:9966.
. To verify that the application is now connected to the database service, access the list of all pets:
+
----
$ curl -X GET "http://localhost:9966/petclinic/api/pets" -H "accept: application/json"
$ oc port-forward --address 0.0.0.0 svc/spring-petclinic 8080:80 -n my-petclinic
----
+
.Example output
[source,terminal]
----
[{"id":1,"name":"Leo","birthDate":"2000/09/07","type":{"id":1,"name":"cat"},
"owner":{"id":1,"firstName":"George","lastName":"Franklin","address":"110...
Forwarding from 0.0.0.0:8080 -> 8080
Handling connection for 8080
----
. Access link:http://localhost:8080/petclinic[http://localhost:8080/petclinic].
+
The previous output shows the initially configured sample data and verifies that the application is now connected to the database service.
You can now remotely access the Spring PetClinic sample application at localhost:8080 and see that the application is now connected to the database service.

66
modules/sbo-creating-a-postgresql-database-instance.adoc
View File

@@ -7,31 +7,16 @@ To create a PostgreSQL database instance, you must create a `PostgresCluster` cu
[discrete]
.Procedure
. Create the `PostgresCluster` CR and the `my-postgresql` namespace by running the following command in shell:
. Create the `PostgresCluster` CR in the `my-petclinic` namespace by running the following command in shell:
+
[source,terminal]
----
$ oc apply -f - << EOD
---
apiVersion: v1
kind: Namespace
metadata:
name: my-postgresql
$ oc apply -n my-petclinic -f - << EOD
---
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-postgresql
annotations:
service.binding: 'path={.metadata.annotations.dbsecret},objectType=Secret'
dbsecret: hippo-pguser-hippo
proxy: hippo-pgbouncer
type: postgresql
service.binding/database: path={.metadata.name}
service.binding/port: path={.spec.port}
service.binding/username: path={.metadata.name}
service.binding/host: path={.metadata.annotations.proxy}
service.binding/type: path={.metadata.annotations.type}
spec:
image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres-ha:centos8-13.4-0
postgresVersion: 13
@@ -65,7 +50,7 @@ spec:
storage: 1Gi
proxy:
pgBouncer:
image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbouncer:centos8-1.15-2
image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbouncer:centos8-1.15-2
EOD
----
+
@@ -74,49 +59,28 @@ The annotations added in this `PostgresCluster` CR help in enabling the service
The output verifies that the database instance is created:
+
.Example output
[source,terminal]
----
namespace/my-postgresql configured
postgrescluster.postgres-operator.crunchydata.com/hippo created
----
. After you have created the database instance, ensure that all the pods in `my-postgresql` namespace are running (it will take a few minutes):
. After you have created the database instance, ensure that all the pods in `my-petclinic` namespace are running (it will take a few minutes):
+
[source,terminal]
----
$ oc get pods -n my-postgresql
$ oc get pods -n my-petclinic
----
+
The output verifies that the database is created:
The output verifies that the database is created and configured:
+
.Example output
[source,terminal]
----
NAME READY STATUS RESTARTS AGE
hippo-backup-6th6--1-28849 0/1 Completed 0 1m
hippo-instance1-sl4r-0 2/2 Running 0 2m
hippo-pgbouncer-8454474bc7-lhcn9 2/2 Running 0 2m
NAME READY STATUS RESTARTS AGE
hippo-backup-nqjg-2rq94 1/1 Running 0 35s
hippo-instance1-nw92-0 3/3 Running 0 112s
hippo-pgbouncer-57b98f4476-znsk5 2/2 Running 0 112s
hippo-repo-host-0 1/1 Running 0 112s
----
+
The new database is empty at this stage. You can set its schema and project a sample data set to interact with the sample application.
. Initialize the database with the schema and sample data. To do so, use the following custom shell script by copying the code into the shell and running it:
+
----
$ cat << EOD | bash
#!/bin/bash
export pgo_cluster_name=hippo
export cluster_namespace=my-postgresql
export pgo_cluster_username=hippo
export PGPASSWORD=\$(oc -n "\${cluster_namespace}" get secrets \
"\${pgo_cluster_name}-pguser-\${pgo_cluster_username}" -o "jsonpath={.data['password']}" | base64 -d)
nohup oc -n \${cluster_namespace} port-forward svc/hippo-pgbouncer 5432:5432 &
sleep 5
curl -LO https://raw.githubusercontent.com/spring-petclinic/spring-petclinic-rest/master/src/main/resources/db/postgresql/initDB.sql
psql -h localhost -U "\${pgo_cluster_username}" "\${pgo_cluster_name}" -f initDB.sql
curl -LO https://raw.githubusercontent.com/spring-petclinic/spring-petclinic-rest/master/src/main/resources/db/postgresql/populateDB.sql
psql -h localhost -U "\${pgo_cluster_username}" "\${pgo_cluster_name}" -f populateDB.sql
EOD
----
+
The output in the terminal shows you that the database is being configured for the application.
After the database is configured, you can deploy the sample application and connect it to the database service.

9
modules/sbo-data-model.adoc
View File

@@ -1,9 +1,14 @@
// Module included in the following assemblies:
//
// *openshift-docs/applications/connecting_applications_to_services/exposing-binding-data-from-a-service
// * /applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc
:_content-type: CONCEPT
[id="sbo-data-model_{context}"]
= Data model
[role="_abstract"]
The data model used in the annotations and OLM descriptors follow specific conventions.
Service binding annotations must use the following convention:
[source,yaml]
@@ -16,7 +21,7 @@ where:
`<NAME>`:: Specifies the name under which the binding value is to be exposed. You can exclude it only when the `objectType` parameter is set to `Secret` or `ConfigMap`.
`<VALUE>`:: Specifies the constant value exposed when no `path` is set.
This section explains the data model used in the annotations and OLM descriptors. The data model is the same for custom resource definition (CRD) or custom resource (CR) annotations and Operator Lifecycle Manager (OLM) descriptors, but the syntax differs.
Although, the data model is the same for custom resource definitions (CRD), custom resource (CR) annotations, and Operator Lifecycle Manager (OLM) descriptors, the syntax for each one differs.
The data model provides the details on the allowed values and semantic for the `path`, `elementType`, `objectType`, `sourceKey`, and `sourceValue` parameters.

82
modules/sbo-deploying-the-spring-petclinic-sample-application.adoc
View File

@@ -7,84 +7,88 @@ To deploy the Spring PetClinic sample application on an {product-title} cluster,
[discrete]
.Procedure
. Deploy the `spring-petclinic-rest` application with the `PostgresCluster` custom resource (CR) by running the following command in shell:
. Deploy the `spring-petclinic` application with the `PostgresCluster` custom resource (CR) by running the following command in shell:
+
[source,terminal]
----
$ oc apply -f - << EOD
$ oc apply -n my-petclinic -f - << EOD
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: spring-petclinic-rest
namespace: my-postgresql
name: spring-petclinic
labels:
app: spring-petclinic-rest
app: spring-petclinic
spec:
replicas: 1
selector:
matchLabels:
app: spring-petclinic-rest
app: spring-petclinic
template:
metadata:
labels:
app: spring-petclinic-rest
app: spring-petclinic
spec:
containers:
- name: application
image: quay.io/baijum/spring-petclinic-rest:latest
- name: app
image: quay.io/service-binding/spring-petclinic:latest
imagePullPolicy: Always
env:
- name: SPRING_PROFILES_ACTIVE
value: postgresql,spring-data-jpa
value: postgres
ports:
- name: http
containerPort: 9966
containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: spring-petclinic-rest
namespace: my-postgresql
labels:
app: spring-petclinic
name: spring-petclinic
spec:
type: NodePort
ports:
- port: 80
targetPort: 9966
- port: 80
protocol: TCP
targetPort: 8080
selector:
app: spring-petclinic-rest
app: spring-petclinic
EOD
----
+
The output verifies that the Spring PetClinic sample application is created and deployed:
+
.Example output
[source,terminal]
----
deployment.apps/spring-petclinic-rest created
service/spring-petclinic-rest created
deployment.apps/spring-petclinic created
service/spring-petclinic created
----
. Set up port forwarding from the application port to access the sample application from your local environment:
+
----
$ oc port-forward --address 0.0.0.0 svc/spring-petclinic-rest 9966:80 -n my-postgresql
----
. Access link:http://localhost:9966/petclinic[http://localhost:9966/petclinic].
+
You can now remotely access the Spring PetClinic sample application at localhost:9966.
+
[NOTE]
====
The application is not yet connected to the database service. If you try to interact with the application, it will return errors.
====
+
For example, if you try to access the list of all pets using `curl`, you can see an error message similar to the following sample message:
+
----
$ curl -X GET "http://localhost:9966/petclinic/api/pets" -H "accept: application/json"
If you are deploying the application using *Container images* in the *Developer* perspective of the web console, you must enter the following environment variables under the *Deployment* section of the *Advanced options*:
{"className":"org.springframework.transaction.CannotCreateTransactionException","exMessage":"Could
not open JPA EntityManager for transaction; nested exception is
org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC
Connection"}
* Name: SPRING_PROFILES_ACTIVE
* Value: postgres
====
. Verify that the application is not yet connected to the database service by running the following command (it will take a few minutes to view the `CrashLoopBackOff` status):
+
[source,terminal]
----
$ oc get pods -n my-petclinic
----
+
.Example output
[source,terminal]
----
NAME READY STATUS RESTARTS AGE
spring-petclinic-5b4c7999d4-wzdtz 0/1 CrashLoopBackOff 4 (13s ago) 2m25s
----
+
At this stage, the pod fails to start. If you try to interact with the application, it will return errors.
You can now use the {servicebinding-title} to connect the application to the database service.

20
modules/sbo-methods-of-exposing-binding-data.adoc
View File

@@ -1,6 +1,12 @@
// Module included in the following assemblies:
//
// * /applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc
:_content-type: CONCEPT
[id="sbo-methods-of-exposing-binding-data_{context}"]
= Methods of exposing binding data
[role="_abstract"]
This section describes the methods you can use to expose the binding data.
Ensure that you know and understand your workload requirements and environment, and how it works with the provided services.
@@ -70,7 +76,7 @@ spec:
kind: AccountService
name: prod-account-service
application:
name: spring-petclinic-rest
name: spring-petclinic
group: apps
version: v1
resource: deployments
@@ -98,7 +104,7 @@ spec:
application:
apiVersion: apps/v1
kind: Deployment
name: spring-petclinic-rest
name: spring-petclinic
----
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.
@@ -150,7 +156,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-postgresql
namespace: my-petclinic
annotations:
service.binding: 'path={.metadata.name}-pguser-{.metadata.name},objectType=Secret'
...
@@ -177,7 +183,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-postgresql
namespace: my-petclinic
annotations:
service.binding: 'path={.metadata.name}-config,objectType=ConfigMap'
...
@@ -245,8 +251,8 @@ The following examples show the `detectBindingResources` API option set to `true
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
name: spring-petclinic-rest-detect-all
namespace: my-postgresql
name: spring-petclinic-detect-all
namespace: my-petclinic
spec:
detectBindingResources: true
services:
@@ -255,7 +261,7 @@ spec:
kind: PostgresCluster
name: hippo
application:
name: spring-petclinic-rest
name: spring-petclinic
group: apps
version: v1
resource: deployments

4
modules/sbo-naming-strategies.adoc
View File

@@ -2,9 +2,11 @@
//
// * /applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc
:_content-type: CONCEPT
[id="sbo-naming-strategies_{context}"]
= Naming strategies
[role="_abstract"]
Naming strategies are available only for the `binding.operators.coreos.com` API group.
Naming strategies use Go templates to help you define custom binding names through the service binding request. Naming strategies apply for all attributes including the mappings in the `ServiceBinding` custom resource (CR).
@@ -26,6 +28,7 @@ Binding names declared through annotations or Operator Lifecycle Manager (OLM) d
.Example
After the template compilation, the binding names take the `{{ .name }}` form.
+
[source,yaml]
----
host: hippo-pgbouncer
port: 5432
@@ -36,6 +39,7 @@ port: 5432
.Example
After the template compilation, the binding names take the `{{ .service.kind | upper}}_{{ .name | upper }}` form.
+
[source,yaml]
----
DATABASE_HOST: hippo-pgbouncer
DATABASE_PORT: 5432

7
modules/sbo-rbac-requirements.adoc
View File

@@ -1,10 +1,13 @@
// Module included in the following assemblies:
//
// *openshift-docs/applications/connecting_applications_to_services/exposing-binding-data-from-a-service
// * /applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc
:_content-type: CONCEPT
[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.
[role="_abstract"]
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. If the users do not have permissions to read binding data or modify application resource, the {servicebinding-title} prevents such users to bind services to application. Adhering to the RBAC requirements avoids unnecessary permission elevation for the user and prevents access to unauthorized services or applications.
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:

6
modules/sbo-unbinding-workloads-from-a-backing-service.adoc
View File

@@ -2,9 +2,11 @@
//
// * /applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc
:_content-type: PROCEDURE
[id="sbo-unbinding-workloads-from-a-backing-service_{context}"]
= Unbinding workloads from a backing service
[role="_abstract"]
You can unbind a workload from a backing service by using the `oc` tool.
* To unbind a workload from a backing service, delete the `ServiceBinding` custom resource (CR) linked to it:
@@ -17,8 +19,8 @@ $ oc delete ServiceBinding <.metadata.name>
.Example
[source,terminal]
----
$ oc delete ServiceBinding spring-petclinic-rest
$ oc delete ServiceBinding spring-petclinic-pgcluster
----
where:
[horizontal]
`spring-petclinic-rest`:: Specifies the name of the `ServiceBinding` CR.
`spring-petclinic-pgcluster`:: Specifies the name of the `ServiceBinding` CR.