runtime

README

Service Binding Runtime

Reference implementation of the ServiceBinding.io 1.1 spec, along with 1.0. The full specification is implemented, please open an issue for any discrepancies.

• Getting Started
  • Deploy a released build
  • Build from source
    • Undeploy controller
• Samples
• Supported Services
• Supported Workloads
• Architecture
  • Controller
  • Webhooks
• Contributing
  • Test It Out
  • Modifying the API definitions
• Community, discussion, contribution, and support
  • Code of conduct

Getting Started

You’ll need a Kubernetes cluster to run against. You can use kind to get a local cluster for testing, or run against a remote cluster.

After the controller is deployed, try out the samples.

Deploy a released build

The easiest way to get started is by deploying the latest release. Alternatively, you can build the runtime from source.

Build from source

1. Define where to publish images:

   export KO_DOCKER_REPO=<a-repository-you-can-write-to>
   

   For kind, a registry is not required:

   export KO_DOCKER_REPO=kind.local
   

2. Build and deploy the controller to the cluster:

   Note: The cluster must have the cert-manager deployed. There is a make deploy-cert-manager target to deploy the cert-manager.

   make deploy
   

Undeploy controller

Undeploy the controller to the cluster:

make undeploy

Samples

Samples are located in the samples directory, including:

• Spring PetClinic with MySQL
• Controlled Resource
• Overridden Type and Provider
• Multiple Bindings
• External Secrets Operator

Supported Services

Kubernetes defines no provisioned services by default, however, Secrets may be directly referenced.

Additional services can be supported dynamically by defining a ClusterRole.

Supported Workloads

Support for the built-in k8s workload resource is pre-configured including:

• apps DaemonSet
• apps Deployment
• apps ReplicaSet
• apps StatefulSet
• batch CronJob (also includes a ClusterResourceMapping)
• batch Job (since Jobs are immutable, the ServiceBinding must be defined and service resolved before the job is created)
• core ReplicationController

Additional workloads can be supported dynamically by defining a ClusterRole and if not PodSpecable, a ClusterWorkloadResourceMapping.

Architecture

The Service Binding for Kubernetes Specification defines the shape of Provisioned Services, and how the Secret is projected into a workload. The spec says less (intentionally) about how this happens.

Both a controller and mutating admission webhook are used to project a Secret defined by the service referenced by the ServiceBinding resource into the workloads referenced. The controller is used to process ServiceBindings by resolving services, projecting workloads and updating the status. The webhook is used to prevent removal of the workload projection, projecting workload on create, and a notification trigger for ServiceBindings the controller should process.

The apis, resolver and projector packages are defined by the reference implementation and reused here with slight modifications. The bulk of the work to bind a service to a workload is encapsulated with these packages. The output from the projector is deterministic and idempotent. The order that service bindings are applied to, or removed from, a workload does not matter. If a workload is bound and then unbound, the only trace will be the SERVICE_BINDING_ROOT environment variable.

There are a limited number of resources that maintain an informer cache within the manager:

• ServiceBinding
• ClusterWorkloadResourceMapping
• MutatingWebhookConfiguration
• ValidatingWebhookConfiguration

Controller

When a ServiceBinding is created, updated or deleted the controller processes the resource. It will:

• resolve the referenced service resource, looking at it's .spec.binding.name for the name of the Secret to bind
• reflect the discovered Secret name onto the ServiceBinding's .status.binding.name
• the ServiceAvailable condition is updated on the ServiceBinding
• the referenced workloads are resolved (either by name or selector)
• a ClusterWorkloadResourceMapping is resolved for the apiVersion/kind of the workload (or a default value for a PodSpecable workload is used)
• the resolved Secret name is projected into the workload
• the Ready condition is updated on the ServiceBinding

Webhooks

In addition to that main flow, a MutatingWebhookConfiguration and ValidatingWebhookConfiguration are updated:

• all ServiceBindings in the cluster are resolved
• the rules for a MutatingWebhookConfiguration are updated based on the set of all workload group-kinds referenced
• the rules for a ValidatingWebhookConfiguration are updated based on the set of all workload and service group-kinds referenced

The MutatingWebhookConfiguration is used to intercept create and update requests for workloads:

• all ServiceBindings targeting the workload are resolved
• a ClusterWorkloadResourceMapping is resolved for the apiVersion/kind of the workload (or a default value for a PodSpecable workload is used)
• for each ServiceBinding the resolved Secret name is projected into the workload
• the delta between the original resource and the projected resource is returned with the webhook response as a patch

The ValidatingWebhookConfiguration is used as an alternative to watching the API Server directly for these types and keeping an informer cache. When a webhook request is received, the ServiceBindings that reference that resource as a workload or service are resolved and enqueued for the controller to process.

No blocking work is performed within the webhooks.

Contributing

Test It Out

Run the unit tests:

make test

Modifying the API definitions

If you are editing the API definitions, generate the manifests such as CRs or CRDs using:

make manifests

NOTE: Run make help for more information on all potential make targets

More information can be found via the Kubebuilder Documentation

Community, discussion, contribution, and support

The Service Binding Controller project is a community lead effort. A bi-weekly working group call is open to the public. Discussions occur here on GitHub and on the #bindings-discuss channel in the Kubernetes Slack.

If you catch an error in the implementation, please let us know by opening an issue at our GitHub repository.

Code of conduct

Participation in the Service Binding community is governed by the Contributor Covenant.