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

KEP-2906: Update Catalog schema for CRD compatibility #3220

Merged
merged 1 commit into from
Feb 23, 2022
Merged

KEP-2906: Update Catalog schema for CRD compatibility #3220

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
136 changes: 92 additions & 44 deletions keps/sig-cli/2906-kustomize-function-catalog/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ A successful implementation of this API should have the following characteristic

### Non-Goals

1. Support anything other than KRM-style fyunctions that follow the [functions spec](https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md)
1. Support anything other than KRM-style functions that follow the [functions spec](https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md)
1. Directly implement capabilities to publish function or other resources to OCI registries

## Proposal
Expand All @@ -255,15 +255,18 @@ A `Catalog` will contain a collection of one or more functions that can be used
A minimal example is shown below:

```yaml
apiVersion: kustomize.io/v1
apiVersion: config.kubernetes.io/v1alpha1
kind: Catalog
metadata:
name: "example-co-functionss"
name: "example-co-functions"
spec:
krmFunctions:
- apiVersion: example.com/v1
kind: JavaApplication
- group: example.com
names:
kind: JavaApplication
description: "A Kustomize function that represents a Java based app"
versions:
- name: v1
runtime:
container:
image: example/module_providers/java:v1.0.0
Expand Down Expand Up @@ -300,15 +303,18 @@ Kustomize can at a later date provide a built in Catalog for supporting official
In addition to container based functions, the `Catalog` will support discovery of Starlark and Exec based functions, via an HTTP(s), Git, or OCI reference as illustrated below:

```yaml
apiVersion: kustomize.io/v1
apiVersion: config.kubernetes.io/v1alpha1
kind: Catalog
metadata:
name: "example-co-functions"
spec:
krmFunctions:
- apiVersion: example.com/v1
kind: GroovyApplication
- group: example.com
names:
kind: GroovyApplication
description: "A Kustomize function that can handle groovy apps"
versions:
- name: v1
runtime:
starlark: https://example.co/module_providers/starlark-func:v1.0.0
```
Expand All @@ -328,27 +334,36 @@ To do this, I build a new `Catalog` API resource:

```yaml
# catalog.yaml
apiVersion: kustomize.io/v1
apiVersion: config.kubernetes.io/v1alpha1
kind: Catalog
metadata:
name: "example-co-functions"
spec:
krmFunctions:
- apiVersion: example.com/v1
kind: JavaApplication
- group: example.com
names:
kind: JavaApplication
description: "A Kustomize function that can handle Java apps"
versions:
- name: v1
runtime:
container:
image: docker.example.co/functions/java:v1.0.0
- apiVersion: example.com/v1
kind: Logger
- group: example.com
names:
kind: Logger
description: "A Kustomize function that adds our bespoke logging"
versions:
- name: v1
runtime:
container:
image: docker.example.co/functions/logger:v1.0.0
- apiVersion: example.com/v1
kind: SecretSidecar
- group: example.com
names:
kind: SecretSidecar
description: "A Kustomize function that adds our bespoke secret sidecar"
versions:
- name: v1
runtime:
container:
image: docker.example.co/functions/secrets:v1.0.0
Expand Down Expand Up @@ -460,15 +475,18 @@ modules:
As a Kustomize developer, I want to build an `official` Helm extension module and publish it via the Kustomize official extension catalog. I build and publish the extension to the official Kustomize `gcr.io` project (or alternative, such as Github Package Registry). I then update the official Kustomize extension catalog:

