×

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 Service Binding Operator enables application developers to easily bind workloads together with operator-managed backing services, without any manual procedures to configure the binding connection. For the Service Binding Operator 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 Service Binding Operator. Then, the Service Binding Operator automatically collects the binding data from the backing service and shares it with a workload to provide a consistent and predictable experience.

Methods of exposing binding data

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.

Binding data is exposed under the following circumstances:

  • Backing service is available as a provisioned service resource.

    The service you intend to connect to is compliant with the Service Binding specification. You must create a Secret resource with all the required binding data values and reference it in the backing service custom resource (CR). The detection of all the binding data values is automatic.

  • Backing service is not available as a provisioned service resource.

    You must expose the binding data from the backing service. Depending on your workload requirements and environment, you can choose any of the following methods to expose the binding data:

    • Direct secret reference

    • Generation of an intermediate secret through custom resource definition (CRD) or CR annotations

    • Generation of an intermediate secret through Operator Lifecycle Manager (OLM) descriptors

    • Detection of binding data through owned resources

Provisioned service

Provisioned service represents a backing service CR with a reference to a Secret resource placed in the .status.binding.name field of the backing service CR.

As an Operator provider or the user who creates backing services, you can use this method to be compliant with the Service Binding specification, by creating a Secret resource and referencing it in the .status.binding.name section of the backing service CR. This Secret resource must provide all the binding data values required for a workload to connect to the backing service.

The following examples show an AccountService CR that represents a backing service and a Secret resource referenced from the CR.

Example: AccountService CR
apiVersion: example.com/v1alpha1
kind: AccountService
name: prod-account-service
spec:
  ...
status:
  binding:
    name: hippo-pguser-hippo
Example: Referenced Secret resource
apiVersion: v1
kind: Secret
metadata:
  name: hippo-pguser-hippo
data:
  password: "MTBz"
  user: "Z3Vlc3Q="
  ...

When creating a service binding resource, you can directly give the details of the AccountService resource in the ServiceBinding specification as follows:

Example: ServiceBinding resource
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
  name: account-service
spec:
  ...
  services:
  - group: "example.com"
    version: v1alpha1
    kind: AccountService
    name: prod-account-service
  application:
    name: spring-petclinic-rest
    group: apps
    version: v1
    resource: deployments

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

Example: ServiceBinding resource in Specification API
apiVersion: servicebinding.io/v1alpha3
kind: ServiceBinding
metadata:
  name: account-service
spec:
  ...
  service:
    apiVersion: example.com/v1alpha1
    kind: AccountService
    name: prod-account-service
  application:
    apiVersion: apps/v1
    kind: Deployment
    name: spring-petclinic-rest

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.

Direct secret reference

You can use this method, if all the required binding data values are available in a Secret resource that you can reference in your Service Binding definition. In this method, a ServiceBinding resource directly references a Secret resource to connect to a service. All the keys in the Secret resource are exposed as binding data.

Example: Specification with the binding.operators.coreos.com API
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
  name: account-service
spec:
  ...
  services:
  - group: ""
    version: v1
    kind: Secret
    name: hippo-pguser-hippo
Example: Specification that is compliant with the servicebinding.io API
apiVersion: servicebinding.io/v1alpha3
kind: ServiceBinding
metadata:
  name: account-service
spec:
  ...
  service:
    apiVersion: v1
    kind: Secret
    name: hippo-pguser-hippo

Declaring binding data through CRD or CR annotations

You can use this method to annotate the resources of the backing service to expose the binding data with specific annotations. Adding annotations under the metadata section alters the CRs and CRDs of the backing services. Service Binding Operator detects the annotations added to the CRs and CRDs and then creates a Secret resource with the values extracted based on the annotations.

The following examples show the annotations that are added under the metadata section and a referenced ConfigMap object from a resource:

Example: Exposing binding data from a Secret object in the metadata.annotations.dbsecret custom field
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-postgresql
  annotations:
    service.binding: 'path={.metadata.name}-pguser-{.metadata.name},objectType=Secret'
    ...
Example: Exposing binding data from a ConfigMap object in the metadata.annotations.dbconfig custom field
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-postgresql
  annotations:
    service.binding: 'path={.metadata.name}-config,objectType=ConfigMap'
    ...

The previous example places the name of the config map in the metadata.annotations.dbconfig custom field and specifies to expose a single key from the config map.

