diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9af13e1..ec591f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,11 +6,49 @@ _As contributors and maintainers of this project, and in the interest of fosteri ## Getting Started -We have full documentation on how to get started contributing here: +### Repo layout + +``` +├── publishers # Home for all functions metadata +│ ├── kustomize +│ │ ├── functions +│ │ │ ├── fn-foo.yaml +│ │ │ ├── fn-bar.yaml +│ │ │ └── README.md +│ │ ├── catalogs +│ │ │ ├── v20220225.yaml +│ │ │ ├── v20220101.yaml +│ │ │ └── README.md +│ │ └── OWNERS # OWNERS of the publisher +│ ├── kubeflow +│ ├── sig-cli +│ └── OWNERS # OWNERS to approve new publishers +├── krm-functions # Home for in-tree functions source code +│ ├── Makefile +│ ├── kustomize +│ │ ├── fn-foo +│ │ ├── README.md +│ │ └── OWNERS # OWNERS to approve code change to the function +│ └── sig-cli +├── site +├── Makefile +└── OWNERS +``` + +## Contributing in-tree KRM function source code + +To contribute KRM function source code, so that it can be managed and released by this repo, follow the instructions +in the [krm-functions directory]((https://github.com/kubernetes-sigs/krm-functions-registry/tree/main/krm-functions)) + + +## Publishing KRM function metadata in-tree and out-of-tree functions - +To publish KRM function metadata, independently of where the source code lives, follow the instructions +in the [publishers directory](https://github.com/kubernetes-sigs/krm-functions-registry/tree/main/publishers). + +## General Kubernetes Contributing docs + +We have full documentation on how to get started contributing here: - [Contributor License Agreement](https://git.k8s.io/community/CLA.md) Kubernetes projects require that you sign a Contributor License Agreement (CLA) before we can accept your pull requests - [Kubernetes Contributor Guide](https://git.k8s.io/community/contributors/guide) - Main contributor documentation, or you can just jump directly to the [contributing section](https://git.k8s.io/community/contributors/guide#contributing) @@ -20,16 +58,7 @@ If your repo has certain guidelines for contribution, put them here ahead of the - [Mentoring Initiatives](https://git.k8s.io/community/mentoring) - We have a diverse set of mentorship programs available that are always looking for volunteers! - - - +- [Slack channel](https://kubernetes.slack.com/messages/sig-cli-krm-functions) \ No newline at end of file diff --git a/OWNERS b/OWNERS index d6c71de..8a763fa 100644 --- a/OWNERS +++ b/OWNERS @@ -2,3 +2,4 @@ approvers: - krm-functions-registry-owners + - krm-functions-registry-maintainers diff --git a/OWNERS_ALIASES b/OWNERS_ALIASES index 156a2aa..a24b2cf 100644 --- a/OWNERS_ALIASES +++ b/OWNERS_ALIASES @@ -6,6 +6,9 @@ aliases: - KnVerey - mengqiy + krm-functions-registry-maintainers: + - natasha41575 + sig-cli-functions-approvers: - jeremyrickard - KnVerey diff --git a/README.md b/README.md index 51c88b8..03d86f2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,17 @@ # krm-functions-registry -Public registry for KRM functions +Public registry of KRM functions. This repo hosts a centralized index for KRM +functions and donated source code for some KRM functions. + +## Background, contributing, and releasing + +[KEP] + +[Open an Issue] + +[Contributor Guide] + +[Release Process] ## Community, discussion, contribution, and support @@ -15,5 +26,10 @@ You can reach the maintainers of this project at: Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md). +[KEP]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/2985-public-krm-functions-registry +[Contributor Guide]: CONTRIBUTING.md +[Release Process]: RELEASING.md +[Open an Issue]: https://github.com/kubernetes-sigs/krm-functions-registry/issues + [owners]: https://git.k8s.io/community/contributors/guide/owners.md [Creative Commons 4.0]: https://git.k8s.io/website/LICENSE diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..0fad3d7 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,5 @@ +# Release Process \[TODO\] + +This doc will cover the release process for the in-tree KRM +functions whose source code is stored here. + diff --git a/krm-functions/README.md b/krm-functions/README.md new file mode 100644 index 0000000..add01c7 --- /dev/null +++ b/krm-functions/README.md @@ -0,0 +1,35 @@ +# KRM Functions + +This directory is the home for the source code for all in-tree functions that are maintained and +released by this repository. + +## Requirements + +By donating a function's source code to this repo, you are donating the function to SIG-CLI. We cannot +accept 3rd party functions as in-tree functions. + +## Files + +Each publisher will need to create their own subdirectory `krm-functions/{PUBLISHER}/` +in this directory to store their functions source code, under . For example, SIG-CLI sponsored functions are located +under `krm-functions/sig-cli/`. + +Each function must be in its own subdirectory `krm-functions/{PUBLISHER}/{FUNCTION NAME}/`. This directory should +contain: +- An OWNERS file to approve code changes to the function. +- A README.md file to provide a user guide for the function. +- Source code and unit tests. +- A Dockerfile that describes how to build the function image. +- An `examples/` directory. An `examples/` directory. Examples that will serve both as examples for functions and as e2e tests. Each example should have its + own subdirectory `krm-functions/{PUBLISHER}/{FUNCTION NAME}/examples/{EXAMPLE_NAME}/`, and this directory should contain: + - A README.md file that serves as a guide for the example. + - A subdirectory `.expected`. This should contain two files: + - `exec.sh`: A script that will run your example. This script will be run on the example directory it is in. This can + be something as simple as `kustomize build --enable-alpha-plugins > resources.yaml`. + - `diff.patch`: This file should contain the expected diff between the original example directory files and the files + after `exec.sh` is run. + - Any additional files needed for your examples to run. For example, if you are running `kustomize build` in your `exec.sh` + script, you will need a kustomization file. + +An example of this is SIG-CLI's [render-helm-chart](https://github.com/kubernetes-sigs/krm-functions-registry/tree/main/krm-functions/sig-cli/render-helm-chart) +function. diff --git a/krm-functions/sig-cli/render-helm-chart/README.md b/krm-functions/sig-cli/render-helm-chart/README.md index f3b8cfd..6316949 100644 --- a/krm-functions/sig-cli/render-helm-chart/README.md +++ b/krm-functions/sig-cli/render-helm-chart/README.md @@ -19,8 +19,6 @@ helm binary directly. You can learn more about helm [here][helm] and more about helm charts [here][charts]. - - ## Usage This function can be used with any KRM function orchestrators such to render a specified helm chart. @@ -29,8 +27,6 @@ field is needed for local charts. ### FunctionConfig - - There are 2 kinds of `functionConfig` supported by this function: - `ConfigMap` @@ -96,7 +92,6 @@ helmCharts: valuesFiles: []string valuesInline: map[string]interface{} valuesMerge: string - ``` | Field | Description | Example @@ -110,6 +105,7 @@ helmCharts: `name` | The name of the chart | minecraft `version` | The version of the chart | 3.1.3 `repo` | A URL locating the chart on the internet | https://itzg.github.io/minecraft-server-charts +`apiVersions` | Kubernetes api versions used for Capabilities.APIVersions | acme.cert-manager.io/v1 `releaseName` | Replaces RELEASE_NAME in the chart template output | test `namespace` | Sets the target namespace for a release (`.Release.Namespace` in the template) | my-namespace `nameTemplate` | Specify the template used to name the release | gatekeeper @@ -120,8 +116,6 @@ helmCharts: `valuesFiles` | Remote or local filepaths to use instead of the default values that accompanied the chart. The default values are in '{chartHome}/{name}/values.yaml', where `chartHome` and `name` are the parameters defined above. | Using a local values file: path/to/your/values.yaml