```yaml
apiVersion: kustomize.io/v1
apiVersion: config.kubernetes.io/v1alpha1
kind: Catalog
metadata:
name: "official-kustomize-functions"
spec:
krmFunctions:
- apiVersion: kustomize.io/v1
kind: Helm
- group: kustomize.io
names:
kind: Helm
description: "A Kustomize function that can handle Helm charts"
versions:
- name: v1
runtime:
container:
image: k8s.gcr.io/kustomize/helm-function:v1.0.0
Expand All @@ -491,21 +509,27 @@ I publish the implementation of my function as a container to a public Docker re
Once this has been approved and included into the officially published catalog, my function is available for others to discover:

```yaml
apiVersion: kustomize.io/v1
apiVersion: config.kubernetes.io/v1alpha1
kind: Catalog
metadata:
name: "official-kustomize-functions"
spec:
krmFunctions:
- apiVersion: kustomize.io/v1
kind: Helm
- group: kustomize.io
names:
kind: Helm
description: "A Kustomize function that can handle Helm charts"
versions:
- name: v1
runtime:
container:
image: k8s.gcr.io/kustomize/helm-function:v1.0.0
- apiVersion: example.co/v1
kind: McGuffin
- group: example.co
names:
kind: McGuffin
description: "A KRM function that everyone is searching for"
versions:
- name: v1
runtime:
container:
image: docker.example.io/krm/mcguffin-function:v1.0.0
Expand All @@ -522,27 +546,36 @@ As a platform developer at enterprise company Example Co, I wish to publish a tr
Using the runtime information and the metadata for each function, I publish a trusted catalog for use at Example Co

```yaml
apiVersion: kustomize.io/v1
apiVersion: config.kubernetes.io/v1alpha1
kind: Catalog
metadata:
name: "example-co-aggregated-catalog"
spec:
krmFunctions:
- apiVersion: banana.co/v1
kind: Split
- group: banana.co
names:
kind: Split
description: "A KRM function that splits a deployment into multiple deployments"
versions:
- name: v1
runtime:
container:
image: banana.gcr.io/functions/split-function:v1.0.0
- apiVersion: watermelon.co/v1
kind: Salt
- group: watermelon.co
names:
kind: Salt
description: "A KRM function that applies salt"
versions:
- name: v1
runtime:
container:
image: watermelon.gcr.io/krm-functions/salt-function:v1.0.0
- apiVersion: example.com/v1
kind: JavaApplication
- group: example.com
names:
kind: JavaApplication
description: "A Kustomize function that can handle Java apps"
versions:
- name: v1
runtime:
container:
image: example/module_providers/java:v1.0.0
Expand Down Expand Up @@ -587,22 +620,34 @@ info:
title: KRM Function Metadata
version: v1alpha1
definitions:
FunctionSpec:
KRMFunctionDefinitionSpec:
type: object
description: spec contains the metadata for a KRM function.
required:
- group
- kind
- names
- description
- publisher
- versions
properties:
group:
description: group of the functionConfig
type: string
kind:
description: kind of the functionConfig
description:
description: brief description of the KRM function.
type: string
publisher:
description: the entity (e.g. organization) that produced and owns this KRM function.
type: string
names:
description: the resource and kind names for the KRM function
type: object
required:
- kind
properties:
kind:
description: the Kind of the functionConfig
type: string
versions:
description: the versions of the functionConfig
type: array
Expand Down Expand Up @@ -743,30 +788,32 @@ definitions:
type: array
items:
type: string
KRMFunction:
KRMFunctionDefinition:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to make the same changes to https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/2985-public-krm-functions-registry, right? It leverages the KRMFunction definition from here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will need to update it if we change the name here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call--the names.kind change needs to be made there as well.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we want to change the name here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As part of strengthening the analogy to CRD, I though it would be useful to include "Definition" in the name of this type. In the same way that the CRD kind defines a CR rather than being one itself, this type defines a function. Does that make sense?

type: object
description: KRMFunction is metadata of a KRM function.
description: |
KRMFunctionDefinition is metadata that defines a KRM function
the same way a CustomResourceDefinition defines a custom resource.
x-kubernetes-group-version-kind:
- group: config.kubernetes.io
kind: KRMFunction
kind: KRMFunctionDefinition
version: v1alpha1
required:
- apiVersion
- kind
- spec
properties:
apiVersion:
description: apiVersion of KRMFunction. i.e. config.kubernetes.io/v1alpha1
description: apiVersion of KRMFunctionDefinition. i.e. config.kubernetes.io/v1alpha1
type: string
enum:
- config.kubernetes.io/v1alpha1
kind:
description: kind of the KRMFunction. It must be KRMFunction.
description: kind of the KRMFunctionDefinition. It must be KRMFunctionDefinition.
type: string
enum:
- KRMFunction
- KRMFunctionDefinition
spec:
$ref: "#/definitions/FunctionSpec"
$ref: "#/definitions/KRMFunctionDefinitionSpec"
KRMFunctionCatalog:
type: object
description: KRMFunctionCatalog is the metadata of a collection of KRM functions.
Expand Down Expand Up @@ -799,7 +846,7 @@ definitions:
krmFunctions:
type: array
items:
$ref: "#/definitions/FunctionSpec"
$ref: "#/definitions/KRMFunctionDefinitionSpec"
paths: {}
```
</details>
Expand All @@ -811,7 +858,7 @@ When using OCI references, either a tag or digest reference can be provided. Exe
An example representation is shown below:

```yaml
apiVersion: kustomize.io/v1
apiVersion: config.kubernetes.io/v1alpha1
kind: Catalog
metadata:
name: "example-co-functions"
Expand All @@ -820,7 +867,8 @@ metadata:
spec:
krmFunctions:
- group: example.com
kind: SetNamespace
names:
kind: SetNamespace
description: "A short description of the KRM function"
publisher: example.com
versions:
Expand Down
8 changes: 4 additions & 4 deletions keps/sig-cli/2906-kustomize-function-catalog/kep.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,10 @@ stage: alpha
# The most recent milestone for which work toward delivery of this KEP has been
# done. This can be the current (upcoming) milestone, if it is being actively
# worked on.
latest-milestone: "v1.23"
latest-milestone: "v1.24"

# The milestone at which this feature was, or is targeted to be, at each stage.
milestone:
alpha: "v1.23"
beta: "v1.24"
stable: "v1.26"
alpha: "v1.24"
beta: "v1.25"
stable: "v1.27"
18 changes: 10 additions & 8 deletions keps/sig-cli/2985-public-krm-functions-registry/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -559,17 +559,18 @@ using [mdBook](https://github.com/rust-lang/mdBook).

### Function Metadata

We will use `KRMFunction` kind whose schema is defined in [KEP-2906](https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/2906-kustomize-function-catalog#function-metadata-schema) to capture the metadata for a single KRM function.
We will use `KRMFunctionDefinition` kind whose schema is defined in [KEP-2906](https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/2906-kustomize-function-catalog#function-metadata-schema) to capture the metadata for a single KRM function.

The following is an example function metadata for a container-based KRM
function. We will support it starting from the alpha phase.

```yaml
apiVersion: config.k8s.io/v1alpha1
kind: KRMFunction
apiVersion: config.kubernetes.io/v1alpha1
kind: KRMFunctionDefinition
spec:
group: example.com
kind: SetNamespace
names:
kind: SetNamespace
description: "A short description of the KRM function"
publisher: example.com
versions:
Expand Down Expand Up @@ -602,11 +603,12 @@ The following is an example for exec-based KRM function. We will support it
starting from the beta phase.

```yaml
apiVersion: config.k8s.io/v1alpha1
kind: KRMFunction
apiVersion: config.kubernetes.io/v1alpha1
kind: KRMFunctionDefinition
spec:
group: example.com
kind: SetNamespace
names:
kind: SetNamespace
description: "A short description of the KRM function"
publisher: example.com
versions:
Expand Down Expand Up @@ -1172,4 +1174,4 @@ new subproject, repos requested, or GitHub details. Listing these here allows a
SIG to get the process for these resources started right away.
-->

[KRM functions spec]: https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md
[KRM functions spec]: https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md