Example: Referenced ConfigMap object from a resource
apiVersion: v1
kind: ConfigMap
metadata:
  name: hippo-config
data:
  db_timeout: "10s"
  user: "hippo"

Declaring binding data through OLM descriptors

You can use this method if your backing service is provided by an Operator. If your Operator is distributed as an OLM bundle, you can add OLM descriptors to describe the binding data that is to be exposed. The OLM descriptors are part of Cluster Service Version resources. The Service Binding Operator detects the OLM descriptors and then creates a Secret resource with the values extracted based on the detected OLM descriptors.

You can expose the binding data by using the specDescriptors array and statusDescriptors array. The specDescriptors array specifies a path under the .spec section of a CR. The statusDescriptors array specifies a path under the .status section of a CR.

Following are the only two fields that are used for binding the data:

  • Path: A dot-delimited path of the field on the object as described by the descriptor.

  • X-Descriptors: Defines the binding data.

The following examples show how to define an X-Descriptor depending on the resource to which you point the path:

Example: X-Descriptor definition for exposing a secret
- path: data.dbConfiguration
  x-descriptors:
  - urn:alm:descriptor:io.kubernetes:Secret
  - service.binding
Example: X-Descriptor definition for exposing a config map
- path: data.dbConfiguration
  x-descriptors:
  - urn:alm:descriptor:io.kubernetes:ConfigMap
  - service.binding
  • You must have a service.binding entry in the X-Descriptors to identify that it is a configuration for service binding.

  • The absence of the Secret or ConfigMap specific X-Descriptors indicates that the descriptor is referencing the binding data value at the given path.

Detection of binding data through owned resources

You can use this method if your backing service owns one or more Kubernetes resources such as route, service, config map, or secret that you can use to detect the binding data. In this method, the Service Binding Operator detects the binding data from resources owned by the backing service CR.

The following examples show the detectBindingResources API option set to true in the ServiceBinding CR:

Example
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
  name: spring-petclinic-rest-detect-all
  namespace: my-postgresql
spec:
  detectBindingResources: true
  services:
    - group: postgres-operator.crunchydata.com
      version: v1beta1
      kind: PostgresCluster
      name: hippo
  application:
    name: spring-petclinic-rest
    group: apps
    version: v1
    resource: deployments

In the previous example, PostgresCluster custom service resource owns one or more Kubernetes resources such as route, service, config map, or secret.

The Service Binding Operator automatically detects the binding data exposed on each of the owned resources.

Categories of exposable binding data

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

Exposing a string from a resource

The following example shows how to expose the string from the metadata.name field of the PostgresCluster custom resource (CR) as a username:

Example
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-postgresql
  annotations:
    service.binding/username: path={.metadata.name}
    ...

Exposing an entire config map or secret that is referenced from a resource

The following examples show how to expose an entire secret as annotations:

Example: Exposing an entire secret as annotations
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-postgresql
  annotations:
    service.binding: 'path={.metadata.name}-pguser-{.metadata.name},objectType=Secret'
Example: The referenced secret from the backing service resource
apiVersion: v1
kind: Secret
metadata:
  name: hippo-pguser-hippo
data:
  password: "MTBz"
  user: "Z3Vlc3Q="

The following example shows how to expose an entire config map as OLM descriptors:

Example: Exposing an entire config map as OLM descriptors
- path: data.dbConfiguration
  x-descriptors:
  - urn:alm:descriptor:io.kubernetes:ConfigMap
  - service.binding

This example uses the path attribute with a urn:alm:descriptor:io.kubernetes:ConfigMap entry to indicate that the path points to the ConfigMap service resource.

If you intend to project all the values from a ConfigMap service resource, you must specify it as an attribute in the backing service CR. For example, if the attribute is part of the .spec section, you can create and use a specDescriptors array. Or, if the attribute is part of the .status section, you can create and use a statusDescriptors array.

Exposing a specific entry from a config map or secret that is referenced from a resource

The following examples show how to expose a specific entry from a config map as annotations:

Example: Exposing an entry from a config map as annotations
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-postgresql
  annotations:
    service.binding: 'path={.metadata.name}-config,objectType=ConfigMap,sourceKey=user'
Example: The referenced config map from the backing service resource

The binding data should have a key with name as db_timeout and value as 10s:

apiVersion: v1
kind: ConfigMap
metadata:
  name: hippo-config
data:
  db_timeout: "10s"
  user: "hippo"

