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 7430cb0c6baa..28de07f1f1d0 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::_attributes/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 @@ -44,7 +42,6 @@ include::modules/sbo-advanced-binding-options.adoc[leveloffset=+1] include::modules/sbo-binding-workloads-that-are-not-compliant-with-PodSpec.adoc[leveloffset=+1] include::modules/sbo-unbinding-workloads-from-a-backing-service.adoc[leveloffset=+1] -[role="_additional-resources"] == Additional resources * xref:../../applications/connecting_applications_to_services/understanding-service-binding-operator.adoc#binding-a-workload-together-with-a-backing-service[Binding a workload together with a backing service]. -* xref:../../applications/connecting_applications_to_services/getting-started-with-service-binding.adoc#connecting-the-spring-petclinic-sample-application-to-the-postgresql-database-service[Connecting the Spring PetClinic sample application to the PostgreSQL database service]. +* xref:../../applications/connecting_applications_to_services/getting-started-with-service-binding.adoc#connecting-the-spring-petclinic-sample-application-to-the-postgresql-database-service[Connecting the Spring PetClinic sample application to the PostgreSQL database service]. \ No newline at end of file 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 57633543eb30..c1809e75eec8 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::_attributes/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. @@ -16,8 +17,7 @@ include::modules/sbo-data-model.adoc[leveloffset=+1] include::modules/sbo-rbac-requirements.adoc[leveloffset=+1] include::modules/sbo-categories-of-exposable-binding-data.adoc[leveloffset=+1] -[role="_additional-resources"] == Additional resources * link:https://github.com/openshift/console/blob/master/frontend/packages/operator-lifecycle-manager/src/components/descriptors/reference/reference.md[OLM Descriptor Reference]. * xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-generating-csvs[Defining cluster service versions (CSVs)]. -* xref:../../applications/connecting_applications_to_services/projecting-binding-data.adoc#projecting-binding-data[Projecting binding data]. +* xref:../../applications/connecting_applications_to_services/projecting-binding-data.adoc#projecting-binding-data[Projecting binding data]. \ No newline at end of file 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 15314f3e7f1a..a086182dc434 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,8 @@ include::_attributes/servicebinding-document-attributes.adoc[] toc::[] -{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. +[role="_abstract"] +The {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 the {servicebinding-title} to create a binding connection between the application and the database service. // Prerequisites for getting started with Service Binding Operator [discrete] @@ -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] @@ -28,9 +33,8 @@ include::modules/sbo-deploying-the-spring-petclinic-sample-application.adoc[leve //Connecting the Spring PetClinic sample application to the PostgreSQL database service include::modules/sbo-connecting-spring-petclinic-sample-app-to-postgresql-database-service.adoc[leveloffset=+1] -[role="_additional-resources"] -== Additional resources +== Additional Resources * xref:../../applications/connecting_applications_to_services/installing-sbo.adoc#installing-sbo[Installing Service Binding Operator]. * xref:../../applications/creating_applications/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Creating applications using the Developer perspective]. * xref:../../operators/understanding/crds/crd-managing-resources-from-crds.adoc[Managing resources from custom resource definitions]. -* link:https://github.com/redhat-developer/service-binding-operator#known-bindable-operators[Known bindable Operators]. +* link:https://github.com/redhat-developer/service-binding-operator#known-bindable-operators[Known bindable Operators]. \ No newline at end of file diff --git a/applications/connecting_applications_to_services/installing-sbo.adoc b/applications/connecting_applications_to_services/installing-sbo.adoc index a68e81ecc2d1..6a68aaf31767 100644 --- a/applications/connecting_applications_to_services/installing-sbo.adoc +++ b/applications/connecting_applications_to_services/installing-sbo.adoc @@ -7,6 +7,7 @@ include::_attributes/servicebinding-document-attributes.adoc[] toc::[] +[role="_abstract"] This guide walks cluster administrators through the process of installing the {servicebinding-title} to an {product-title} cluster. You can install {servicebinding-title} on {product-title} 4.7 and later. @@ -23,6 +24,5 @@ You can install {servicebinding-title} on {product-title} 4.7 and later. include::modules/op-installing-sbo-operator-using-the-web-console.adoc[leveloffset=+1] -[role="_additional-resources"] -== Additional resources -* xref:../../applications/connecting_applications_to_services/getting-started-with-service-binding.adoc#getting-started-with-service-binding[Getting started with service binding]. +== Additional Resources +* xref:../../applications/connecting_applications_to_services/getting-started-with-service-binding.adoc#getting-started-with-service-binding[Getting started with service binding]. \ No newline at end of file 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 c3e67b5dddbf..9457013a9856 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::_attributes/common-attributes.adoc[] include::_attributes/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 @@ -87,7 +88,6 @@ You can also use the context menu by dragging the dangling arrow to add and crea image::odc_context_operator.png[] ==== -[role="_additional-resources"] == Additional resources * xref:../../applications/connecting_applications_to_services/getting-started-with-service-binding.adoc#getting-started-with-service-binding[Getting started with service binding]. -* link:https://github.com/redhat-developer/service-binding-operator#known-bindable-operators[Known bindable Operators]. +* link:https://github.com/redhat-developer/service-binding-operator#known-bindable-operators[Known bindable Operators]. \ No newline at end of file diff --git a/applications/connecting_applications_to_services/projecting-binding-data.adoc b/applications/connecting_applications_to_services/projecting-binding-data.adoc index b6cf79231a86..7a69c136af9c 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::_attributes/servicebinding-document-attributes.adoc[] toc::[] +[role="_abstract"] This section provides information on how you can consume the binding data. == Consumption of binding data @@ -18,7 +19,6 @@ After the backing service exposes the binding data, for a workload to access and include::modules/sbo-configuration-of-directory-path-to-project-binding-data.adoc[leveloffset=+1] include::modules/sbo-projecting-the-binding-data.adoc[leveloffset=+1] -[role="_additional-resources"] == Additional resources * xref:../../applications/connecting_applications_to_services/exposing-binding-data-from-a-service.adoc#exposing-binding-data-from-a-service[Exposing binding data from a service]. -* link:https://redhat-developer.github.io/service-binding-operator/userguide/using-projected-bindings/using-projected-bindings.html[Using the projected binding data in the source code of the application]. +* link:https://redhat-developer.github.io/service-binding-operator/userguide/using-projected-bindings/using-projected-bindings.html[Using the projected binding data in the source code of the application]. \ No newline at end of file diff --git a/applications/connecting_applications_to_services/sbo-release-notes.adoc b/applications/connecting_applications_to_services/sbo-release-notes.adoc index 1ff6c91489c0..9ef2723f1127 100644 --- a/applications/connecting_applications_to_services/sbo-release-notes.adoc +++ b/applications/connecting_applications_to_services/sbo-release-notes.adoc @@ -3,7 +3,7 @@ include::_attributes/common-attributes.adoc[] include::_attributes/servicebinding-document-attributes.adoc[] :_content-type: ASSEMBLY [id="servicebinding-release-notes"] -= {servicebinding-title} release notes += Release notes for {servicebinding-title} :context: servicebinding-release-notes toc::[] @@ -24,7 +24,9 @@ With {servicebinding-title}, you can: Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see link:https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language[Red Hat CTO Chris Wright's message]. // Modules included, most to least recent +include::modules/sbo-release-notes-1-0-1.adoc[leveloffset=+1] include::modules/sbo-release-notes-1-0.adoc[leveloffset=+1] + == Additional resources -* xref:../../applications/connecting_applications_to_services/understanding-service-binding-operator.adoc#understanding-service-binding-operator[Understanding Service Binding Operator]. +* xref:../../applications/connecting_applications_to_services/understanding-service-binding-operator.adoc#understanding-service-binding-operator[Understanding Service Binding Operator]. \ No newline at end of file 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 fd47d1bf041c..5a28f9cff5d5 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::_attributes/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. @@ -78,6 +79,5 @@ With {servicebinding-title}, you can: ** Support for role-based access control (RBAC). -[role="_additional-resources"] == Additional resources -* xref:../../applications/connecting_applications_to_services/getting-started-with-service-binding.adoc#getting-started-with-service-binding[Getting started with service binding]. +* xref:../../applications/connecting_applications_to_services/getting-started-with-service-binding.adoc#getting-started-with-service-binding[Getting started with service binding]. \ No newline at end of file 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..30c868996049 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 @@ -110,4 +115,4 @@ spec: <1> Name of the backing service resource. <2> Optional identifier. <3> Generated JSON name that is to be projected as the file content or environment value. The JSON name contains the attributes of the backing service custom resource. -<4> Generated JSON value that is to be projected as the file content or environment value. The JSON value contains the attributes of the backing service custom resource. +<4> Generated JSON value that is to be projected as the file content or environment value. The JSON value contains the attributes of the backing service custom resource. \ No newline at end of file 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..f27f198387c3 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> @@ -148,4 +154,4 @@ spec: secret: binding-request-72ddc0c540ab3a290e138726940591debf14c581 <1> ... ---- -<1> Unique name of the `Secret` resource generated by the {servicebinding-title}. +<1> Unique name of the `Secret` resource generated by the {servicebinding-title}. \ No newline at end of file diff --git a/modules/sbo-categories-of-exposable-binding-data.adoc b/modules/sbo-categories-of-exposable-binding-data.adoc index bac71cb8560d..9ca61b5127b3 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 @@ -313,4 +323,4 @@ The following example shows how to expose the values of collection entries with - path: bootstrap x-descriptors: - service.binding:endpoints:elementType=sliceOfStrings:sourceValue=url ----- +---- \ No newline at end of file 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..4ba44a03a20e 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. \ No newline at end of file diff --git a/modules/sbo-creating-a-postgresql-database-instance.adoc b/modules/sbo-creating-a-postgresql-database-instance.adoc index 06f36fe7eb74..03724c81030c 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,58 +50,37 @@ 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 ---- + -The annotations added in this `PostgresCluster` CR help in enabling the service binding connection and trigger the Operator reconciliation. +The annotations added in this `PostgresCluster` CR enable the service binding connection and trigger the Operator reconciliation. + 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 the `my-petclinic` namespace are running: + +[source,terminal] ---- -$ oc get pods -n my-postgresql +$ oc get pods -n my-petclinic ---- + -The output verifies that the database is created: +The output, which takes a few minutes to display, 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. +After the database is configured, you can deploy the sample application and connect it to the database service. \ No newline at end of file diff --git a/modules/sbo-data-model.adoc b/modules/sbo-data-model.adoc index 8ea76cf143b9..3ec12156fadd 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. @@ -68,4 +73,4 @@ Note: [NOTE] ==== The `sourceKey` and `sourceValue` parameters are applicable only if the element indicated in the `path` parameter refers to a `ConfigMap` or `Secret` resource. -==== +==== \ No newline at end of file diff --git a/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc b/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc index ea67c920915b..ac9fd07e6da9 100644 --- a/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc +++ b/modules/sbo-deploying-the-spring-petclinic-sample-application.adoc @@ -7,84 +7,90 @@ 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: ++ +[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: +The output takes a few minutes to display the `CrashLoopBackOff` status: + +.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 returns errors. -You can now use the {servicebinding-title} to connect the application to the database service. +You can now use the {servicebinding-title} to connect the application to the database service. \ No newline at end of file diff --git a/modules/sbo-methods-of-exposing-binding-data.adoc b/modules/sbo-methods-of-exposing-binding-data.adoc index 73b975945350..0068374dbce0 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 @@ -263,4 +269,4 @@ spec: In the previous example, `PostgresCluster` custom service resource owns one or more Kubernetes resources such as route, service, config map, or secret. -The {servicebinding-title} automatically detects the binding data exposed on each of the owned resources. +The {servicebinding-title} automatically detects the binding data exposed on each of the owned resources. \ No newline at end of file diff --git a/modules/sbo-naming-strategies.adoc b/modules/sbo-naming-strategies.adoc index 75b73e6994a7..46b2fb4708a9 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 @@ -48,4 +52,4 @@ If your workload requires a different format, you can define a custom naming str * When the binding names are projected as files, by default the predefined `none` naming strategy is applied, and the binding names do not change. * When the binding names are projected as environment variables and no `namingStrategy` is defined, by default the predefined `uppercase` naming strategy is applied. * You can override the predefined naming strategies by defining custom naming strategies using different combinations of custom binding names and predefined post-processing functions. -==== +==== \ No newline at end of file diff --git a/modules/sbo-rbac-requirements.adoc b/modules/sbo-rbac-requirements.adoc index 9a0cabf882b8..5a025aa81f6d 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: @@ -37,4 +40,4 @@ rules: ... ---- -This cluster role can be deployed during the installation of the backing service Operator. +This cluster role can be deployed during the installation of the backing service Operator. \ No newline at end of file diff --git a/modules/sbo-release-notes-1-0-1.adoc b/modules/sbo-release-notes-1-0-1.adoc new file mode 100644 index 000000000000..d0a990aefd96 --- /dev/null +++ b/modules/sbo-release-notes-1-0-1.adoc @@ -0,0 +1,87 @@ +[id="sbo-release-notes-1-0-1_{context}"] += Release notes for {servicebinding-title} 1.0.1 + +{servicebinding-title} is now available on {product-title} 4.7, 4.8 and 4.9. + +{servicebinding-title} 1.0.1 supports OpenShift Container Platform 4.9 and later running on: + +* IBM Power Systems +* IBM Z and LinuxONE + +The custom resource definition (CRD) of the {servicebinding-title} 1.0.1 supports the following APIs: + +* *Service Binding* with the `binding.operators.coreos.com` API group. +* *Service Binding (Spec API Tech Preview)* with the `servicebinding.io` API group. ++ +[IMPORTANT] +==== +*Service Binding (Spec API Tech Preview)* with the `servicebinding.io` API group is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. + +For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/. +==== + +[id="support-matrix-1-0-1_{context}"] +== Support matrix + +Some features in this release are currently in Technology Preview. These experimental features are not intended for production use. + +link:https://access.redhat.com/support/offerings/techpreview[Technology Preview Features Support Scope] + +In the table below, features are marked with the following statuses: + +- *TP*: _Technology Preview_ + +- *GA*: _General Availability_ + +Note the following scope of support on the Red Hat Customer Portal for these features: + +.Support matrix +[cols="1,1",options="header"] +|=== +| Feature | {servicebinding-title} 1.0.1 +| `binding.operators.coreos.com` API group +| GA +| `servicebinding.io` API group +| TP +|=== + + +[id="fixed-issues-1-0-1_{context}"] +== Fixed issues +* Before this update, binding the data values from a `Cluster` custom resource (CR) of the `postgresql.k8s.enterpriesedb.io/v1` API collected the `host` binding value from the `.metadata.name` field of the CR. The collected binding value is an incorrect hostname and the correct hostname is available at the `.status.writeService` field. With this update, the annotations that the {servicebinding-title} uses to expose the binding data values from the backing service CR are now modified to collect the `host` binding value from the `.status.writeService` field. The {servicebinding-title} uses these modified annotations to project the correct hostname in the `host` and `provider` bindings. link:https://issues.redhat.com/browse/APPSVC-1040[APPSVC-1040] +* Before this update, when you would bind a `PostgresCluster` CR of the `postgres-operator.crunchydata.com/v1beta1` API, the binding data values did not include the values for the database certificates. As a result, the application failed to connect to the database. With this update, modifications to the annotations that the {servicebinding-title} uses to expose the binding data from the backing service CR now include the database certificates. The {servicebinding-title} uses these modified annotations to project the correct `ca.crt`, `tls.crt`, and `tls.key` certificate files. link:https://issues.redhat.com/browse/APPSVC-1045[APPSVC-1045] +* Before this update, when you would bind a `PerconaXtraDBCluster` custom resource (CR) of the `pxc.percona.com` API, the binding data values did not include the `port` and `database` values. These binding values along with the others already projected are necessary for an application to successfully connect to the database service. With this update, the annotations that the {servicebinding-title} uses to expose the binding data values from the backing service CR are now modified to project the additional `port` and `database` binding values. The {servicebinding-title} uses these modified annotations to project the complete set of binding values that the application can use to successfully connect to the database service. link:https://issues.redhat.com/browse/APPSVC-1073[APPSVC-1073] + + +[id="known-issues-1-0-1_{context}"] +== Known issues +* Currently, when you install the {servicebinding-title} in the single namespace installation mode, the absence of an appropriate namespace-scoped role-based access control (RBAC) rule prevents the successful binding of an application to a few known Operator-backed services that the {servicebinding-title} can automatically detect and bind to. In addition, the following error message is generated: ++ +.Example error message +---- +`postgresclusters.postgres-operator.crunchydata.com "hippo" is forbidden: + User "system:serviceaccount:my-petclinic:service-binding-operator" cannot + get resource "postgresclusters" in API group "postgres-operator.crunchydata.com" + in the namespace "my-petclinic"` +---- ++ +Workaround 1: Install the {servicebinding-title} in the `all namespaces` installation mode. As a result, the appropriate cluster-scoped RBAC rule now exists and the binding succeeds. ++ +Workaround 2: If you cannot install the {servicebinding-title} in the `all namespaces` installation mode, install the following role binding into the namespace where the {servicebinding-title} is installed: ++ +.Example: Role binding for Crunchy Postgres Operator +[source,yaml] +---- +kind: RoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: service-binding-crunchy-postgres-viewer +subjects: + - kind: ServiceAccount + name: service-binding-operator +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: service-binding-crunchy-postgres-viewer-role +---- +link:https://issues.redhat.com/browse/APPSVC-1062[APPSVC-1062] \ No newline at end of file diff --git a/modules/sbo-unbinding-workloads-from-a-backing-service.adoc b/modules/sbo-unbinding-workloads-from-a-backing-service.adoc index 3b491fb90bf9..f1c3b7b2adaf 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. \ No newline at end of file