chore: annotate KGO supported types

README.md

@@ -51,6 +51,8 @@ When you add a new CRD make sure to
 - Add CRD validation tests in [`test/crdsvalidation`][testcrdsvalidation]
 - If this CRD is meant to have Konnect helpers functions generated for it,
   add it in [konnect-funcs supported type list][konnect_funcs_gen].
+- 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).
 
 [crd_kustomization]: ./config/crd/kustomization.yaml
 [konnect_funcs_gen]: ./scripts/konnect-funcs/supportedtypes.go
@@ -59,3 +61,12 @@ When you add a new CRD make sure to
 
 Currently in order to make a new release/tag available for users to use is to
 create a new tag and push it to the repository.
+
+## Available custom markers
+
+| Name                        | Applies to | Meaning                                                                                                       |
+|-----------------------------|------------|---------------------------------------------------------------------------------------------------------------|
+| `+apireference:kgo:exclude` | Fields     | Any field annotated with this marker will be excluded from the [KGO's generated CRDs reference][kgo-crd-ref]. |
+| `+apireference:kgo:include` | Types      | Any type annotated with this marker will be included in the [KGO's generated CRDs reference][kgo-crd-ref].    |
+
+[kgo-crd-ref]: https://github.com/Kong/gateway-operator/blob/main/docs/api-reference.md

api/configuration/v1/conditions.go

@@ -2,10 +2,12 @@ package v1
 
 // ConditionType is a type of condition associated with an object.
 // This type should be used with the object's Status.Conditions field.
+// +apireference:kgo:include
 type ConditionType string
 
 // ConditionReason defines the set of reasons that explain why a particular
 // condition type has been raised.
+// +apireference:kgo:include
 type ConditionReason string
 
 const (

api/configuration/v1/kongconsumer_types.go

@@ -23,6 +23,8 @@ import (
 	konnectv1alpha1 "github.com/kong/kubernetes-configuration/api/konnect/v1alpha1"
 )
 
+// KongConsumer is the Schema for the kongconsumers API.
+//
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 // +kubebuilder:object:root=true
@@ -36,8 +38,7 @@ import (
 // +kubebuilder:validation:XValidation:rule="!has(oldSelf.spec.controlPlaneRef) || has(self.spec.controlPlaneRef)", message="controlPlaneRef is required once set"
 // +kubebuilder:validation:XValidation:rule="!has(self.spec.controlPlaneRef.konnectNamespacedRef) ? true : !has(self.spec.controlPlaneRef.konnectNamespacedRef.__namespace__)", message="spec.controlPlaneRef cannot specify namespace for namespaced resource"
 // +kubebuilder:validation:XValidation:rule="(!has(self.status) || !self.status.conditions.exists(c, c.type == 'Programmed' && c.status == 'True')) ? true : oldSelf.spec.controlPlaneRef == self.spec.controlPlaneRef", message="spec.controlPlaneRef is immutable when an entity is already Programmed"
-
-// KongConsumer is the Schema for the kongconsumers API.
+// +apireference:kgo:include
 type KongConsumer struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -67,15 +68,16 @@ type KongConsumer struct {
 }
 
 // KongConsumerSpec defines the specification of the KongConsumer.
+// +apireference:kgo:include
 type KongConsumerSpec struct {
 	// ControlPlaneRef is a reference to a ControlPlane this Consumer is associated with.
 	// +optional
 	ControlPlaneRef *configurationv1alpha1.ControlPlaneRef `json:"controlPlaneRef,omitempty"`
 }
 
-// +kubebuilder:object:root=true
-
 // KongConsumerList contains a list of KongConsumer.
+// +kubebuilder:object:root=true
+// +apireference:kgo:include
 type KongConsumerList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`

api/configuration/v1/kongplugin_types.go

@@ -22,6 +22,8 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
+// KongPlugin is the Schema for the kongplugins API.
+//
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 // +kubebuilder:object:root=true
@@ -36,8 +38,7 @@ import (
 // +kubebuilder:validation:XValidation:rule="!(has(self.config) && has(self.configFrom))", message="Using both config and configFrom fields is not allowed."
 // +kubebuilder:validation:XValidation:rule="!(has(self.configFrom) && has(self.configPatches))", message="Using both configFrom and configPatches fields is not allowed."
 // +kubebuilder:validation:XValidation:rule="self.plugin == oldSelf.plugin", message="The plugin field is immutable"
-
-// KongPlugin is the Schema for the kongplugins API.
+// +apireference:kgo:include
 type KongPlugin struct {
 	metav1.TypeMeta `json:",inline"`
 	// Setting a `global` label to `true` will apply the plugin to every request proxied by the Kong.
@@ -62,6 +63,8 @@ type KongPlugin struct {
 	// This should be used when the plugin configuration contains sensitive information,
 	// such as AWS credentials in the Lambda plugin or the client secret in the OIDC plugin.
 	// Only one of `config` or `configFrom` may be used in a KongPlugin, not both at once.
+	//
+	// +apireference:kgo:exclude
 	ConfigFrom *ConfigSource `json:"configFrom,omitempty"`
 
 	// ConfigPatches represents JSON patches to the configuration of the plugin.
@@ -70,6 +73,8 @@ type KongPlugin struct {
 	// a key in a secret.
 	// When Config is specified, patches will be applied to the configuration in Config.
 	// Otherwise, patches will be applied to an empty object.
+	//
+	// +apireference:kgo:exclude
 	ConfigPatches []ConfigPatch `json:"configPatches,omitempty"`
 
 	// PluginName is the name of the plugin to which to apply the config.
@@ -100,16 +105,17 @@ type KongPlugin struct {
 	Status KongPluginStatus `json:"status,omitempty"`
 }
 
-// +kubebuilder:object:root=true
-
 // KongPluginList contains a list of KongPlugin.
+// +kubebuilder:object:root=true
+// +apireference:kgo:include
 type KongPluginList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`
 	Items           []KongPlugin `json:"items"`
 }
 
 // KongPluginStatus represents the current status of the KongPlugin resource.
+// +apireference:kgo:include
 type KongPluginStatus struct {
 	// Conditions describe the current conditions of the KongPluginStatus.
 	//

api/configuration/v1/kongprotocol_types.go

@@ -4,6 +4,7 @@ package v1
 // This alias is necessary to deal with https://github.com/kubernetes-sigs/controller-tools/issues/342
 // +kubebuilder:validation:Enum=http;https;grpc;grpcs;tcp;tls;udp
 // +kubebuilder:object:generate=true
+// +apireference:kgo:include
 type KongProtocol string
 
 // KongProtocolsToStrings converts a slice of KongProtocol to plain strings.

api/configuration/v1alpha1/key_set_ref.go

@@ -2,6 +2,7 @@ package v1alpha1
 
 // KeySetRefType is the enum type for the KeySetRef.
 // +kubebuilder:validation:Enum=konnectID;namespacedRef
+// +apireference:kgo:include
 type KeySetRefType string
 
 const (
@@ -19,6 +20,7 @@ const (
 // It is used to reference a KeySet entity.
 // +kubebuilder:validation:XValidation:rule="self.type == 'namespacedRef' ? has(self.namespacedRef) : true", message="when type is namespacedRef, namespacedRef must be set"
 // +kubebuilder:validation:XValidation:rule="self.type == 'konnectID' ? has(self.konnectID) : true", message="when type is konnectID, konnectID must be set"
+// +apireference:kgo:include
 type KeySetRef struct {
 	// Type defines type of the KeySet object reference. It can be one of:
 	// - konnectID
@@ -37,6 +39,7 @@ type KeySetRef struct {
 }
 
 // KeySetNamespacedRef is the schema for the KeySetNamespacedRef type.
+// +apireference:kgo:include
 type KeySetNamespacedRef struct {
 	// Name is the name of the KeySet object.
 	// +kubebuilder:validation:MinLength=1

api/configuration/v1alpha1/kong_ca_certificate.go

@@ -18,6 +18,7 @@ import (
 // +kubebuilder:validation:XValidation:rule="!has(oldSelf.spec.controlPlaneRef) || has(self.spec.controlPlaneRef)", message="controlPlaneRef is required once set"
 // +kubebuilder:validation:XValidation:rule="!has(self.spec.controlPlaneRef.konnectNamespacedRef) ? true : !has(self.spec.controlPlaneRef.konnectNamespacedRef.__namespace__)", message="spec.controlPlaneRef cannot specify namespace for namespaced resource"
 // +kubebuilder:validation:XValidation:rule="(!self.status.conditions.exists(c, c.type == 'Programmed' && c.status == 'True')) ? true : oldSelf.spec.controlPlaneRef == self.spec.controlPlaneRef", message="spec.controlPlaneRef is immutable when an entity is already Programmed"
+// +apireference:kgo:include
 type KongCACertificate struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -29,13 +30,15 @@ type KongCACertificate struct {
 }
 
 // KongCACertificateSpec contains the specification for the KongCACertificate.
+// +apireference:kgo:include
 type KongCACertificateSpec struct {
 	// ControlPlaneRef references the Konnect Control Plane that this KongCACertificate should be created in.
 	ControlPlaneRef          *ControlPlaneRef `json:"controlPlaneRef,omitempty"`
 	KongCACertificateAPISpec `json:",inline"`
 }
 
 // KongCACertificateAPISpec contains the API specification for the KongCACertificate.
+// +apireference:kgo:include
 type KongCACertificateAPISpec struct {
 	// Cert is the PEM-encoded CA certificate.
 	// +kubebuilder:validation:Required
@@ -45,6 +48,7 @@ type KongCACertificateAPISpec struct {
 }
 
 // KongCACertificateStatus defines the observed state of KongCACertificate.
+// +apireference:kgo:include
 type KongCACertificateStatus struct {
 	// Konnect contains the Konnect entity status.
 	// +optional
@@ -60,6 +64,7 @@ type KongCACertificateStatus struct {
 
 // KongCACertificateList contains a list of KongCACertificates.
 // +kubebuilder:object:root=true
+// +apireference:kgo:include
 type KongCACertificateList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`

api/configuration/v1alpha1/kong_certificate.go

@@ -17,6 +17,7 @@ import (
 // +kubebuilder:printcolumn:name="Programmed",description="The Resource is Programmed on Konnect",type=string,JSONPath=`.status.conditions[?(@.type=='Programmed')].status`
 // +kubebuilder:validation:XValidation:rule="!has(oldSelf.spec.controlPlaneRef) || has(self.spec.controlPlaneRef)", message="controlPlaneRef is required once set"
 // +kubebuilder:validation:XValidation:rule="(!self.status.conditions.exists(c, c.type == 'Programmed' && c.status == 'True')) ? true : oldSelf.spec.controlPlaneRef == self.spec.controlPlaneRef", message="spec.controlPlaneRef is immutable when an entity is already Programmed"
+// +apireference:kgo:include
 type KongCertificate struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -28,13 +29,15 @@ type KongCertificate struct {
 }
 
 // KongCertificateSpec contains the specification for the KongCertificate.
+// +apireference:kgo:include
 type KongCertificateSpec struct {
 	// ControlPlaneRef references the Konnect Control Plane that this KongCertificate should be created in.
 	ControlPlaneRef        *ControlPlaneRef `json:"controlPlaneRef,omitempty"`
 	KongCertificateAPISpec `json:",inline"`
 }
 
 // KongCertificateAPISpec contains the API specification for the KongCertificate.
+// +apireference:kgo:include
 type KongCertificateAPISpec struct {
 	// Cert is the PEM-encoded certificate.
 	// +kubebuilder:validation:Required
@@ -58,6 +61,7 @@ type KongCertificateAPISpec struct {
 }
 
 // KongCertificateStatus defines the observed state of KongCertificate.
+// +apireference:kgo:include
 type KongCertificateStatus struct {
 	// Konnect contains the Konnect entity status.
 	// +optional
@@ -73,6 +77,7 @@ type KongCertificateStatus struct {
 
 // KongCertificateList contains a list of KongCertificates.
 // +kubebuilder:object:root=true
+// +apireference:kgo:include
 type KongCertificateList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`

api/configuration/v1alpha1/kong_license_types.go

@@ -4,6 +4,8 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
+// KongLicense stores a Kong enterprise license to apply to managed Kong gateway instances.
+//
 // +genclient
 // +genclient:nonNamespaced
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
@@ -13,8 +15,7 @@ import (
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`,description="Age"
 // +kubebuilder:printcolumn:name="Enabled",type=boolean,JSONPath=`.enabled`,description="Enabled to configure on Kong gateway instances"
-
-// KongLicense stores a Kong enterprise license to apply to managed Kong gateway instances.
+// +apireference:kgo:include
 type KongLicense struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -29,6 +30,7 @@ type KongLicense struct {
 }
 
 // KongLicenseStatus stores the status of the KongLicense being processesed in each controller that reconciles it.
+// +apireference:kgo:include
 type KongLicenseStatus struct {
 	// +listType=map
 	// +listMapKey=controllerName
@@ -37,6 +39,7 @@ type KongLicenseStatus struct {
 
 // KongLicenseControllerStatus is the status of owning KongLicense being processed
 // identified by the controllerName field.
+// +apireference:kgo:include
 type KongLicenseControllerStatus struct {
 	// ControllerName is an identifier of the controller to reconcile this KongLicense.
 	// Should be unique in the list of controller statuses.
@@ -56,18 +59,21 @@ type KongLicenseControllerStatus struct {
 // RFC 1123 subdomain.
 // +kubebuilder:validation:MaxLength=253
 // +kubebuilder:validation:Pattern=`^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
+// +apireference:kgo:include
 type Group string
 
 // Kind refers to a Kubernetes kind.
 // +kubebuilder:validation:MinLength=1
 // +kubebuilder:validation:MaxLength=63
 // +kubebuilder:validation:Pattern=`^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$`
+// +apireference:kgo:include
 type Kind string
 
 // Namespace refers to a Kubernetes namespace. It must be a RFC 1123 label.
 // +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
 // +kubebuilder:validation:MinLength=1
 // +kubebuilder:validation:MaxLength=63
+// +apireference:kgo:include
 type Namespace string
 
 // ObjectName refers to the name of a Kubernetes object.
@@ -76,9 +82,11 @@ type Namespace string
 //
 // +kubebuilder:validation:MinLength=1
 // +kubebuilder:validation:MaxLength=253
+// +apireference:kgo:include
 type ObjectName string
 
 // ControllerReference is a reference to a controller that reconciles the KongLicense.
+// +apireference:kgo:include
 type ControllerReference struct {
 	// Group is the group of referent.
 	// It should be empty if the referent is in "core" group (like pod).
@@ -93,12 +101,9 @@ type ControllerReference struct {
 	Name ObjectName `json:"name"`
 }
 
-// KongLicensePhase is a string that represents the phase of the KongLicense.
-type KongLicensePhase string
-
-// +kubebuilder:object:root=true
-
 // KongLicenseList contains a list of KongLicense.
+// +kubebuilder:object:root=true
+// +apireference:kgo:include
 type KongLicenseList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`

api/configuration/v1alpha1/kong_target_types.go

@@ -32,6 +32,7 @@ import (
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="Programmed",description="The Resource is Programmed on Konnect",type=string,JSONPath=`.status.conditions[?(@.type=='Programmed')].status`
 // +kubebuilder:validation:XValidation:rule="oldSelf.spec.upstreamRef == self.spec.upstreamRef", message="spec.upstreamRef is immutable"
+// +apireference:kgo:include
 type KongTarget struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -41,7 +42,9 @@ type KongTarget struct {
 	Status KongTargetStatus `json:"status,omitempty"`
 }
 
+// KongTargetSpec defines the specification of a Kong Target.
 // KongTargetSpec defines the desired state of KongTarget.
+// +apireference:kgo:include
 type KongTargetSpec struct {
 	// UpstreamRef is a reference to a KongUpstream this KongTarget is attached to.
 	UpstreamRef TargetRef `json:"upstreamRef"`
@@ -50,6 +53,7 @@ type KongTargetSpec struct {
 }
 
 // KongTargetAPISpec are the attributes of the Kong Target itself.
+// +apireference:kgo:include
 type KongTargetAPISpec struct {
 	// Target is the target address of the upstream.
 	Target string `json:"target"`
@@ -63,6 +67,7 @@ type KongTargetAPISpec struct {
 }
 
 // KongTargetStatus defines the observed state of KongTarget.
+// +apireference:kgo:include
 type KongTargetStatus struct {
 	// Konnect contains the Konnect entity status.
 	// +optional
@@ -76,9 +81,9 @@ type KongTargetStatus struct {
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 }
 
-// +kubebuilder:object:root=true
-
 // KongTargetList contains a list of Kong Targets.
+// +kubebuilder:object:root=true
+// +apireference:kgo:include
 type KongTargetList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`