The following example shows how to expose a specific entry from a config map as OLM descriptors:

Example: Exposing an entry from a config map as OLM descriptors
- path: data.dbConfiguration
  x-descriptors:
  - urn:alm:descriptor:io.kubernetes:ConfigMap
  - service.binding:my_certificate:sourceKey=certificate

This example uses the path attribute with an X-Descriptors update for service.binding and sourceKey by providing the following information:

  • Name of the binding key that is to be injected

  • Name of the key in the Secret service resource

Exposing a resource definition value

The following example shows how to expose a resource definition value as annotations:

Example: Exposing a resource definition value as annotations
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-postgresql
  annotations:
    service.binding/username: path={.metadata.name}
    ...

The following example shows how to expose a resource definition value as OLM descriptors:

Example: Exposing a resource definition value as OLM descriptors
- path: data.connectionURL
  x-descriptors:
  - service.binding:uri

The previous example uses the connectionURL attribute that points to the required resource definition value that is to be projected as uri.

If required values are available as attributes of backing service resources, annotating these values using X-Descriptors identifies them as the binding data.

Exposing entries of a collection with the key and value from each entry

Following is the example for exposing the entries of a collection with the key and value from each entry as annotations:

Example: Exposing the entries of a collection as annotations
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-postgresql
  annotations:
    "service.binding/uri": "path={.status.connections},elementType=sliceOfMaps,sourceKey=type,sourceValue=url"
spec:
  ...
status:
  connections:
    - type: primary
      url: primary.example.com
    - type: secondary
      url: secondary.example.com
    - type: '404'
      url: black-hole.example.com

The following example shows how the previous entries of a collection in annotations are projected into the bound application.

Example: Binding data files
/bindings/<binding-name>/uri_primary => primary.example.com
/bindings/<binding-name>/uri_secondary => secondary.example.com
/bindings/<binding-name>/uri_404 => black-hole.example.com

Following is the example for exposing the entries of a collection with the key and value from each entry as OLM descriptors:

Example: Exposing the entries of a collection as OLM descriptors
- path: bootstrap
  x-descriptors:
  - service.binding:endpoints:elementType=sliceOfMaps:sourceKey=type:sourceValue=url

The previous example uses the path attribute with an X-Descriptors update for the required entries of a collection.

Example: Configuration from a backing service resource
status:
  connections:
    - type: primary
      url: primary.example.com
    - type: secondary
      url: secondary.example.com
    - type: '404'
      url: black-hole.example.com

The previous example helps you to project all those values with keys such as primary, secondary, and so on.

Exposing items of a collection with one key per item

Following is the example for exposing the items of a collection with one key per item as annotations:

Example: Exposing the items of a collection as annotations
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-postgresql
  annotations:
    "service.binding/tags": "path={.spec.tags},elementType=sliceOfStrings"
spec:
    tags:
      - knowledge
      - is
      - power

The following example shows how the previous items of a collection in annotations are projected into the bound application.

Example: Binding data files
/bindings/<binding-name>/tags_0 => knowledge
/bindings/<binding-name>/tags_1 => is
/bindings/<binding-name>/tags_2 => power

Following is the example for exposing the items of a collection with one key per item as OLM descriptors:

Example: Exposing the items of a collection as OLM descriptors
- path: spec.tags
  x-descriptors:
  - service.binding:tags:elementType=sliceOfStrings

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
spec:
  tags:
  - knowledge
  - is
  - power

Exposing values of collection entries with one key per entry value

Following is the example for exposing the values of collection entries with one key per entry value as annotations:

Example: Exposing the values of collection entries as annotations
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-postgresql
  annotations:
    "service.binding/url": "path={.spec.connections},elementType=sliceOfStrings,sourceValue=url"
spec:
  connections:
    - type: primary
      url: primary.example.com
    - type: secondary
      url: secondary.example.com
    - type: '404'
      url: black-hole.example.com

The following example shows how the previous values of a collection in annotations are projected into the bound application.

Example: Binding data files
/bindings/<binding-name>/url_0 => primary.example.com
/bindings/<binding-name>/url_1 => secondary.example.com
/bindings/<binding-name>/url_2 => black-hole.example.com

Following is the example for exposing the values of collection entries with one key per entry value as OLM descriptors:

Example: Exposing the values of collection entries as OLM descriptors
- path: bootstrap
  x-descriptors:
  - service.binding:endpoints:elementType=sliceOfStrings:sourceValue=url