Using a remote values file: https://raw.githubusercontent.com/config-sync-examples/helm-components/main/cert-manager-values.yaml `valuesMerge` | ValuesMerge specifies how to treat ValuesInline with respect to ValuesFiles. Legal values: 'merge', 'override' (default), 'replace'. | replace - - [helm]: https://helm.sh/ [charts]: https://helm.sh/docs/topics/charts/ [helm template command]: https://helm.sh/docs/helm/helm_template/ diff --git a/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-inline-values/.krmignore b/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-inline-values/.krmignore deleted file mode 100644 index 9d7a400..0000000 --- a/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-inline-values/.krmignore +++ /dev/null @@ -1 +0,0 @@ -.expected diff --git a/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-inline-values/README.md b/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-inline-values/README.md index 6d0b157..3837ddc 100644 --- a/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-inline-values/README.md +++ b/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-inline-values/README.md @@ -1,5 +1,86 @@ # render-helm-chart: Kustomize Inline Values - +### Overview + +This example demonstrates how to declaratively invoke the `render-helm-chart` +function with kustomize using the `valuesInline` field. + +### Function invocation + +To use the function with kustomize, you can specify the `functionConfig` +in your kustomization's `generators` field. This example uses inline values +to use instead of the default values accompanying the chart: + +kustomization.yaml: +```yaml +generators: + - |- + apiVersion: v1alpha1 + kind: RenderHelmChart + metadata: + name: demo + annotations: + config.kubernetes.io/function: | + container: + network: true + image: us.gcr.io/k8s-artifacts-prod/krm-functions/render-helm-chart:unstable + helmCharts: + - chartArgs: + name: ocp-pipeline + version: 0.1.16 + repo: https://bcgov.github.io/helm-charts + templateOptions: + releaseName: moria + namespace: mynamespace + values: + valuesInline: + releaseNamespace: "" + rbac: + create: true + rules: + - apiGroups: [""] + verbs: ["*"] + resources: ["*"] +``` + +Then, to build the kustomization with kustomize v4: + +```shell +kustomize build --enable-alpha-plugins --network . +``` + +### Expected result + +You should also be able to find the line `def releaseNamespace = ""` somewhere +in your output, as well as the following: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: moria-ocp-pipeline + namespace: mynamespace +rules: +- apiGroups: + - "" + resources: + - '*' + verbs: + - '*' +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: moria-ocp-pipeline + namespace: mynamespace +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: moria-ocp-pipeline +subjects: +- kind: ServiceAccount + name: jenkins + namespace: mynamespace +``` + +which demonstrates that the correct values provided via `valuesInline` were used. \ No newline at end of file diff --git a/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-values-files/README.md b/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-values-files/README.md index 7f27f46..df9d226 100644 --- a/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-values-files/README.md +++ b/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-values-files/README.md @@ -1,5 +1,81 @@ # render-helm-chart: Kustomize Values Files - \ No newline at end of file +### Overview + +This example demonstrates how to declaratively invoke the `render-helm-chart` +function with kustomize using multiple values files. + +### Function invocation + +To use the function with kustomize, you can specify the `functionConfig` +in your kustomization's `generators` field. This example specifies multiple remote +values files to use instead of the default values accompanying the chart: + +kustomization.yaml: +```yaml +generators: + - |- + apiVersion: v1alpha1 + kind: RenderHelmChart + metadata: + name: demo + annotations: + config.kubernetes.io/function: | + container: + network: true + image: us.gcr.io/k8s-artifacts-prod/krm-functions/render-helm-chart:unstable + helmCharts: + - chartArgs: + name: ocp-pipeline + version: 0.1.16 + repo: https://bcgov.github.io/helm-charts + templateOptions: + namespace: mynamespace + releaseName: moria + values: + valuesFiles: + - https://raw.githubusercontent.com/natasha41575/kpt-functions-catalog/a9c9cd765a05f7a7fb6923dbde4651b62c9c229c/examples/render-helm-chart-kustomize-values-files/file1.yaml + - https://raw.githubusercontent.com/natasha41575/kpt-functions-catalog/a9c9cd765a05f7a7fb6923dbde4651b62c9c229c/examples/render-helm-chart-kustomize-values-files/file2.yaml +``` + +Then, to build the kustomization with kustomize v4: + +```shell +kustomize build --enable-alpha-plugins --network . +``` + +### Expected result + +You should also be able to find the line `def releaseNamespace = ""` somewhere +in your output, as well as the following: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: moria-ocp-pipeline + namespace: mynamespace +rules: +- apiGroups: + - "" + resources: + - '*' + verbs: + - '*' +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: moria-ocp-pipeline + namespace: mynamespace +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: moria-ocp-pipeline +subjects: +- kind: ServiceAccount + name: jenkins + namespace: mynamespace +``` + +which demonstrates that the correct values provided via `valuesFiles` were used. \ No newline at end of file diff --git a/krm-functions/sig-cli/render-helm-chart/metadata.yaml b/krm-functions/sig-cli/render-helm-chart/metadata.yaml deleted file mode 100644 index 545df8b..0000000 --- a/krm-functions/sig-cli/render-helm-chart/metadata.yaml +++ /dev/null @@ -1,17 +0,0 @@ -# Copyright 2022 The Kubernetes Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# TODO: Add metadata.yaml file here, based on the function metadata schema -# defined here https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/2985-public-krm-functions-registry#function-metadata -# and add CI to verify the metadata diff --git a/publishers/README.md b/publishers/README.md new file mode 100644 index 0000000..0d4181f --- /dev/null +++ b/publishers/README.md @@ -0,0 +1,18 @@ +# Publishers + +This directory is the home for all published KRM functions metadata. Each publisher should create their own +subdirectory containing: + +- An OWNERS file containing a list of owners of the publisher +- A README.md file with a description of who the publisher is +- A `functions` directory, containing a file for each published KRM function. The KRM function metadata file should be named after the function, + `{FUNCTION-NAME}.yaml`. This file should be a kubernetes object of type KRMFunctionDefinition, + which is defined in the [Catalog KEP]. +- A `catalogs` directory, containing a file for each published functions Catalog. Each catalog file should be named with the date it was + published, in the form `v{YYYY}{MM}{DD}.yaml`, e.g. `v20220225.yaml`. + +See [SIG-CLI functions] as an example. + +[SIG-CLI functions]: (https://github.com/kubernetes-sigs/krm-functions-registry/tree/main/publishers/sig-cli) + +[Catalog KEP]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/2906-kustomize-function-catalog#function-metadata-schema \ No newline at end of file diff --git a/publishers/sig-cli/OWNERS b/publishers/sig-cli/OWNERS new file mode 100644 index 0000000..064cbf0 --- /dev/null +++ b/publishers/sig-cli/OWNERS @@ -0,0 +1,4 @@ +# See the OWNERS docs at https://go.k8s.io/owners + +approvers: +- sig-cli-functions-approvers diff --git a/publishers/sig-cli/README.md b/publishers/sig-cli/README.md new file mode 100644 index 0000000..d9a04c7 --- /dev/null +++ b/publishers/sig-cli/README.md @@ -0,0 +1,2 @@ +This directory contains published KRM function metadata and catalogs for +[SIG-CLI](https://github.com/kubernetes/community/tree/master/sig-cli). \ No newline at end of file diff --git a/publishers/sig-cli/catalogs/v20220225.yaml b/publishers/sig-cli/catalogs/v20220225.yaml new file mode 100644 index 0000000..f7b9340 --- /dev/null +++ b/publishers/sig-cli/catalogs/v20220225.yaml @@ -0,0 +1 @@ +# This file is just a placeholder until we have a published catalog. \ No newline at end of file diff --git a/publishers/sig-cli/functions/render-helm-chart.yaml b/publishers/sig-cli/functions/render-helm-chart.yaml new file mode 100644 index 0000000..0491445 --- /dev/null +++ b/publishers/sig-cli/functions/render-helm-chart.yaml @@ -0,0 +1,127 @@ +# Copyright 2022 The Kubernetes Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# TODO: Add CI to validate the metadata here. + +apiVersion: config.kubernetes.io/v1alpha1 +kind: KRMFunctionDefinition +spec: + group: config.kubernetes.io + description: "The `render-helm-chart` function renders a local or remote Helm chart." + publisher: https://github.com/kubernetes/community/tree/master/sig-cli + names: + kind: RenderHelmChart + versions: + name: v1 + idempotent: true + license: Apache 2.0 + maintainers: + - natashasarkar@google.com + - mengqiy@google.com + - katrina.verey@shopify.com + usage: https://github.com/kubernetes-sigs/krm-functions-registry/blob/main/krm-functions/sig-cli/render-helm-chart/README.md + examples: + - https://github.com/kubernetes-sigs/krm-functions-registry/blob/main/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-inline-values/README.md + - https://github.com/kubernetes-sigs/krm-functions-registry/blob/main/krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-values-files/README.md + runtime: + container: + image: us.gcr.io/k8s-artifacts-prod/krm-functions/render-helm-chart:unstable + requireNetwork: true + requireStorageMount: true + schema: + openAPIV3Schema: + properties: + apiVersion: + type: string + kind: + type: string + metadata: + type: object + properties: + name: + type: string + minLength: 1 + required: + - name + helmGlobals: + description: parameters applied to all helm charts. + type: object + properties: + chartHome: + description: + type: string + configHome: + description: + type: string + helmCharts: + description: an array of helm chart parameters. + type: array + items: + type: object + description: parameters to configure the helm chart rendering. + properties: + chartArgs: + description: arguments that describe the chart being rendered. + type: object + properties: + name: + description: the name of the chart. + type: string + version: + description: the version of the chart. + type: string + repo: + description: URL locating the chart on the internet + type: string + templateOptions: + description: a collection of fields that map to flag options of `helm template`. + type: object + properties: + apiVersions: + description: kubernetes api versions used for Capabilities.APIVersions + type: array + items: + type: string + releaseName: + description: replaces RELEASE_NAME in the chart template output + type: string + namespace: string + description: + type: string + nameTemplate: + description: sets the target namespace for a release (`.Release.Namespace` in the template) + type: string + includeCRDs: + description: specifies if Helm should also generate CustomResourceDefinitions. Legal values are "true", "false" (default). + type: bool + skipTests: + description: if set, skip tests from templated output. Legal values are "true", "false" (default). + type: bool + values: + description: values to use instead of the default values that accompany the chart. + type: object + properties: + valuesFiles: + description: remote or local filepaths to use instead of the default values that accompanied the chart. The default values are in '{chartHome}/{name}/values.yaml', where `chartHome` and `name` are the parameters defined above. + type: array + items: + type: string + valuesInline: + description: values defined inline to use instead of default values that accompany the chart. + type: object + additionalProperties: + type: string + valuesMerge: + description: valuesMerge specifies how to treat ValuesInline with respect to ValuesFiles. Legal values are 'merge', 'override' (default), 'replace'. + type: string diff --git a/site/README.md b/site/README.md new file mode 100644 index 0000000..7ed775a --- /dev/null +++ b/site/README.md @@ -0,0 +1,4 @@ +# Site \[TODO\] + +This directory will contain the source code for the site contents that will be used to display +the published functions metadata. \ No newline at end of file