Declaring binding data through CRD or CR annotations

If your backing service is not compliant with the Service Binding specification as a Provisioned Service resource, you can annotate the resources of the backing service to expose the binding data with specific annotations. Adding annotations under the metadata section alters the CR and CRD of the backing services.

The Service Binding Operator implements support for Secret Generation Extension. The 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 and Secret object from a resource:

Example: Exposing binding data from a Secret object defined in the CR annotations
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: db
  namespace: my-petclinic
  annotations:
    service.binding: 'path={.metadata.name}-cred,objectType=Secret'
    ...

The previous example places the name of the secret name in the {.metadata.name}-cred template that resolves to db-cred. The template can contain multiple JSONPath expressions.

Example: Referenced Secret object from a resource
apiVersion: v1
kind: Secret
metadata:
  name: db-cred
data:
  password: "foo"
  user: "guest"
Example: Exposing binding data from a ConfigMap object defined in the CR annotations
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: db
  namespace: my-petclinic
  annotations:
    service.binding: 'path={.metadata.name}-config,objectType=ConfigMap'
    ...

The previous example places the name of the config map in the {.metadata.name}-config template that resolves to db-config. The template can contain multiple JSONPath expressions.

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

Exposing a string from a resource

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

Example
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: my-db
  namespace: my-petclinic
  annotations:
    service.binding/username: path={.metadata.name}
    ...

Exposing a constant value as the binding item

The following example shows how to expose a constant value from the Database custom resource (CR):

Example: Exposing a constant value
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: my-db
  namespace: my-petclinic
  annotations:
    "service.binding/type": "foo" (1)
1 Binding type to be exposed with the foo value.

Exposing all secret entries as binding data

The following example shows how to expose all secret entries constant valueas binding data from the Database CR:

Example: Exposing all secret entries as binding data
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: my-db
  annotations:
    "service.binding": "path={.status.data.dbCredentials},objectType=Secret"
spec:
  ...

status:
  data:
    dbCredentials: db-cred (1)
1 Secret name

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

The following example shows how to expose a specific entry from a config map through annotations:

Example: Exposing db_timeout entry from a config map through annotations
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: my-db
  namespace: my-petclinic
  annotations:
    service.binding: 'path={.metadata.name}-config,objectType=ConfigMap,sourceKey=db_timeout'
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: db-config
data:
  db_timeout: "10s"
  user: "db1"
Example: Exposing username entry from a secret as user binding item
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: my-db
  annotations:
    "service.binding/user": "path={.status.data.dbCredentials},objectType=Secret,sourceKey=username"
spec:
  ...

status:
  data:
    dbCredentials: db-cred (1)
1 Secret name

Exposing a resource definition value

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

Example: Exposing status.data.connectionURL resource value as uri binding item
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: my-db
  annotations:
    "service.binding/uri":  "path={.status.data.connectionURL}"
spec:
  ...

status:
  data:
    connectionURL: "http://guest:secret123@192.168.1.29/db"

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

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

The following example shows how to expose the entries of a collection with the key and value from each entry through annotations:

Example: Exposing the entries of a collection through annotations
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: my-db
  namespace: my-petclinic
  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

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

The following example shows how to expose the items of a collection with one key per item through annotations:

Example: Exposing the items of a collection through annotations
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: my-db
  namespace: my-petclinic
  annotations:
    "service.binding/tags": "path={.spec.tags},elementType=sliceOfStrings"
spec:
    tags:
      - knowledge
      - is
      - power

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>/tags_0 => knowledge
/bindings/<binding-name>/tags_1 => is
/bindings/<binding-name>/tags_2 => power

The previous example helps you project all those values with key such as prefix_0, prefix_1, and so on. The default prefix is the name of the resource kind:.

Exposing values of collection entries with one key per entry value

The following example shows how to expose the values of collection entries with one key per entry value through annotations:

Example: Exposing the values of collection entries through annotations
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: my-db
  namespace: my-petclinic
  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

The previous example helps you project all those values with key such as prefix_0, prefix_1, and so on. The default prefix is the name of the resource kind:.

Setting annotations mapping to be optional

You can have optional fields in the annotations. For example, a link to the credentials might not be there if the service endpoint does not require authentication. In such cases, a field might not exist in the target path of the annotations. As a result, the Service Binding Operator generates an error, by default. As a service provider, to indicate whether you require annotations mapping, you can set a value to the optional flag in your annotations while enabling services.

Service Binding Operator provides annotations mapping only if the target path is available. When the target path is not available the Service Binding Operator skips providing the annotations mapping.

Procedure

  1. To enable Service Binding Operator consider a new field in the annotations, provide the mapping by setting the optional flag value to true:

Example
apiVersion: apps.example.org/v1beta1
kind: Database
metadata:
  name: my-db
  namespace: my-petclinic
  annotations:
    service.binding/username: path={.spec.name},optional=true
    ...

  • If you set the optional flag value to false and when the Service Binding Operator is unable to find the target path, the Operator fails the annotations mapping.

  • If there is no value set for the optional flag, the Service Binding Operator considers the value as false, by default and fails the annotations mapping.