Binding workloads using Service Binding Operator

Naming strategies
Advanced binding options
- Changing the binding names before projecting them into the workload
- Composing custom binding data
Binding secondary workloads that are not compliant with PodSpec
- Configuring the custom location of the container path
- Configuring the custom location of the secret path
Unbinding workloads from a backing service
Additional resources

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

apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
    name: spring-petclinic-pgcluster
    namespace: my-petclinic
spec:
    services: (1)
    - group: postgres-operator.crunchydata.com
      version: v1beta1
      kind: PostgresCluster
      name: hippo
    application: (2)
      name: spring-petclinic
      group: apps
      version: v1
      resource: deployments

1	Specifies a list of service resources.
2	The sample application that points to a deployment or any other similar resource with an embedded PodSpec.

As shown in the previous example, you can also directly use a ConfigMap or a Secret itself as a service resource to be used as a source of binding data.

Naming strategies

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).

A backing service projects the binding names as files or environment variables into the workload. If a workload expects the projected binding names in a particular format, but the binding names to be projected from the backing service are not available in that format, then you can change the binding names using naming strategies.

Predefined post-processing functions

While using naming strategies, depending on the expectations or requirements of your workload, you can use the following predefined post-processing functions in any combination to convert the character strings:

upper: Converts the character strings into capital or uppercase letters.
lower: Converts the character strings into lowercase letters.
title: Converts the character strings where the first letter of each word is capitalized except for certain minor words.

Predefined naming strategies

Binding names declared through annotations are processed for their name change before their projection into the workload according to the following predefined naming strategies:

none: When applied, there are no changes in the binding names.

Example

After the template compilation, the binding names take the {{ .name }} form.
```
host: hippo-pgbouncer
port: 5432
```
upper: Applied when no namingStrategy is defined. When applied, converts all the character strings of the binding name key into capital or uppercase letters.

Example

After the template compilation, the binding names take the {{ .service.kind | upper}}_{{ .name | upper }} form.
```
DATABASE_HOST: hippo-pgbouncer
DATABASE_PORT: 5432
```
If your workload requires a different format, you can define a custom naming strategy and change the binding name using a prefix and a separator, for example, PORT_DATABASE.

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.

Advanced binding options

Advanced binding options are available only for the binding.operators.coreos.com API group.

Changing the binding names before projecting them into the workload

You can specify the rules to change the binding names in the .spec.namingStrategy attribute of the ServiceBinding custom resource (CR). For example, consider a Spring PetClinic sample application that connects to the PostgreSQL database. In this case, the PostgreSQL database service exposes the host and port fields of the database to use for binding. The Spring PetClinic sample application can access this exposed binding data through the binding names.

Example: Spring PetClinic sample application in the ServiceBinding CR

...
    application:
      name: spring-petclinic
      group: apps
      version: v1
      resource: deployments
...

Example: PostgreSQL database service in the ServiceBinding CR

...
    services:
    - group: postgres-operator.crunchydata.com
      version: v1beta1
      kind: PostgresCluster
      name: hippo
...

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

DATABASE_HOST: hippo-pgbouncer

where:

`DATABASE`	Specifies the `kind` backend service.
`HOST`	Specifies the binding name.

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

POSTGRESQL_DATABASE_HOST_ENV: hippo-pgbouncer
POSTGRESQL_DATABASE_PORT_ENV: 5432

The following items describe the expressions defined in the POSTGRESQL_{{ .service.kind | upper }}_{{ .name | upper }}_ENV naming strategy:

.name: Refers to the binding name exposed by the backing service. In the previous example, the binding names are HOST and PORT.
.service.kind: Refers to the kind of service resource whose binding names are changed with the naming strategy.
upper: String function used to post-process the character string while compiling the Go template string.
POSTGRESQL: Prefix of the custom binding name.
ENV: Suffix of the custom binding name.

Similar to the previous example, you can define the string templates in namingStrategy to define how each key of the binding names should be prepared by the service binding request.

Composing custom binding data

As an application developer, you can compose custom binding data under the following circumstances:

The backing service does not expose binding data.
The values exposed are not available in the required format as expected by the workload.

For example, consider a case where the backing service CR exposes the host, port, and database user as binding data, but the workload requires that the binding data be consumed as a connection string. You can compose custom binding data using attributes in the Kubernetes resource representing the backing service.

Example

apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
    name: spring-petclinic-pgcluster
    namespace: my-petclinic
