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

Move Secret Generation Strategies extension #161

Merged
merged 5 commits into from Aug 5, 2021
Merged

Move Secret Generation Strategies extension #161

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9d73684
Remove Secret Generation Strategies extension
baijum Jun 10, 2021
f6622d9
Remove the Extensions section
baijum Jun 10, 2021
171a2de
Move the extension to another file
baijum Jun 10, 2021
caf33c3
Move extensions into a directory
baijum Jun 11, 2021
edbad80
Fix typo
baijum Jun 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
225 changes: 0 additions & 225 deletions README.md
View file
Open in desktop
Expand Up @@ -71,12 +71,6 @@ Participation in the Kubernetes community is governed by the [Kubernetes Code of
- [Reconciler Implementation](#reconciler-implementation-1)
- [Role-Based Access Control (RBAC)](#role-based-access-control-rbac)
- [Example Resource](#example-resource-3)
- [Extensions](#extensions)
- [Binding `Secret` Generation Strategies](#binding-secret-generation-strategies)
- [OLM Operator Descriptors](#olm-operator-descriptors)
- [Descriptor Examples](#descriptor-examples)
- [Non-OLM Operator and Resource Annotations](#non-olm-operator-and-resource-annotations)
- [Annotation Examples](#annotation-examples)
---

## Status
Expand Down Expand Up @@ -580,222 +574,3 @@ aggregationRule:
service.binding/controller: "true"
rules: [] # The control plane automatically fills in the rules
```

# Extensions

Extensions are optional additions to the core specification as defined above. Implementation and support of these specifications are not required in order for a platform to be considered compliant. However, if the features addressed by these specifications are supported a platform **MUST** be in compliance with the specification that governs that feature.

## Binding `Secret` Generation Strategies

Many services, especially initially, will not be Provisioned Service-compliant. These services will expose the appropriate binding `Secret` information, but not in the way that the specification or applications expect. Users should have a way of describing a mapping from existing data associated with arbitrary resources and CRDs to a representation of a binding `Secret`.

To handle the majority of existing resources and CRDs, `Secret` generation needs to support the following behaviors:

1. Extract a string from a resource
1. Extract an entire `ConfigMap`/`Secret` refrenced from a resource
1. Extract a specific entry in a `ConfigMap`/`Secret` referenced from a resource
1. Extract entries from a collection of objects, mapping keys and values from entries in a `ConfigMap`/`Secret` referenced from a resource
1. Exctact a collection of specific entry values in a resource's collection of objects
1. Map each value to a specific key
1. Map each value of a collection to a key with generated name

While the syntax of the generation strategies are specific to the system they are annotating, they are based on a common data model.

| Model | Description
| ----- | -----------
| `path` | A template represention of the path to an element in a Kubernetes resource. The value of `path` is specified as [JSONPath](https://kubernetes.io/docs/reference/kubectl/jsonpath/). Required.
| `objectType` | Specifies the type of the object selected by the `path`. One of `ConfigMap`, `Secret`, or `string` (default).
| `elementType` | Specifies the type of object in an array selected by the `path`. One of `sliceOfMaps`, `sliceOfStrings`, `string` (default).
| `sourceKey` | Specifies a particular key to select if a `ConfigMap` or `Secret` is selected by the `path`. Specifies a value to use for the key for an entry in a binding `Secret` when `elementType` is `sliceOfMaps`.
| `sourceValue` | Specifies a particular value to use for the value for an entry in a binding `Secret` when `elementType` is `sliceOfMaps` or `sliceOfStrings`.


### OLM Operator Descriptors

OLM Operators are configured by setting the `specDescriptor` and `statusDescriptor` entries in the [ClusterServiceVersion](https://docs.openshift.com/container-platform/4.4/operators/operator_sdk/osdk-generating-csvs.html) with mapping descriptors.

### Descriptor Examples

The following examples refer to this resource definition.

```yaml
apiVersion: apps.kube.io/v1beta1
kind: Database
metadata:
name: my-cluster
spec:
tags:
- Brno
- PWR
- stage
...

status:
bootstrap:
- type: plain
url: myhost2.example.com
name: hostGroup1
- type: tls
url: myhost1.example.com:9092,myhost2.example.com:9092
name: hostGroup2
data:
dbConfiguration: database-config # ConfigMap
dbCredentials: database-cred-Secret # Secret
url: db.stage.ibm.com
```

1. Mount an entire `Secret` as the binding `Secret`

```yaml
- path: data.dbCredentials
x-descriptors:
- urn:alm:descriptor:io.kubernetes:Secret
- service.binding
```

1. Mount an entire `ConfigMap` as the binding `Secret`

```yaml
- path: data.dbConfiguration
x-descriptors:
- urn:alm:descriptor:io.kubernetes:ConfigMap
- service.binding
```

1. Mount an entry from a `ConfigMap` into the binding `Secret`

```yaml
- path: data.dbConfiguration
x-descriptors:
- urn:alm:descriptor:io.kubernetes:ConfigMap
- service.binding:certificate:sourceKey=certificate
```

1. Mount an entry from a `ConfigMap` into the binding `Secret` with a different key

```yaml
- path: data.dbConfiguration
x-descriptors:
- urn:alm:descriptor:io.kubernetes:ConfigMap
- service.binding:timeout:sourceKey=db_timeout
```

1. Mount a resource definition value into the binding `Secret`

```yaml
- path: data.uri
x-descriptors:
- service.binding:uri
```

1. Mount a resource definition value into the binding `Secret` with a different key

```yaml
- path: data.connectionURL
x-descriptors:
- service.binding:uri
```

1. Mount the entries of a collection into the binding `Secret` selecting the key and value from each entry

```yaml
- path: bootstrap
x-descriptors:
- service.binding:endpoints:elementType=sliceOfMaps:sourceKey=type:sourceValue=url
```

1. Mount the items of a collection into the binding `Secret` with one key per item

```yaml
- path: spec.tags
x-descriptors:
- service.binding:tags:elementType=sliceOfStrings
```

1. Mount the values of collection entries into the binding `Secret` with one key per entry value

```yaml
- path: bootstrap
x-descriptors:
- service.binding:endpoints:elementType=sliceOfStrings:sourceValue=url
```

### Non-OLM Operator and Resource Annotations

Non-OLM Operators are configured by adding annotations to the Operator's CRD with mapping configuration. All Kubernetes resources are configured by adding annotations to the resource.

### Annotation Examples

The following examples refer to this resource definition.

```yaml
apiVersion: apps.kube.io/v1beta1
kind: Database
metadata:
name: my-cluster
spec:
tags:
- Brno
- PWR
- stage
...

status:
bootstrap:
- type: plain
url: myhost2.example.com
name: hostGroup1
- type: tls
url: myhost1.example.com:9092,myhost2.example.com:9092
name: hostGroup2
data:
dbConfiguration: database-config # ConfigMap
dbCredentials: database-cred-Secret # Secret
url: db.stage.ibm.com
```

1. Mount an entire `Secret` as the binding `Secret`
```plain
“service.binding":
”path={.status.data.dbCredentials},objectType=Secret”
```
1. Mount an entire `ConfigMap` as the binding `Secret`
```plain
service.binding”:
"path={.status.data.dbConfiguration},objectType=ConfigMap”
```
1. Mount an entry from a `ConfigMap` into the binding `Secret`
```plain
“service.binding/certificate”:
"path={.status.data.dbConfiguration},objectType=ConfigMap,sourceKey=certificate"
```
1. Mount an entry from a `ConfigMap` into the binding `Secret` with a different key
```plain
“service.binding/timeout”:
“path={.status.data.dbConfiguration},objectType=ConfigMap,sourceKey=db_timeout”
```
1. Mount a resource definition value into the binding `Secret`
```plain
“service.binding/uri”:
"path={.status.data.url}"
```
1. Mount a resource definition value into the binding `Secret` with a different key
```plain
“service.binding/uri":
"path={.status.data.connectionURL}”
```
1. Mount the entries of a collection into the binding `Secret` selecting the key and value from each entry
```plain
“service.binding/endpoints”:
"path={.status.bootstrap},elementType=sliceOfMaps,sourceKey=type,sourceValue=url"
```
1. Mount the items of a collection into the binding `Secret` with one key per item
```plain
"service.binding/tags":
"path={.spec.tags},elementType=sliceOfStrings
```
1. Mount the values of collection entries into the binding `Secret` with one key per entry value
```plain
“service.binding/endpoints”:
"path={.status.bootstrap},elementType=sliceOfStrings,sourceValue=url"
```
7 changes: 7 additions & 0 deletions extensions/README.md
View file
Open in desktop
@@ -0,0 +1,7 @@
# Extensions

This directory contains extensions to the [Service Binding Specification for Kubernetes](https://github.com/k8s-service-bindings/spec). Extensions are optional additions to the core specification. Implementation and support of these specifications are not required in order for a platform to be considered compliant. However, if the features addressed by these specifications are supported, a platform must be in compliance with the specification that governs that feature. Both the core spec and the extensions are going to have their independent release cycles.

| No. | Title | Status |
| --- | ---------------------------------------------------- | ------ |
| 1 | [Secret Generation Extension](./secret-generation.md) | Draft |