README ¶
kubernetes-configuration
This repository holds the API definitions for Kong's Kubernetes configuration.
Repository structure
api/
directory contains Go types that are the source for generatingpkg/clientset
: Go clientsets for users who want to interact with Kong's Kubernetes configuration in Go
config/crd
: Kubernetes CRDs for all supported channelstest/
directory contains Go teststest/crdsvalidation
directory contains Go tests which perform operations against a live Kubernetes cluster, testing CEL rules set on API typestest/unit
directory contains Go unit tests for generated Go types
docs/
directory contains generated API reference markdown files
Channels
This repository supports multiple channels of CRDs. Each channel is an independent collection
of CRDs that is meant to be used by a designated product or project. Manifests for each channel
are stored in a separate directory under config/crd/<channel>
(each has a generated kustomize.yaml
file as well).
The following channels are supported:
ingress-controller
- CRDs for Kong Ingress Controlleringress-controller-incubator
- experimental CRDs for Kong Ingress Controllergateway-operator
- CRDs for Kong Gateway Operator
A single CRD can be included in multiple channels. See available custom markers for more details.
Install CRDs
In order to install the CRDs from this repo, you can use the following command, replacing
<channel>
with one of the supported channel names.
kustomize build github.com/kong/kubernetes-configuration/config/crd/<channel> | kubectl apply -f -
For example, to install the CRDs for the Kong Ingress Controller, you can run:
kustomize build github.com/kong/kubernetes-configuration/config/crd/ingress-controller | kubectl apply -f -
Generate code
In order to run code generation in this repo you can use make generate
.
Adding new CRDs
When you add a new CRD make sure to
- Annotate the CRD with
+kong:channels
marker to specify the channels that the CRD should be published to. - Add unit tests in
test/unit
- Add CRD validation tests in
test/crdsvalidation
- If you want
GetItems() []T
helper to be generated for your type, add it to supported type list. - If this CRD is meant to have Konnect helpers functions generated for it, add it in supported type list.
- Annotate the CRD and any new type it depends on with the right markers to make sure it will be included in the generated documentation. See [available markers](#Available custom markers).
How to release?
- Make sure a changelog is updated with the new version, the release date, and all the changes.
- Trigger a release workflow. This will create a tag a release in GitHub.
Available custom markers
Name | Applies to | Meaning |
---|---|---|
+kong:channels |
Types | Any root object type annotated with this marker will be included in a CRD channel passed as a marker value (e.g. +kong:channels=ingress-controller;gateway-operator will include the CRD both in ingress-controller and gateway-operator channels). |
+apireference:kgo:exclude |
Fields | Any field annotated with this marker will be excluded from the KGO's generated CRDs reference. |
+apireference:kgo:include |
Types | Any type annotated with this marker will be included in the KGO's generated CRDs reference. |
+apireference:kic:exclude |
Fields | Any type annotated with this marker will be excluded from the KIC's generated CRDs reference. |
+apireference:kic:include |
Types | Any type annotated with this marker will be included in the KIC's generated CRDs reference. |
Why do we need separate markers for API reference and channels?
Channels are used to group CRDs into logical sets that are meant to be used by a specific product or project. API reference markers are used to control which types and fields are included in the generated API reference documentation. While the channels are enough to be defined on a root object type, the API reference markers need to be defined on each type or field that should be included/excluded in the generated API reference documentation.
Currently, we don't have a way to automatically generate API reference documentation based only on channels, so we need separate markers for this purpose.
Directories ¶
Path | Synopsis |
---|---|
api
|
|
configuration/v1
Package v1 contains API Schema definitions for the konghq.com v1 API group.
|
Package v1 contains API Schema definitions for the konghq.com v1 API group. |
configuration/v1alpha1
Package v1alpha1 contains API Schema definitions for the configuration.konghq.com v1alpha1 API group.
|
Package v1alpha1 contains API Schema definitions for the configuration.konghq.com v1alpha1 API group. |
configuration/v1beta1
Package v1beta1 contains API Schema definitions for the configuration.konghq.com v1beta1 API group.
|
Package v1beta1 contains API Schema definitions for the configuration.konghq.com v1beta1 API group. |
incubator
Package incubator contains API Schema definitions for the incubator.ingress-controller.konghq.com API group.
|
Package incubator contains API Schema definitions for the incubator.ingress-controller.konghq.com API group. |
incubator/v1alpha1
Package v1alpha1 contains API Schema definitions for the incubator.ingress-controller.konghq.com v1alpha1 API group.
|
Package v1alpha1 contains API Schema definitions for the incubator.ingress-controller.konghq.com v1alpha1 API group. |
konnect/v1alpha1
Package v1alpha1 contains API Schema definitions for the konnect.konghq.com v1alpha1 API group.
|
Package v1alpha1 contains API Schema definitions for the konnect.konghq.com v1alpha1 API group. |
pkg
|
|
clientset/fake
This package has the automatically generated fake clientset.
|
This package has the automatically generated fake clientset. |
clientset/scheme
This package contains the scheme of the automatically generated clientset.
|
This package contains the scheme of the automatically generated clientset. |
clientset/typed/configuration/v1
This package has the automatically generated typed clients.
|
This package has the automatically generated typed clients. |
clientset/typed/configuration/v1/fake
Package fake has the automatically generated clients.
|
Package fake has the automatically generated clients. |
clientset/typed/configuration/v1alpha1
This package has the automatically generated typed clients.
|
This package has the automatically generated typed clients. |
clientset/typed/configuration/v1alpha1/fake
Package fake has the automatically generated clients.
|
Package fake has the automatically generated clients. |
clientset/typed/configuration/v1beta1
This package has the automatically generated typed clients.
|
This package has the automatically generated typed clients. |
clientset/typed/configuration/v1beta1/fake
Package fake has the automatically generated clients.
|
Package fake has the automatically generated clients. |
clientset/typed/incubator/v1alpha1
This package has the automatically generated typed clients.
|
This package has the automatically generated typed clients. |
clientset/typed/incubator/v1alpha1/fake
Package fake has the automatically generated clients.
|
Package fake has the automatically generated clients. |
clientset/typed/konnect/v1alpha1
This package has the automatically generated typed clients.
|
This package has the automatically generated typed clients. |
clientset/typed/konnect/v1alpha1/fake
Package fake has the automatically generated clients.
|
Package fake has the automatically generated clients. |
scripts
|
|
crds-generator
This script is responsible for generating CRDs.
|
This script is responsible for generating CRDs. |