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 5bec54a34fb1..1613dca26f11 100644 --- a/applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc +++ b/applications/connecting_applications_to_services/binding-workloads-using-sbo.adoc @@ -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 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 a60b805f63b4..80d9a1b604db 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,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. 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 df8ffc44b95b..c2cddd47263b 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,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] diff --git a/applications/connecting_applications_to_services/installing-sbo.adoc b/applications/connecting_applications_to_services/installing-sbo.adoc index 6cef4187d296..e4726ac88eb9 100644 --- a/applications/connecting_applications_to_services/installing-sbo.adoc +++ b/applications/connecting_applications_to_services/installing-sbo.adoc @@ -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. 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 cf471b79f3e1..a6095e476a04 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,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 diff --git a/applications/connecting_applications_to_services/projecting-binding-data.adoc b/applications/connecting_applications_to_services/projecting-binding-data.adoc index 714f73ee65ac..e6502f7ad5ae 100644 --- a/applications/connecting_applications_to_services/projecting-binding-data.adoc +++ b/applications/connecting_applications_to_services/projecting-binding-data.adoc @@ -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 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 674d49969e84..a2e32a044d83 100644 --- a/applications/connecting_applications_to_services/understanding-service-binding-operator.adoc +++ b/applications/connecting_applications_to_services/understanding-service-binding-operator.adoc @@ -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. diff --git a/images/odc-binding-connector.png b/images/odc-binding-connector.png index efce41ce87af..be3a632b72e0 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 564b9593f1d3..0c11e5456c13 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 c12ae3a16630..570446e21904 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 39671b290033..297c6894a2e0 100644 --- a/modules/sbo-advanced-binding-options.adoc +++ b/modules/sbo-advanced-binding-options.adoc @@ -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 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 667254f0df37..c9dbc890d7b7 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,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> diff --git a/modules/sbo-categories-of-exposable-binding-data.adoc b/modules/sbo-categories-of-exposable-binding-data.adoc index bac71cb8560d..32b42a1ac773 100644 --- a/modules/sbo-categories-of-exposable-binding-data.adoc +++ b/modules/sbo-categories-of-exposable-binding-data.adoc @@ -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//uri_primary => primary.example.com /bindings//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//tags_0 => knowledge /bindings//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//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 120906d6be34..a905157d5e47 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,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. - -. To verify that the files in the application contain the projected binding data, use the following command in shell to print out the 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. 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: + +[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. diff --git a/modules/sbo-creating-a-postgresql-database-instance.adoc b/modules/sbo-creating-a-postgresql-database-instance.adoc index 06f36fe7eb74..dd43bee83495 100644 --- a/modules/sbo-creating-a-postgresql-database-instance.adoc +++ b/modules/sbo-creating-a-postgresql-database-instance.adoc @@ -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 ----- -+ -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 +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 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 8ea76cf143b9..44c1f3c6cbf9 100644 --- a/modules/sbo-data-model.adoc +++ b/modules/sbo-data-model.adoc @@ -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: ``:: 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. -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. diff --git a/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc b/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc index ea67c920915b..a4e90deeb9f7 100644 --- a/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc +++ b/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc @@ -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 ----- - -. 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 +deployment.apps/spring-petclinic created +service/spring-petclinic created ---- - -. 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. +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 ==== + +. 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): + -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: +[source,terminal] +---- +$ oc get pods -n my-petclinic +---- + +.Example output +[source,terminal] ---- -$ 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"} +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. diff --git a/modules/sbo-methods-of-exposing-binding-data.adoc b/modules/sbo-methods-of-exposing-binding-data.adoc index 73b975945350..17fb3c59276e 100644 --- a/modules/sbo-methods-of-exposing-binding-data.adoc +++ b/modules/sbo-methods-of-exposing-binding-data.adoc @@ -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 diff --git a/modules/sbo-naming-strategies.adoc b/modules/sbo-naming-strategies.adoc index 75b73e6994a7..29ede1d07c45 100644 --- a/modules/sbo-naming-strategies.adoc +++ b/modules/sbo-naming-strategies.adoc @@ -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 diff --git a/modules/sbo-rbac-requirements.adoc b/modules/sbo-rbac-requirements.adoc index 9a0cabf882b8..ecb20d1c7c2e 100644 --- a/modules/sbo-rbac-requirements.adoc +++ b/modules/sbo-rbac-requirements.adoc @@ -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: diff --git a/modules/sbo-unbinding-workloads-from-a-backing-service.adoc b/modules/sbo-unbinding-workloads-from-a-backing-service.adoc index 3b491fb90bf9..5e8beeaad0ce 100644 --- a/modules/sbo-unbinding-workloads-from-a-backing-service.adoc +++ b/modules/sbo-unbinding-workloads-from-a-backing-service.adoc @@ -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.