kubernetes-configuration

module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 21, 2025 License: MIT

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 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:

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?

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.

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.
test

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL