Skip to content

Commit 981c917

Browse files
PreeticpPreeticp
authored
Merge pull request #37088 from Srivaralakshmi/sbo-getting-started
Document for Getting started with service binding
2 parents 045c405 + 76b05c4 commit 981c917

5 files changed

+366
-0
lines changed

‎_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1612,6 +1612,8 @@ Topics:
16121612
File: understanding-service-binding-operator
16131613
- Name: Installing Service Binding Operator
16141614
File: installing-sbo
1615+
- Name: Getting started with service binding
1616+
File: getting-started-with-service-binding
16151617
- Name: Connecting an application to a service using the Developer perspective
16161618
File: odc-connecting-an-application-to-a-service-using-the-developer-perspective
16171619
- Name: Projecting binding data

‎applications/connecting_applications_to_services/getting-started-with-service-binding.adoc

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
[id="getting-started-with-service-binding"]
2+
= Getting started with service binding
3+
include::modules/common-attributes.adoc[]
4+
include::modules/servicebinding-document-attributes.adoc[]
5+
:context: getting-started-with-service-binding
6+
7+
toc::[]
8+
9+
{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.
10+
11+
// Prerequisites for getting started with Service Binding Operator
12+
[discrete]
13+
== Prerequisites
14+
15+
* You have access to an {product-title} cluster using an account with `cluster-admin` permissions.
16+
* You have installed the `oc` CLI.
17+
* You have installed PostgreSQL `psql` CLI.
18+
* You have installed {servicebinding-title} from OperatorHub.
19+
* 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.
20+
21+
//Creating a PostgreSQL database instance
22+
include::modules/sbo-creating-a-postgresql-database-instance.adoc[leveloffset=+1]
23+
24+
//Deploying the Spring PetClinic sample application
25+
include::modules/sbo-deploying-the-spring-petclinic-sample-application.adoc[leveloffset=+1]
26+
27+
//Connecting the Spring PetClinic sample application to the PostgreSQL database service
28+
include::modules/sbo-connecting-spring-petclinic-sample-app-to-postgresql-database-service.adoc[leveloffset=+1]
29+
30+
== Additional Resources
31+
//Commenting out the link to avoid Build errors. The entire SBO section is new with topics. Links will work fine when all the SBO doc PRs will be merged.
32+
* Installing {servicebinding-title}.
33+
* Creating applications using the Developer perspective.
34+
* Managing resources from custom resource definitions.

‎modules/sbo-connecting-spring-petclinic-sample-app-to-postgresql-database-service.adoc

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
= Connecting the Spring PetClinic sample application to the PostgreSQL database service
2+
[id="sbo-connecting-spring-petclinic-sample-app-to-postgresql-database-service_{context}"]
3+
4+
To connect the sample application to the database service, you must create a `ServiceBinding` custom resource (CR) that triggers the {servicebinding-title} to project the binding data into the application.
5+
6+
[discrete]
7+
.Procedure
8+
9+
. Create a `ServiceBinding` CR to project the binding data:
10+
+
11+
----
12+
$ oc apply -f - << EOD
13+
---
14+
apiVersion: binding.operators.coreos.com/v1alpha1
15+
kind: ServiceBinding
16+
metadata:
17+
name: spring-petclinic-rest
18+
namespace: my-postgresql
19+
spec:
20+
services: <1>
21+
- group: postgres-operator.crunchydata.com
22+
version: v1beta1
23+
kind: PostgresCluster <2>
24+
name: hippo
25+
- group: ""
26+
version: v1
27+
kind: Secret
28+
name: hippo-pguser-hippo
29+
application: <3>
30+
name: spring-petclinic-rest
31+
group: apps
32+
version: v1
33+
resource: deployments
34+
----
35+
<1> Specifies a list of service resources.
36+
<2> The CR of the database.
37+
<3> The sample application that points to a Deployment or any other similar resource with an embedded PodSpec.
38+
+
39+
The output verifies that the `ServiceBinding` CR is created to project the binding data into the sample application.
40+
+
41+
.Example output
42+
----
43+
servicebinding.binding.operators.coreos.com/spring-petclinic-rest created
44+
----
45+
46+
. To verify that the binding is successful, check the status conditions of the binding resource:
47+
+
48+
----
49+
$ oc get servicebindings spring-petclinic-rest -n my-postgresql -o jsonpath-as-json='{.status.conditions}'
50+
----
51+
+
52+
.Example output
53+
----
54+
[
55+
[
56+
{
57+
"lastTransitionTime": "2021-09-06T13:42:28Z",
58+
"message": "",
59+
"reason": "DataCollected",
60+
"status": "True",
61+
"type": "CollectionReady",
62+
},
63+
{
64+
"lastTransitionTime": "2021-09-06T13:42:28Z",
65+
"message": "",
66+
"reason": "ApplicationUpdated",
67+
"status": "True",
68+
"type": "InjectionReady",
69+
},
70+
{
71+
"lastTransitionTime": "2021-09-06T13:42:28Z",
72+
"message": "",
73+
"reason": "ApplicationsBound",
74+
"status": "True",
75+
"type": "Ready",
76+
},
77+
],
78+
]
79+
----
80+
+
81+
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.
82+
83+
. To verify that the files in the application contain the projected binding data, use the following command in shell to print out the contents:
84+
+
85+
----
86+
$ 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
87+
----
88+
+
89+
.Example output: With all the values from the secret resource
90+
----
91+
/bindings/spring-petclinic-rest/username: hippo
92+
/bindings/spring-petclinic-rest/password: w0ZB<0j1W|K;+4*TlK7-w^z/
93+
/bindings/spring-petclinic-rest/host: hippo-pgbouncer
94+
/bindings/spring-petclinic-rest/port: 5432
95+
/bindings/spring-petclinic-rest/type: postgresql
96+
----
97+
98+
. Set up the port forwarding from the application port to access the sample application from your local environment:
99+
+
100+
----
101+
$ oc port-forward --address 0.0.0.0 svc/spring-petclinic-rest 9966:80 -n my-postgresql
102+
----
103+
104+
. Access link:http://localhost:9966/petclinic[http://localhost:9966/petclinic].
105+
+
106+
You can now remotely access the Spring PetClinic sample application at localhost:9966.
107+
108+
. To verify that the application is now connected to the database service, access the list of all pets:
109+
+
110+
----
111+
$ curl -X GET "http://localhost:9966/petclinic/api/pets" -H "accept: application/json"
112+
----
113+
+
114+
.Example output
115+
----
116+
[{"id":1,"name":"Leo","birthDate":"2000/09/07","type":{"id":1,"name":"cat"},
117+
"owner":{"id":1,"firstName":"George","lastName":"Franklin","address":"110...
118+
----
119+
+
120+
The previous output shows the initially configured sample data and verifies that the application is now connected to the database service.

‎modules/sbo-creating-a-postgresql-database-instance.adoc

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
[id="sbo-creating-a-postgresql-database-instance_{context}"]
2+
= Creating a PostgreSQL database instance
3+
4+
To create a PostgreSQL database instance, you must create a `PostgresCluster` custom resource (CR) and configure the database.
5+
6+
[discrete]
7+
.Procedure
8+
9+
. Create the `PostgresCluster` CR and the `my-postgresql` namespace by running the following command in shell:
10+
+
11+
----
12+
$ oc apply -f - << EOD
13+
---
14+
apiVersion: v1
15+
kind: Namespace
16+
metadata:
17+
name: my-postgresql
18+
---
19+
apiVersion: postgres-operator.crunchydata.com/v1beta1
20+
kind: PostgresCluster
21+
metadata:
22+
name: hippo
23+
namespace: my-postgresql
24+
annotations:
25+
service.binding: 'path={.metadata.annotations.dbsecret},objectType=Secret'
26+
dbsecret: hippo-pguser-hippo
27+
proxy: hippo-pgbouncer
28+
type: postgresql
29+
service.binding/database: path={.metadata.name}
30+
service.binding/port: path={.spec.port}
31+
service.binding/username: path={.metadata.name}
32+
service.binding/host: path={.metadata.annotations.proxy}
33+
service.binding/type: path={.metadata.annotations.type}
34+
spec:
35+
image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres-ha:centos8-13.4-0
36+
postgresVersion: 13
37+
instances:
38+
- name: instance1
39+
dataVolumeClaimSpec:
40+
accessModes:
41+
- "ReadWriteOnce"
42+
resources:
43+
requests:
44+
storage: 1Gi
45+
backups:
46+
pgbackrest:
47+
image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbackrest:centos8-2.33-2
48+
repos:
49+
- name: repo1
50+
volume:
51+
volumeClaimSpec:
52+
accessModes:
53+
- "ReadWriteOnce"
54+
resources:
55+
requests:
56+
storage: 1Gi
57+
- name: repo2
58+
volume:
59+
volumeClaimSpec:
60+
accessModes:
61+
- "ReadWriteOnce"
62+
resources:
63+
requests:
64+
storage: 1Gi
65+
proxy:
66+
pgBouncer:
67+
image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbouncer:centos8-1.15-2
68+
EOD
69+
----
70+
+
71+
The annotations added in this `PostgresCluster` CR help in enabling the service binding connection and trigger the Operator reconciliation.
72+
+
73+
The output verifies that the database instance is created:
74+
+
75+
.Example output
76+
----
77+
namespace/my-postgresql configured
78+
postgrescluster.postgres-operator.crunchydata.com/hippo created
79+
----
80+
81+
. After you have created the database instance, ensure that all the pods in `my-postgresql` namespace are running (it will take a few minutes):
82+
+
83+
----
84+
$ oc get pods -n my-postgresql
85+
----
86+
+
87+
The output verifies that the database is created:
88+
+
89+
.Example output
90+
----
91+
NAME READY STATUS RESTARTS AGE
92+
hippo-backup-6th6--1-28849 0/1 Completed 0 1m
93+
hippo-instance1-sl4r-0 2/2 Running 0 2m
94+
hippo-pgbouncer-8454474bc7-lhcn9 2/2 Running 0 2m
95+
----
96+
+
97+
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.
98+
99+
. 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:
100+
+
101+
----
102+
$ cat << EOD | bash
103+
#!/bin/bash
104+
105+
export pgo_cluster_name=hippo
106+
export cluster_namespace=my-postgresql
107+
export pgo_cluster_username=hippo
108+
export PGPASSWORD=\$(oc -n "\${cluster_namespace}" get secrets \
109+
"\${pgo_cluster_name}-pguser-\${pgo_cluster_username}" -o "jsonpath={.data['password']}" | base64 -d)
110+
nohup oc -n \${cluster_namespace} port-forward svc/hippo-pgbouncer 5432:5432 &
111+
sleep 5
112+
curl -LO https://raw.githubusercontent.com/spring-petclinic/spring-petclinic-rest/master/src/main/resources/db/postgresql/initDB.sql
113+
psql -h localhost -U "\${pgo_cluster_username}" "\${pgo_cluster_name}" -f initDB.sql
114+
curl -LO https://raw.githubusercontent.com/spring-petclinic/spring-petclinic-rest/master/src/main/resources/db/postgresql/populateDB.sql
115+
psql -h localhost -U "\${pgo_cluster_username}" "\${pgo_cluster_name}" -f populateDB.sql
116+
EOD
117+
----
118+
+
119+
The output in the terminal shows you that the database is being configured for the application.
120+
121+
After the database is configured, you can deploy the sample application and connect it to the database service.

‎modules/sbo-deploying-the-spring-petclinic-sample-application.adoc

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
[id="sbo-deploying-the-spring-petclinic-sample-application_{context}"]
2+
= Deploying the Spring PetClinic sample application
3+
4+
To deploy the Spring PetClinic sample application on an {product-title} cluster, you must use a deployment configuration and configure your local environment to be able to test the application.
5+
6+
[discrete]
7+
.Procedure
8+
9+
. Deploy the `spring-petclinic-rest` application with the `PostgresCluster` custom resource (CR) by running the following command in shell:
10+
+
11+
----
12+
$ oc apply -f - << EOD
13+
---
14+
apiVersion: apps/v1
15+
kind: Deployment
16+
metadata:
17+
name: spring-petclinic-rest
18+
namespace: my-postgresql
19+
labels:
20+
app: spring-petclinic-rest
21+
spec:
22+
replicas: 1
23+
selector:
24+
matchLabels:
25+
app: spring-petclinic-rest
26+
template:
27+
metadata:
28+
labels:
29+
app: spring-petclinic-rest
30+
spec:
31+
containers:
32+
- name: application
33+
image: quay.io/baijum/spring-petclinic-rest:latest
34+
env:
35+
- name: SPRING_PROFILES_ACTIVE
36+
value: postgresql,spring-data-jpa
37+
ports:
38+
- name: http
39+
containerPort: 9966
40+
---
41+
apiVersion: v1
42+
kind: Service
43+
metadata:
44+
name: spring-petclinic-rest
45+
namespace: my-postgresql
46+
spec:
47+
ports:
48+
- port: 80
49+
targetPort: 9966
50+
selector:
51+
app: spring-petclinic-rest
52+
EOD
53+
----
54+
+
55+
The output verifies that the Spring PetClinic sample application is created and deployed:
56+
+
57+
.Example output
58+
----
59+
deployment.apps/spring-petclinic-rest created
60+
service/spring-petclinic-rest created
61+
----
62+
63+
. Set up port forwarding from the application port to access the sample application from your local environment:
64+
+
65+
----
66+
$ oc port-forward --address 0.0.0.0 svc/spring-petclinic-rest 9966:80 -n my-postgresql
67+
----
68+
69+
. Access link:http://localhost:9966/petclinic[http://localhost:9966/petclinic].
70+
+
71+
You can now remotely access the Spring PetClinic sample application at localhost:9966.
72+
+
73+
[NOTE]
74+
====
75+
The application is not yet connected to the database service. If you try to interact with the application, it will return errors.
76+
====
77+
+
78+
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:
79+
+
80+
----
81+
$ curl -X GET "http://localhost:9966/petclinic/api/pets" -H "accept: application/json"
82+
83+
{"className":"org.springframework.transaction.CannotCreateTransactionException","exMessage":"Could
84+
not open JPA EntityManager for transaction; nested exception is
85+
org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC
86+
Connection"}
87+
----
88+
89+
You can now use the {servicebinding-title} to connect the application to the database service.

0 commit comments

Comments
 (0)