servicebinding-runtime

Service Binding Runtime

Experimental implementation of the ServiceBinding.io 1.0 spec using reconciler-runtime. The full specification is implemented, please open an issue for any discrepancies.

• Architecture
  • Controller
  • Webhooks
• Supported Services
• Supported Workloads
• Getting Started
  • Running on the cluster
  • Undeploy controller
• Contributing
  • Test It Out
  • Modifying the API definitions
• Acknowledgements
• License

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 references 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 ValidationWebhookConfiguration 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 ValidationWebhookConfiguration 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.

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.

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. Note: Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster kubectl cluster-info shows).

Running on the cluster

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

2. Build and Deploy the controller to the cluster:

   make deploy
   

Undeploy controller

Undeploy the controller to the cluster:

make undeploy

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

Acknowledgements

The scope of this work is defined by the Service Binding for Kubernetes project. Without our friends from IBM and RedHat, this domain this controller operates within would not exist.

Large chunks of this code base are from the upstream reference implementation for the service binding specification, include the apis, projector and resolver packages. These sources retain the upstream copyright headers

License

Copyright 2022 Scott Andrews.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.