spec:
    services:
    - group: postgres-operator.crunchydata.com
      version: v1beta1
      kind: PostgresCluster
      name: hippo (1)
      id: postgresDB (2)
    - group: ""
      version: v1
      kind: Secret
      name: hippo-pguser-hippo
      id: postgresSecret
    application:
      name: spring-petclinic
      group: apps
      version: v1
      resource: deployments
    mappings:
      ## From the database service
      - name: JDBC_URL
        value: 'jdbc:postgresql://{{ .postgresDB.metadata.annotations.proxy }}:{{ .postgresDB.spec.port }}/{{ .postgresDB.metadata.name }}'
      ## From both the services!
      - name: CREDENTIALS
        value: '{{ .postgresDB.metadata.name }}{{ translationService.postgresSecret.data.password }}'
      ## Generate JSON
      - name: DB_JSON (3)
        value: {{ json .postgresDB.status }} (4)

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.

Binding secondary workloads that are not compliant with PodSpec

A typical scenario in service binding involves configuring the backing service, the workload (deployment), and Service Binding Operator. 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 Service Binding Operator.

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.

Service Binding Operator 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.

Configuring the custom location of the container path

Consider a secondary workload CR, which is not compliant with the PodSpec and has containers located at the spec.containers path:

Example: Secondary workload CR

apiVersion: "operator.sbo.com/v1"
kind: SecondaryWorkload
metadata:
    name: secondary-workload
spec:
    containers:
    - name: hello-world
      image: quay.io/baijum/secondary-workload:latest
      ports:
      - containerPort: 8080

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

apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
    name: spring-petclinic-pgcluster
spec:
    services:
    - group: postgres-operator.crunchydata.com
      version: v1beta1
      kind: PostgresCluster
      name: hippo
      id: postgresDB
    - group: ""
      version: v1
      kind: Secret
      name: hippo-pguser-hippo
      id: postgresSecret
    application: (1)
      name: spring-petclinic
      group: apps
      version: v1
      resource: deployments
    application: (2)
      name: secondary-workload
      group: operator.sbo.com
      version: v1
      resource: secondaryworkloads
      bindingPath:
        containersPath: spec.containers (3)

1	The sample application that points to a deployment or any other similar resource with an embedded PodSpec.
2	The secondary workload, which is not compliant with the PodSpec.
3	The custom location of the container path.

After you specify the location of the container path, Service Binding Operator generates the binding data, which becomes available in the container path specified in the secondary workload of the ServiceBinding CR.

The following example shows the spec.containers path with the envFrom and secretRef fields:

Example: Secondary workload CR with the envFrom and secretRef fields

apiVersion: "operator.sbo.com/v1"
kind: SecondaryWorkload
metadata:
    name: secondary-workload
spec:
    containers:
    - env: (1)
      - name: ServiceBindingOperatorChangeTriggerEnvVar
        value: "31793"
      envFrom:
      - secretRef:
          name: secret-resource-name (2)
      image: quay.io/baijum/secondary-workload:latest
      name: hello-world
      ports:
      - containerPort: 8080
      resources: {}

1	Unique array of containers with values generated by the Service Binding Operator. These values are based on the backing service CR.
2	Name of the `Secret` resource generated by the Service Binding Operator.

Configuring the custom location of the secret path

Consider a secondary workload CR, which is not compliant with the PodSpec, with only the secret at the spec.secret path:

Example: Secondary workload CR

apiVersion: "operator.sbo.com/v1"
kind: SecondaryWorkload
metadata:
    name: secondary-workload
spec:
    secret: ""

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

apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
    name: spring-petclinic-pgcluster
spec:
...
    application: (1)
      name: secondary-workload
      group: operator.sbo.com
      version: v1
      resource: secondaryworkloads
      bindingPath:
        secretPath: spec.secret (2)
...

1	The secondary workload, which is not compliant with the PodSpec.
2	The custom location of the secret path that contains the name of the `Secret` resource.

After you specify the location of the secret path, Service Binding Operator generates the binding data, which becomes available in the secret path specified in the secondary workload of the ServiceBinding CR.

The following example shows the spec.secret path with the binding-request value:

Example: Secondary workload CR with the binding-request value

...
apiVersion: "operator.sbo.com/v1"
kind: SecondaryWorkload
metadata:
    name: secondary-workload
spec:
    secret: binding-request-72ddc0c540ab3a290e138726940591debf14c581 (1)
...

1	Unique name of the `Secret` resource generated by the Service Binding Operator.

Unbinding workloads from a backing service

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:
```
$ oc delete ServiceBinding <.metadata.name>
```
Example
```
$ oc delete ServiceBinding spring-petclinic-pgcluster
```
where:

spring-petclinic-pgcluster
Specifies the name of the ServiceBinding CR.

Naming strategies

Advanced binding options

Changing the binding names before projecting them into the workload

Composing custom binding data

Binding secondary workloads that are not compliant with PodSpec

Configuring the custom location of the container path

Configuring the custom location of the secret path

Unbinding workloads from a backing service

Additional resources