diff --git a/applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc b/applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc index 1613dca26f11..5bec54a34fb1 100644 --- a/applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc +++ b/applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc @@ -7,27 +7,29 @@ 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-pgcluster - namespace: my-petclinic + name: spring-petclinic-rest + namespace: my-postgresql 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 + name: spring-petclinic-rest group: apps version: v1 resource: deployments diff --git a/applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc b/applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc index 80d9a1b604db..a60b805f63b4 100644 --- a/applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc +++ b/applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc @@ -7,7 +7,6 @@ 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. diff --git a/applications/connecting_applications_to_services/getting-started-with-service-binding.adoc b/applications/connecting_applications_to_services/getting-started-with-service-binding.adoc index 7f81b56761d5..0a2a1f7dd0f0 100644 --- a/applications/connecting_applications_to_services/getting-started-with-service-binding.adoc +++ b/applications/connecting_applications_to_services/getting-started-with-service-binding.adoc @@ -7,7 +7,6 @@ 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 @@ -16,13 +15,9 @@ 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-petclinic` namespace. -+ -[NOTE] -==== -You can create the namespace using the `oc create namespace my-petclinic` command. -==== +* 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. //Creating a PostgreSQL database instance include::modules/sbo-creating-a-postgresql-database-instance.adoc[leveloffset=+1] diff --git a/applications/connecting_applications_to_services/installing-sbo.adoc b/applications/connecting_applications_to_services/installing-sbo.adoc index 438f7f9b6a3e..fdde57c78c50 100644 --- a/applications/connecting_applications_to_services/installing-sbo.adoc +++ b/applications/connecting_applications_to_services/installing-sbo.adoc @@ -7,7 +7,6 @@ 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. diff --git a/applications/connecting_applications_to_services/odc-connecting-an-application-to-a-service-using-the-developer-perspective.adoc b/applications/connecting_applications_to_services/odc-connecting-an-application-to-a-service-using-the-developer-perspective.adoc index a6095e476a04..cf471b79f3e1 100644 --- a/applications/connecting_applications_to_services/odc-connecting-an-application-to-a-service-using-the-developer-perspective.adoc +++ b/applications/connecting_applications_to_services/odc-connecting-an-application-to-a-service-using-the-developer-perspective.adoc @@ -5,7 +5,6 @@ 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. @@ -19,8 +18,8 @@ This procedure walks you through an example of creating a visual connection betw .Prerequisites -* 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`. +* 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`. .Procedure @@ -29,7 +28,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 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. +. 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. Similarly you can create other applications and components and establish visual connections between them. @@ -43,13 +42,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 -* 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`. +* 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`. .Procedure -. 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. +. 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. . 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: @@ -60,8 +59,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-pgcluster - namespace: my-petclinic + name: spring-petclinic-rest + namespace: my-postgresql spec: services: - group: postgres-operator.crunchydata.com @@ -69,7 +68,7 @@ spec: kind: PostgresCluster name: hippo application: - name: spring-petclinic + name: spring-petclinic-rest group: apps version: v1 resource: deployments diff --git a/applications/connecting_applications_to_services/projecting-binding-data.adoc b/applications/connecting_applications_to_services/projecting-binding-data.adoc index e6502f7ad5ae..714f73ee65ac 100644 --- a/applications/connecting_applications_to_services/projecting-binding-data.adoc +++ b/applications/connecting_applications_to_services/projecting-binding-data.adoc @@ -7,7 +7,6 @@ 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 diff --git a/applications/connecting_applications_to_services/understanding-service-binding-operator.adoc b/applications/connecting_applications_to_services/understanding-service-binding-operator.adoc index a2e32a044d83..674d49969e84 100644 --- a/applications/connecting_applications_to_services/understanding-service-binding-operator.adoc +++ b/applications/connecting_applications_to_services/understanding-service-binding-operator.adoc @@ -8,7 +8,6 @@ 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. diff --git a/images/odc-binding-connector.png b/images/odc-binding-connector.png index be3a632b72e0..efce41ce87af 100644 Binary files a/images/odc-binding-connector.png and b/images/odc-binding-connector.png differ diff --git a/images/odc_connecting_multiple_applications.png b/images/odc_connecting_multiple_applications.png index 0c11e5456c13..564b9593f1d3 100644 Binary files a/images/odc_connecting_multiple_applications.png and b/images/odc_connecting_multiple_applications.png differ diff --git a/images/odc_connector.png b/images/odc_connector.png index 570446e21904..c12ae3a16630 100644 Binary files a/images/odc_connector.png and b/images/odc_connector.png differ diff --git a/modules/sbo-advanced-binding-options.adoc b/modules/sbo-advanced-binding-options.adoc index 297c6894a2e0..39671b290033 100644 --- a/modules/sbo-advanced-binding-options.adoc +++ b/modules/sbo-advanced-binding-options.adoc @@ -2,11 +2,9 @@ // // * /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 @@ -17,7 +15,7 @@ You can specify the rules to change the binding names in the .spec.namingStrateg ---- ... application: - name: spring-petclinic + name: spring-petclinic-rest group: apps version: v1 resource: deployments @@ -39,7 +37,6 @@ 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 ---- @@ -51,7 +48,6 @@ 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 @@ -77,13 +73,12 @@ 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-pgcluster - namespace: my-petclinic + name: spring-petclinic-rest + namespace: my-postgresql spec: services: - group: postgres-operator.crunchydata.com @@ -97,7 +92,7 @@ spec: name: hippo-pguser-hippo id: postgresSecret application: - name: spring-petclinic + name: spring-petclinic-rest group: apps version: v1 resource: deployments diff --git a/modules/sbo-binding-workloads-that-are-not-compliant-with-PodSpec.adoc b/modules/sbo-binding-workloads-that-are-not-compliant-with-PodSpec.adoc index c9dbc890d7b7..667254f0df37 100644 --- a/modules/sbo-binding-workloads-that-are-not-compliant-with-PodSpec.adoc +++ b/modules/sbo-binding-workloads-that-are-not-compliant-with-PodSpec.adoc @@ -2,14 +2,12 @@ // // * /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` custom resource (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` 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. @@ -28,20 +26,18 @@ spec: - name: hello-world image: quay.io/baijum/secondary-workload:latest ports: - - containerPort: 8080 + - containerPort: 9966 ---- -[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: -+ +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: + .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-pgcluster + name: spring-petclinic-rest spec: services: - group: postgres-operator.crunchydata.com @@ -55,7 +51,7 @@ spec: name: hippo-pguser-hippo id: postgresSecret application: <1> - name: spring-petclinic + name: spring-petclinic-rest group: apps version: v1 resource: deployments @@ -93,7 +89,7 @@ spec: image: quay.io/baijum/secondary-workload:latest name: hello-world ports: - - containerPort: 8080 + - containerPort: 9966 resources: {} ---- <1> Unique array of containers with values generated by the {servicebinding-title}. These values are based on the backing service CR. @@ -113,17 +109,15 @@ spec: secret: "" ---- -[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: -+ +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: + .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-pgcluster + name: spring-petclinic-rest spec: ... application: <1> diff --git a/modules/sbo-categories-of-exposable-binding-data.adoc b/modules/sbo-categories-of-exposable-binding-data.adoc index 32b42a1ac773..bac71cb8560d 100644 --- a/modules/sbo-categories-of-exposable-binding-data.adoc +++ b/modules/sbo-categories-of-exposable-binding-data.adoc @@ -1,12 +1,6 @@ -// 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. @@ -22,7 +16,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1 kind: PostgresCluster metadata: name: hippo - namespace: my-petclinic + namespace: my-postgresql annotations: service.binding/username: path={.metadata.name} ... @@ -39,7 +33,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1 kind: PostgresCluster metadata: name: hippo - namespace: my-petclinic + namespace: my-postgresql annotations: "service.binding/type": "postgresql" <1> ---- @@ -56,7 +50,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1 kind: PostgresCluster metadata: name: hippo - namespace: my-petclinic + namespace: my-postgresql annotations: service.binding: 'path={.metadata.name}-pguser-{.metadata.name},objectType=Secret' ---- @@ -99,7 +93,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1 kind: PostgresCluster metadata: name: hippo - namespace: my-petclinic + namespace: my-postgresql annotations: service.binding: 'path={.metadata.name}-config,objectType=ConfigMap,sourceKey=user' ---- @@ -144,7 +138,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1 kind: PostgresCluster metadata: name: hippo - namespace: my-petclinic + namespace: my-postgresql annotations: service.binding/username: path={.metadata.name} ... @@ -175,7 +169,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1 kind: PostgresCluster metadata: name: hippo - namespace: my-petclinic + namespace: my-postgresql annotations: "service.binding/uri": "path={.status.connections},elementType=sliceOfMaps,sourceKey=type,sourceValue=url" spec: @@ -193,7 +187,6 @@ 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//uri_primary => primary.example.com /bindings//uri_secondary => secondary.example.com @@ -239,7 +232,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1 kind: PostgresCluster metadata: name: hippo - namespace: my-petclinic + namespace: my-postgresql annotations: "service.binding/tags": "path={.spec.tags},elementType=sliceOfStrings" spec: @@ -252,7 +245,6 @@ 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//tags_0 => knowledge /bindings//tags_1 => is @@ -272,7 +264,6 @@ 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: @@ -292,7 +283,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1 kind: PostgresCluster metadata: name: hippo - namespace: my-petclinic + namespace: my-postgresql annotations: "service.binding/url": "path={.spec.connections},elementType=sliceOfStrings,sourceValue=url" spec: @@ -308,7 +299,6 @@ 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//url_0 => primary.example.com /bindings//url_1 => secondary.example.com diff --git a/modules/sbo-connecting-spring-petclinic-sample-app-to-postgresql-database-service.adoc b/modules/sbo-connecting-spring-petclinic-sample-app-to-postgresql-database-service.adoc index a905157d5e47..120906d6be34 100644 --- a/modules/sbo-connecting-spring-petclinic-sample-app-to-postgresql-database-service.adoc +++ b/modules/sbo-connecting-spring-petclinic-sample-app-to-postgresql-database-service.adoc @@ -9,25 +9,29 @@ 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 -n my-petclinic -f - << EOD +$ oc apply -f - << EOD --- apiVersion: binding.operators.coreos.com/v1alpha1 kind: ServiceBinding metadata: - name: spring-petclinic-pgcluster + name: spring-petclinic-rest + namespace: my-postgresql spec: - services: <1> + services: <1> - group: postgres-operator.crunchydata.com version: v1beta1 kind: PostgresCluster <2> name: hippo - application: <3> - name: spring-petclinic - group: apps - version: v1 - resource: deployments + - group: "" + version: v1 + kind: Secret + name: hippo-pguser-hippo + application: <3> + name: spring-petclinic-rest + group: apps + version: v1 + resource: deployments EOD ---- <1> Specifies a list of service resources. @@ -37,61 +41,82 @@ 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 created +servicebinding.binding.operators.coreos.com/spring-petclinic-rest created ---- -. Verify that the request for service binding is successful: +. To verify that the binding is successful, check the status conditions of the binding resource: + -[source,terminal] ---- -$ oc get servicebindings -n my-petclinic +$ oc get servicebindings spring-petclinic-rest -n my-postgresql -o jsonpath-as-json='{.status.conditions}' ---- + .Example output -[source,terminal] ---- -NAME READY REASON AGE -spring-petclinic-pgcluster True ApplicationsBound 7s +[ + [ + { + "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", + }, + ], +] ---- + -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: +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. -[source,terminal] +. To verify that the files in the application contain the projected binding data, use the following command in shell to print out the contents: ++ ---- -$ 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 +$ 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 ---- - ++ .Example output: With all the values from the secret resource -[source,text] ---- -/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 +/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 ---- -==== . 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 8080:80 -n my-petclinic +$ 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" ---- + .Example output -[source,terminal] ---- -Forwarding from 0.0.0.0:8080 -> 8080 -Handling connection for 8080 +[{"id":1,"name":"Leo","birthDate":"2000/09/07","type":{"id":1,"name":"cat"}, +"owner":{"id":1,"firstName":"George","lastName":"Franklin","address":"110... ---- - -. Access link:http://localhost:8080/petclinic[http://localhost:8080/petclinic]. + -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. +The previous output shows the initially configured sample data and verifies that the application is now connected to the database service. diff --git a/modules/sbo-creating-a-postgresql-database-instance.adoc b/modules/sbo-creating-a-postgresql-database-instance.adoc index dd43bee83495..06f36fe7eb74 100644 --- a/modules/sbo-creating-a-postgresql-database-instance.adoc +++ b/modules/sbo-creating-a-postgresql-database-instance.adoc @@ -7,16 +7,31 @@ To create a PostgreSQL database instance, you must create a `PostgresCluster` cu [discrete] .Procedure -. Create the `PostgresCluster` CR in the `my-petclinic` namespace by running the following command in shell: +. Create the `PostgresCluster` CR and the `my-postgresql` namespace by running the following command in shell: + -[source,terminal] ---- -$ oc apply -n my-petclinic -f - << EOD +$ oc apply -f - << EOD +--- +apiVersion: v1 +kind: Namespace +metadata: + name: my-postgresql --- 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 @@ -50,7 +65,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 ---- + @@ -59,28 +74,49 @@ 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-petclinic` namespace are running (it will take a few minutes): +. After you have created the database instance, ensure that all the pods in `my-postgresql` namespace are running (it will take a few minutes): + -[source,terminal] ---- -$ oc get pods -n my-petclinic +$ oc get pods -n my-postgresql ---- + -The output verifies that the database is created and configured: +The output verifies that the database is created: + .Example output -[source,terminal] ---- -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 +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 +---- ++ +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. diff --git a/modules/sbo-data-model.adoc b/modules/sbo-data-model.adoc index 44c1f3c6cbf9..8ea76cf143b9 100644 --- a/modules/sbo-data-model.adoc +++ b/modules/sbo-data-model.adoc @@ -1,14 +1,9 @@ // Module included in the following assemblies: // -// * /applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc - -:_content-type: CONCEPT +// *openshift-docs/applications/connecting_applications_to_services/exposing-binding-data-from-a-service [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] @@ -21,7 +16,7 @@ where: ``:: 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`. ``:: Specifies the constant value exposed when no `path` is set. -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. +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. The data model provides the details on the allowed values and semantic for the `path`, `elementType`, `objectType`, `sourceKey`, and `sourceValue` parameters. diff --git a/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc b/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc index a4e90deeb9f7..ea67c920915b 100644 --- a/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc +++ b/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc @@ -7,88 +7,84 @@ To deploy the Spring PetClinic sample application on an {product-title} cluster, [discrete] .Procedure -. Deploy the `spring-petclinic` application with the `PostgresCluster` custom resource (CR) by running the following command in shell: +. Deploy the `spring-petclinic-rest` application with the `PostgresCluster` custom resource (CR) by running the following command in shell: + -[source,terminal] ---- -$ oc apply -n my-petclinic -f - << EOD +$ oc apply -f - << EOD --- apiVersion: apps/v1 kind: Deployment metadata: - name: spring-petclinic + name: spring-petclinic-rest + namespace: my-postgresql labels: - app: spring-petclinic + app: spring-petclinic-rest spec: replicas: 1 selector: matchLabels: - app: spring-petclinic + app: spring-petclinic-rest template: metadata: labels: - app: spring-petclinic + app: spring-petclinic-rest spec: containers: - - name: app - image: quay.io/service-binding/spring-petclinic:latest - imagePullPolicy: Always + - name: application + image: quay.io/baijum/spring-petclinic-rest:latest env: - name: SPRING_PROFILES_ACTIVE - value: postgres + value: postgresql,spring-data-jpa ports: - name: http - containerPort: 8080 + containerPort: 9966 --- apiVersion: v1 kind: Service metadata: - labels: - app: spring-petclinic - name: spring-petclinic + name: spring-petclinic-rest + namespace: my-postgresql spec: - type: NodePort ports: - - port: 80 - protocol: TCP - targetPort: 8080 + - port: 80 + targetPort: 9966 selector: - app: spring-petclinic + app: spring-petclinic-rest EOD ---- + The output verifies that the Spring PetClinic sample application is created and deployed: + .Example output -[source,terminal] ---- -deployment.apps/spring-petclinic created -service/spring-petclinic created +deployment.apps/spring-petclinic-rest created +service/spring-petclinic-rest 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] ==== -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*: - - -* Name: SPRING_PROFILES_ACTIVE -* Value: postgres +The application is not yet connected to the database service. If you try to interact with the application, it will return errors. ==== - -. 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 ----- +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: + -.Example output -[source,terminal] ---- -NAME READY STATUS RESTARTS AGE -spring-petclinic-5b4c7999d4-wzdtz 0/1 CrashLoopBackOff 4 (13s ago) 2m25s +$ curl -X GET "http://localhost:9966/petclinic/api/pets" -H "accept: application/json" + +{"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"} ---- -+ -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. diff --git a/modules/sbo-methods-of-exposing-binding-data.adoc b/modules/sbo-methods-of-exposing-binding-data.adoc index 17fb3c59276e..73b975945350 100644 --- a/modules/sbo-methods-of-exposing-binding-data.adoc +++ b/modules/sbo-methods-of-exposing-binding-data.adoc @@ -1,12 +1,6 @@ -// 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. @@ -76,7 +70,7 @@ spec: kind: AccountService name: prod-account-service application: - name: spring-petclinic + name: spring-petclinic-rest group: apps version: v1 resource: deployments @@ -104,7 +98,7 @@ spec: application: apiVersion: apps/v1 kind: Deployment - name: spring-petclinic + name: spring-petclinic-rest ---- 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. @@ -156,7 +150,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1 kind: PostgresCluster metadata: name: hippo - namespace: my-petclinic + namespace: my-postgresql annotations: service.binding: 'path={.metadata.name}-pguser-{.metadata.name},objectType=Secret' ... @@ -183,7 +177,7 @@ apiVersion: postgres-operator.crunchydata.com/v1beta1 kind: PostgresCluster metadata: name: hippo - namespace: my-petclinic + namespace: my-postgresql annotations: service.binding: 'path={.metadata.name}-config,objectType=ConfigMap' ... @@ -251,8 +245,8 @@ The following examples show the `detectBindingResources` API option set to `true apiVersion: binding.operators.coreos.com/v1alpha1 kind: ServiceBinding metadata: - name: spring-petclinic-detect-all - namespace: my-petclinic + name: spring-petclinic-rest-detect-all + namespace: my-postgresql spec: detectBindingResources: true services: @@ -261,7 +255,7 @@ spec: kind: PostgresCluster name: hippo application: - name: spring-petclinic + name: spring-petclinic-rest group: apps version: v1 resource: deployments diff --git a/modules/sbo-naming-strategies.adoc b/modules/sbo-naming-strategies.adoc index 29ede1d07c45..75b73e6994a7 100644 --- a/modules/sbo-naming-strategies.adoc +++ b/modules/sbo-naming-strategies.adoc @@ -2,11 +2,9 @@ // // * /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). @@ -28,7 +26,6 @@ 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 @@ -39,7 +36,6 @@ 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 diff --git a/modules/sbo-rbac-requirements.adoc b/modules/sbo-rbac-requirements.adoc index ecb20d1c7c2e..9a0cabf882b8 100644 --- a/modules/sbo-rbac-requirements.adoc +++ b/modules/sbo-rbac-requirements.adoc @@ -1,13 +1,10 @@ // Module included in the following assemblies: // -// * /applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc - -:_content-type: CONCEPT +// *openshift-docs/applications/connecting_applications_to_services/exposing-binding-data-from-a-service [id="sbo-rbac-requirements_{context}"] = RBAC requirements -[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. +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: diff --git a/modules/sbo-unbinding-workloads-from-a-backing-service.adoc b/modules/sbo-unbinding-workloads-from-a-backing-service.adoc index 5e8beeaad0ce..3b491fb90bf9 100644 --- a/modules/sbo-unbinding-workloads-from-a-backing-service.adoc +++ b/modules/sbo-unbinding-workloads-from-a-backing-service.adoc @@ -2,11 +2,9 @@ // // * /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: @@ -19,8 +17,8 @@ $ oc delete ServiceBinding <.metadata.name> .Example [source,terminal] ---- -$ oc delete ServiceBinding spring-petclinic-pgcluster +$ oc delete ServiceBinding spring-petclinic-rest ---- where: [horizontal] -`spring-petclinic-pgcluster`:: Specifies the name of the `ServiceBinding` CR. +`spring-petclinic-rest`:: Specifies the name of the `ServiceBinding` CR.