Skip to content

Commit

Permalink
Restructure readme (servicebinding#155)
Browse files Browse the repository at this point in the history 
- add section on deploying a release
- move Getting Started and Samples sections to the top
- other minor polishing

Signed-off-by: Scott Andrews <andrewssc@vmware.com>
  • Loading branch information
@scothis @sadlerap
scothis authored and sadlerap committed Aug 24, 2022
1 parent 251488f commit 29237b5
Showing 1 changed file with 73 additions and 66 deletions.
139 changes: 73 additions & 66 deletions README.md
View file
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).

### 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

0 comments on commit 29237b5

Please sign in to comment.