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 generating

• pkg/clientset: Go clientsets for users who want to interact

with Kong's Kubernetes configuration in Go

• config/crd: Kubernetes CRDs for all supported [channels]
• test/ directory contains Go tests

• test/crdsvalidation directory contains Go tests which

perform operations against a live Kubernetes cluster, testing CEL rules set on API types

• test/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 Controller
• ingress-controller-incubator - experimental CRDs for Kong Ingress Controller
• gateway-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 -

Optionally you can specify the ref to use via the ?ref=<tag> query parameter.

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 -

To install the CRDs from kubernetes-configuration v1.2.0 tag for the Kong Gateway Operator, you can run:

kustomize build github.com/kong/kubernetes-configuration/config/crd/gateway-operator\?ref=v1.2.0 | kubectl apply --server-side -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?

Releases are driven by changes in the VERSION file. This file contains 2 lines:

• The first line is the version number (e.g. 1.0.0).
• The second line indicates if the version should be marked as latest or not

(e.g. latest for latest, anything else is not marked as latest).

To release a new version:

• Pick a new version.
• Make sure a changelog is updated with the new version, the release date, and all the changes.
• Update the VERSION file with said version and whether the version should be marked as latest.

This can be done in a separate PR or along with the PR that introduces the changes.

The [release_on_version_change.yaml] workflow will be triggered when a commit changing the VERSION file is pushed to the main branch. Releases created with this approach will be marked as latest

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.