Workload Projection is a process of obtaining the configuration for services from the Kubernetes cluster. This configuration takes the form of directory structures that follow certain conventions and is attached to an application or to a service as a mounted volume. The kubernetes-service-binding extension uses this directory structure to create configuration sources, which allows you to configure additional modules, such as databases or message brokers.

You can use workload projection during application development to connect their application to a development database or other locally-run services without changing the actual application code or configuration.

For an example of a workload projection where the directory structure is included in the test resources and passed to integration test, see the Kubernetes Service Binding datasource GitHub repository.

The Service Binding Operator is an Operator that implements Service Binding Specification for Kubernetes and is meant to simplify the binding of services to an application. Containerized applications that support Workload Projection obtain service binding information in the form of volume mounts. The Service Binding Operator reads binding service information and mounts it to the application containers that need it.

The correlation between application and bound services is expressed through the ServiceBinding resources, which declares the intent of what services are meant to be bound to what application.

The Service Binding Operator watches for ServiceBinding resources, which inform the Operator what applications are meant to be bound with what services. When a listed application is deployed, the Service Binding Operator collects all the binding information that must be passed to the application, then upgrades the application container by attaching a volume mount with the binding information.

The Service Binding Operator completes the following actions:

• Observes ServiceBinding resources for workloads intended to be bound to a particular service

• Applies the binding information to the workload using volume mounts

The following chapter describes the automatic and semi-automatic service binding approaches and their use cases. With either approach, the kubernetes-service-binding extension generates a ServiceBinding resource. With the semi-automatic approach, users must provide a configuration for target services manually. With the automatic approach, for a limited set of services generating the ServiceBinding resource, no additional configuration is needed.

A service binding process starts with a user specification of required services that will be bound to a certain application. This expression is summarized in the ServiceBinding resource that is generated by the kubernetes-service-binding extension. The use of the kubernetes-service-binding extensions helps users to generate ServiceBinding resources with minimal configuration, therefore simplifying the process overall.

The Service Binding Operator responsible for the binding process then reads the information from the ServiceBinding resource and mounts the required files to a container accordingly.

• An example of the ServiceBinding resource:

  apiVersion: binding.operators.coreos.com/v1beta1    1
  kind: ServiceBinding
  metadata:
   name: binding-request
   namespace: service-binding-demo    2
  spec:
   application:
     name: java-app
     group: apps
     version: v1
     resource: deployments
   services:
   - group: postgres-operator.crunchydata.com
     version: v1beta1
     kind: Database
     name: db-demo
     id: postgresDB

  • The quarkus-kubernetes-service-binding extension provides a more compact way of expressing the same information. For example:

    quarkus.kubernetes-service-binding.services.db-demo.api-version=postgres-operator.crunchydata.com/v1beta1   1
    quarkus.kubernetes-service-binding.services.db-demo.kind=Database   2

After adding the earlier configuration properties inside your application.properties, the quarkus-kubernetes, in combination with the quarkus-kubernetes-service-binding extension, automatically generates the ServiceBinding resource.

The earlier mentioned db-demo property-configuration identifier now has a double role and also completes the following actions:

• Correlates and groups api-version and kind properties together

• Defines the name property for the custom resource with a possibility for a later edit. For example:

  quarkus.kubernetes-service-binding.services.db-demo.api-version=postgres-operator.crunchydata.com/v1beta1
  quarkus.kubernetes-service-binding.services.db-demo.kind=Database
  quarkus.kubernetes-service-binding.services.db-demo.name=my-db

Use the following information to generate a ServiceBinding resource semi-automatically. You will also learn more about the OpenShift deployment process, including how to install operators to configure and deploy an application.

The following procedure installs Service Binding Operator and the PostgreSQL Operator from Crunchy Data. Note that PostgreSQL Operator from Crunchy Data is a third-party software with its support policies and terms of use. Then, the procedure creates a PostgreSQL cluster, a simple application, and finally, deploys it and binds it to the provisioned cluster.

1. Install the Service Binding Operator version 1.0 and higher using the Installing the Service Binding Operator from the OpenShift Container Platform web UI procedure.

   1. Verify the installation:

      oc get csv -n openshift-operators -w

      • When the phase of the Service Binding Operator is set to Succeeded, proceed to the next step.

2. Install the PostgreSQL Crunchy Operator using the Deploy & use tab of the Crunchy PostgreSQL Operator product page.

   1. Verify the installation:

      oc get csv -n openshift-operators -w

      • When the phase of the operator is set to Succeeded, proceed to the next step.

3. Create a PostgreSQL cluster:

   1. Create a new OpenShift namespace, in the space of which you will create a cluster and deploy your application later on. Throughout this procedure, the namespace is called demo.

      oc new-project demo

   2. Create the following custom resource and save it as pg-cluster.yml:

      apiVersion: postgres-operator.crunchydata.com/v1beta1
      kind: PostgresCluster
      metadata:
        name: hippo
      spec:
        openshift: true
        image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres:ubi8-14.2-1
        postgresVersion: 14
        instances:
          - name: instance1
            dataVolumeClaimSpec:
              accessModes:
              - "ReadWriteOnce"
              resources:
                requests:
                  storage: 1Gi
        backups:
          pgbackrest:
            image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbackrest:ubi8-2.38-0
            repos:
            - name: repo1
              volume:
                volumeClaimSpec:
                  accessModes:
                  - "ReadWriteOnce"
                  resources:
                    requests:
                      storage: 1Gi

      This YAML has been reused from Service Binding Operator Quickstart.

   3. Apply the created custom resource:

      oc apply -f ~/pg-cluster.yml

      This command assumes that you saved the pg-cluster.yml file in HOME.

   4. Check the Pods to verify the installation:

      oc get pods -n demo

      • Wait for the Pods to get into the READY state, which signals the installation is complete.

