Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Restructure readme #155

Merged
merged 2 commits into from
Aug 8, 2022
Merged

Restructure readme #155

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
66f8fa8
Restructure readme
scothis Aug 8, 2022
9353f15
Review feedback
scothis Aug 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 73 additions & 66 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
baijum marked this conversation as resolved.
Show resolved Hide resolved

### 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=<a-repository-you-can-write-to>
```

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

Expand All @@ -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=<a-repository-you-can-write-to>
```
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

Expand Down