Getting started with service binding

The Service Binding Operator 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 Service Binding Operator to create a binding connection between the application and the database service.

Prerequisites

  • You have access to an OKD cluster using an account with cluster-admin permissions.

  • You have installed the oc CLI.

  • You have installed Service Binding Operator from OperatorHub.

  • You have installed the 5.1.2 version of 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.

    You can create the namespace using the oc create namespace my-petclinic command.

Creating a PostgreSQL database instance

To create a PostgreSQL database instance, you must create a PostgresCluster custom resource (CR) and configure the database.

Procedure

  1. Create the PostgresCluster CR in the my-petclinic namespace by running the following command in shell:

    1. $ oc apply -n my-petclinic -f - << EOD
    2. ---
    3. apiVersion: postgres-operator.crunchydata.com/v1beta1
    4. kind: PostgresCluster
    5. metadata:
    6.   name: hippo
    7. spec:
    8.   image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres:ubi8-14.4-0
    9.   postgresVersion: 14
    10.   instances:
    11.     - name: instance1
    12.       dataVolumeClaimSpec:
    13.         accessModes:
    14.         - "ReadWriteOnce"
    15.         resources:
    16.           requests:
    17.             storage: 1Gi
    18.   backups:
    19.     pgbackrest:
    20.       image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbackrest:ubi8-2.38-0
    21.       repos:
    22.       - name: repo1
    23.         volume:
    24.           volumeClaimSpec:
    25.             accessModes:
    26.             - "ReadWriteOnce"
    27.             resources:
    28.               requests:
    29.                 storage: 1Gi
    30. EOD

    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

    1. postgrescluster.postgres-operator.crunchydata.com/hippo created

  2. After you have created the database instance, ensure that all the pods in the my-petclinic namespace are running:

    1. $ oc get pods -n my-petclinic

    The output, which takes a few minutes to display, verifies that the database is created and configured:

    Example output

    1. NAME                                     READY    STATUS      RESTARTS   AGE
    2. hippo-backup-9rxm-88rzq                   0/1     Completed   0          2m2s
    3. hippo-instance1-6psd-0                    4/4     Running     0          3m28s
    4. hippo-repo-host-0                         2/2     Running     0          3m28s

    After the database is configured, you can deploy the sample application and connect it to the database service.

Deploying the Spring PetClinic sample application

To deploy the Spring PetClinic sample application on an OKD cluster, you must use a deployment configuration and configure your local environment to be able to test the application.

Procedure

  1. Deploy the spring-petclinic application with the PostgresCluster custom resource (CR) by running the following command in shell:

    1. $ oc apply -n my-petclinic -f - << EOD
    2. ---
    3. apiVersion: apps/v1
    4. kind: Deployment
    5. metadata:
    6.   name: spring-petclinic
    7.   labels:
    8.     app: spring-petclinic
    9. spec:
    10.   replicas: 1
    11.   selector:
    12.     matchLabels:
    13.       app: spring-petclinic
    14.   template:
    15.     metadata:
    16.       labels:
    17.         app: spring-petclinic
    18.     spec:
    19.       containers:
    20.         - name: app
    21.           image: quay.io/service-binding/spring-petclinic:latest
    22.           imagePullPolicy: Always
    23.           env:
    24.           - name: SPRING_PROFILES_ACTIVE
    25.             value: postgres
    26.           ports:
    27.           - name: http
    28.             containerPort: 8080
    29. ---
    30. apiVersion: v1
    31. kind: Service
    32. metadata:
    33.   labels:
    34.     app: spring-petclinic
    35.   name: spring-petclinic
    36. spec:
    37.   type: NodePort
    38.   ports:
    39.     - port: 80
    40.       protocol: TCP
    41.       targetPort: 8080
    42.   selector:
    43.     app: spring-petclinic
    44. EOD

    The output verifies that the Spring PetClinic sample application is created and deployed:

    Example output

    1. deployment.apps/spring-petclinic created
    2. service/spring-petclinic created

    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

  2. Verify that the application is not yet connected to the database service by running the following command:

    1. $ oc get pods -n my-petclinic

    The output takes a few minutes to display the CrashLoopBackOff status:

    Example output

    1. NAME                                READY   STATUS             RESTARTS      AGE
    2. 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.

  3. Expose the service to create a route for your application:

    1. $ oc expose service spring-petclinic -n my-petclinic

    The output verifies that the spring-petclinic service is exposed and a route for the Spring PetClinic sample application is created:

    Example output

    1. route.route.openshift.io/spring-petclinic exposed

You can now use the Service Binding Operator to connect the application to the database service.

Connecting the Spring PetClinic sample application to the PostgreSQL database service

To connect the sample application to the database service, you must create a ServiceBinding custom resource (CR) that triggers the Service Binding Operator to project the binding data into the application.

Procedure

  1. Create a ServiceBinding CR to project the binding data:

    1. $ oc apply -n my-petclinic -f - << EOD
    2. ---
    3. apiVersion: binding.operators.coreos.com/v1alpha1
    4. kind: ServiceBinding
    5. metadata:
    6.   name: spring-petclinic-pgcluster
    7. spec:
    8.   services: (1)
    9.     - group: postgres-operator.crunchydata.com
    10.       version: v1beta1
    11.       kind: PostgresCluster (2)
    12.       name: hippo
    13.   application: (3)
    14.     name: spring-petclinic
    15.     group: apps
    16.     version: v1
    17.     resource: deployments
    18. EOD
    1Specifies a list of service resources.
    2The CR of the database.
    3The sample application that points to a Deployment or any other similar resource with an embedded PodSpec.

    The output verifies that the ServiceBinding CR is created to project the binding data into the sample application.

    Example output

    1. servicebinding.binding.operators.coreos.com/spring-petclinic created

  2. Verify that the request for service binding is successful:

    1. $ oc get servicebindings -n my-petclinic

    Example output

    1. NAME                         READY   REASON              AGE
    2. 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. For example, all the values from the Secret resource are projected into the bindings/spring-petclinic-pgcluster directory.

    Optionally, you can also verify that the files in the application contain the projected binding data, by printing out the directory contents:

    1. $ 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
    1. /bindings/spring-petclinic-pgcluster/username: <username>
    2. /bindings/spring-petclinic-pgcluster/password: <password>
    3. /bindings/spring-petclinic-pgcluster/host: hippo-primary.my-petclinic.svc
    4. /bindings/spring-petclinic-pgcluster/port: 5432
    5. /bindings/spring-petclinic-pgcluster/type: postgresql

  3. Set up the port forwarding from the application port to access the sample application from your local environment:

    1. $ oc port-forward --address 0.0.0.0 svc/spring-petclinic 8080:80 -n my-petclinic

    Example output

    1. Forwarding from 0.0.0.0:8080 -> 8080
    2. Handling connection for 8080

  4. Access http://localhost:8080/petclinic.

    You can now remotely access the Spring PetClinic sample application at localhost:8080 and see that the application is now connected to the database service.

Additional Resources