diff --git a/README.md b/README.md index 3d94d8d7..2fec9da7 100644 --- a/README.md +++ b/README.md @@ -10,62 +10,69 @@ Reference implementation of the [ServiceBinding.io](https://servicebinding.io) [1.0 spec](https://servicebinding.io/spec/core/1.0.0/). The full specification is implemented, please open an issue for any discrepancies. +- [Getting Started](#getting-started) + - [Deploy a released build](#deploy-a-released-build) + - [Build from source](#build-from-source) + - [Undeploy controller](#undeploy-controller) +- [Samples](#samples) +- [Supported Services](#supported-services) +- [Supported Workloads](#supported-workloads) - [Architecture](#architecture) - [Controller](#controller) - [Webhooks](#webhooks) -- [Supported Services](#supported-services) -- [Supported Workloads](#supported-workloads) -- [Getting Started](#getting-started) - - [Running on the cluster](#running-on-the-cluster) - - [Undeploy controller](#undeploy-controller) -- [Samples](#samples) - [Contributing](#contributing) - [Test It Out](#test-it-out) - [Modifying the API definitions](#modifying-the-api-definitions) - [Community, discussion, contribution, and support](#community-discussion-contribution-and-support) - [Code of conduct](#code-of-conduct) -## Architecture +## Getting Started -The [Service Binding for Kubernetes Specification](https://servicebinding.io/spec/core/1.0.0/) defines the shape of [Provisioned Services](https://servicebinding.io/spec/core/1.0.0/#provisioned-service), and how the `Secret` is [projected into a workload](https://servicebinding.io/spec/core/1.0.0/#workload-projection). The spec says less (intentionally) about how this happens. +You’ll need a Kubernetes cluster to run against. You can use [kind](https://kind.sigs.k8s.io) to get a local cluster for testing, or run against a remote cluster. -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 `ServiceBinding`s 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 `ServiceBinding`s the controller should process. +After the controller is deployed, try out the [samples](#samples). -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. +### Deploy a released build -There are a limited number of resources that maintain an informer cache within the manager: -- `ServiceBinding` -- `ClusterWorkloadResourceMapping` -- `MutatingWebhookConfiguration` -- `ValidatingWebhookConfiguration` +The easiest way to get started is by deploying the [latest release](https://github.com/servicebinding/runtime/releases). Alternatively, you can [build the runtime from source](#build-from-source). -### Controller +### Build from source -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` +1. Define where to publish images: -### Webhooks + ```sh + export KO_DOCKER_REPO= + ``` -In addition to that main flow, a `MutatingWebhookConfiguration` and `ValidationWebhookConfiguration` are updated: -- all `ServiceBinding`s 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 + For kind, a registry is not required: -The `MutatingWebhookConfiguration` is used to intercept create and update requests for workloads: -- all `ServiceBinding`s 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 + ```sh + export KO_DOCKER_REPO=kind.local + ``` + +1. Build and deploy the controller to the cluster: -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 `ServiceBinding`s that reference that resource as a workload or service are resolved and enqueued for the controller to process. + Note: The cluster must have the [cert-manager](https://cert-manager.io) deployed. There is a `make deploy-cert-manager` target to deploy the cert-manager. -No blocking work is performed within the webhooks. + ```sh + make deploy + ``` + +#### Undeploy controller +Undeploy the controller to the cluster: + +```sh +make undeploy +``` + +## Samples + +Samples are located in the [samples directory](./samples), including: + +- [Spring PetClinic with MySQL](./samples/spring-petclinic) +- [Controlled Resource](./samples/controlled-resource) +- [Overridden Type and Provider](./samples/overridden-type-provider) +- [Multiple Bindings](./samples/multi-binding) ## Supported Services @@ -86,47 +93,47 @@ Support for the built-in k8s workload resource is pre-configured including: Additional workloads can be supported dynamically by [defining a `ClusterRole`](https://servicebinding.io/spec/core/1.0.0/#considerations-for-role-based-access-control-rbac-1) and if not PodSpecable, a [`ClusterWorkloadResourceMapping`](https://servicebinding.io/spec/core/1.0.0/#workload-resource-mapping). +## Architecture -## Getting Started -You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/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: +The [Service Binding for Kubernetes Specification](https://servicebinding.io/spec/core/1.0.0/) defines the shape of [Provisioned Services](https://servicebinding.io/spec/core/1.0.0/#provisioned-service), and how the `Secret` is [projected into a workload](https://servicebinding.io/spec/core/1.0.0/#workload-projection). The spec says less (intentionally) about how this happens. - ```sh - export KO_DOCKER_REPO= - ``` +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 `ServiceBinding`s 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 `ServiceBinding`s the controller should process. - For kind, a registry is not required: +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. - ```sh - export KO_DOCKER_REPO=kind.local - ``` - -1. Build and Deploy the controller to the cluster: +There are a limited number of resources that maintain an informer cache within the manager: +- `ServiceBinding` +- `ClusterWorkloadResourceMapping` +- `MutatingWebhookConfiguration` +- `ValidatingWebhookConfiguration` - Note: The cluster must have the [cert-manager](https://cert-manager.io) deployed. There is a `make deploy-cert-manager` target to deploy the cert-manager. +### Controller - ```sh - make deploy - ``` +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` -### Undeploy controller -Undeploy the controller to the cluster: +### Webhooks -```sh -make undeploy -``` +In addition to that main flow, a `MutatingWebhookConfiguration` and `ValidationWebhookConfiguration` are updated: +- all `ServiceBinding`s 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 -## Samples +The `MutatingWebhookConfiguration` is used to intercept create and update requests for workloads: +- all `ServiceBinding`s 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 -Samples are located in the [samples directory](./samples), including: +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 `ServiceBinding`s that reference that resource as a workload or service are resolved and enqueued for the controller to process. -- [Spring PetClinic with MySQL](./samples/spring-petclinic) -- [Controlled Resource](./samples/controlled-resource) -- [Overridden Type and Provider](./samples/overridden-type-provider) -- [Multiple Bindings](./samples/multi-binding) +No blocking work is performed within the webhooks. ## Contributing