4. Create a Quarkus application that binds to the PostgreSQL database.

   • The application we are going to create is going to be a simple todo application that will connect to PostgreSQL by using hibernate and panache.

     1. Generate the application:

        mvn com.redhat.quarkus.platform:quarkus-maven-plugin:2.7.7.Final-redhat-00005:create \
          -DplatformGroupId=com.redhat.quarkus.platform \
          -DplatformVersion=2.7.7.Final-redhat-00005 \
          -DprojectGroupId=org.acme \
          -DprojectArtifactId=todo-example \
          -DclassName="org.acme.TodoResource" \
          -Dpath="/todo"

     2. Add all required extensions for connecting to PostgreSQL, generating all required resources, and building a container image for our application:

        ./mvnw quarkus:add-extension -Dextensions="resteasy-jackson,jdbc-postgresql,hibernate-orm-panache,openshift,kubernetes-service-binding"

     3. Create a simple entity as follows:

        package org.acme;
        
        import javax.persistence.Column;
        import javax.persistence.Entity;
        
        import io.quarkus.hibernate.orm.panache.PanacheEntity;
        
        @Entity
        public class Todo extends PanacheEntity {
        
            @Column(length = 40, unique = true)
            public String title;
        
            public boolean completed;
        
            public Todo() {
            }
        
            public Todo(String title, Boolean completed) {
                this.title = title;
            }
        
        }

     4. Expose the entity:

        package org.acme;
        
        import javax.transaction.Transactional;
        import javax.ws.rs.*;
        import javax.ws.rs.core.Response;
        import javax.ws.rs.core.Response.Status;
        import java.util.List;
        
           @Path("/todo")
           public class TodoResource {
        
               @GET
               @Path("/")
               public List<Todo> getAll() {
                 return Todo.listAll();
               }
        
               @GET
               @Path("/{id}")
               public Todo get(@PathParam("id") Long id) {
                   Todo entity = Todo.findById(id);
                   if (entity == null) {
                       throw new WebApplicationException("Todo with id of " + id + " does not exist.", Status.NOT_FOUND);
                   }
                   return entity;
               }
        
               @POST
               @Path("/")
               @Transactional
               public Response create(Todo item) {
                   item.persist();
                   return Response.status(Status.CREATED).entity(item).build();
               }
        
               @GET
               @Path("/{id}/complete")
               @Transactional
               public Response complete(@PathParam("id") Long id) {
                   Todo entity = Todo.findById(id);
                   entity.id = id;
                   entity.completed = true;
                   return Response.ok(entity).build();
               }
        
        
               @DELETE
               @Transactional
               @Path("/{id}")
               public Response delete(@PathParam("id") Long id) {
                   Todo entity = Todo.findById(id);
                   if (entity == null) {
                       throw new WebApplicationException("Todo with id of " + id + " does not exist.", Status.NOT_FOUND);
                   }
                   entity.delete();
                   return Response.noContent().build();
               }
        
           }

5. Bind to the target PostgreSQL cluster by generating a ServiceBinding resource.

   1. Provide the service coordinates to generate the binding and configure the data source:

      • apiVersion: postgres-operator.crunchydata.com/v1beta1

      • kind: PostgresCluster

      • name: pg-cluster

        This is done by setting a quarkus.kubernetes-service-binding.services.<id>. prefix as in the example below. The id is used to group properties together and can be anything.

        quarkus.kubernetes-service-binding.services.my-db.api-version=postgres-operator.crunchydata.com/v1beta1
        quarkus.kubernetes-service-binding.services.my-db.kind=PostgresCluster
        quarkus.kubernetes-service-binding.services.my-db.name=hippo
        
        quarkus.datasource.db-kind=postgresql
        quarkus.hibernate-orm.database.generation=drop-and-create
        quarkus.hibernate-orm.sql-load-script=import.sql

   2. Create an import.sql script with some initial data:

      INSERT INTO todo(id, title, completed) VALUES (nextval('hibernate_sequence'), 'Finish the blog post', false);

6. Deploy the application, including ServiceBinding, and apply it to the cluster:

   mvn clean install -Dquarkus.kubernetes.deploy=true -DskipTests

   • Wait for the deployment to finish.

The quarkus-kubernetes-service-binding extension can generate the ServiceBinding resource automatically after detecting that an application requires access to the external services that are provided by available bindable Operators.

quarkus.datasource.db-kind=postgresql

services:
 - apiVersion: postgres-operator.crunchydata.com/v1beta1
   kind: PostgresCluster
   name: postgresql

quarkus.datasource.fruits-db.db-kind=postgresql

services:
 - apiVersion: postgres-operator.crunchydata.com/v1beta1
   kind: PostgresCluster
   name: fruits-db

quarkus.datasource.fruits-db.db-kind=mysql

services:
 - apiVersion: pxc.percona.com/v1-9-0
   kind: PerconaXtraDBCluster
   name: fruits-db

quarkus.datasource.db-kind=postgresql
quarkus.kubernetes-service-binding.services.postgresql.api-version=postgres-operator.crunchydata.com/v1beta2

quarkus.datasource.fruits-db.db-kind=postgresql

quarkus.kubernetes-service-binding.services.fruits-db.api-version=postgres-operator.crunchydata.com/v1beta1
quarkus.kubernetes-service-binding.services.fruits-db.kind=PostgresCluster
quarkus.kubernetes-service-binding.services.fruits-db.name=fruits-db