Reuse sdk-konnect-go types in CRD types definitions

[pmalek]

Problem statement

This project uses sdk-konnect-go for some of the underlying types in CRDs.

Some of definitions of those types cannot be reused as fields generated from OpenAPI spec do not have much sense in Kubernetes world. For example ServiceInput, contains

// Array of `CA Certificate` object UUIDs that are used to build the trust store while verifying upstream server's TLS certificate. If set to `null` when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted).
CaCertificates []string `json:"ca_certificates,omitempty"`

field which can be used to set Service's CA certificates via a UUID slice. This wouldn't work well in Kubernetes as users are expecting in cluster references. So instead of the above we'd want to make this field an array of in-cluster references to CACertificate objects.

Without this being solved, we have to use a copy paste version of those types with stripped fields, i.e.

kubernetes-configuration/api/configuration/v1alpha1/kongservice_types.go

Lines 65 to 109 in a721d9e

	// KongServiceAPISpec defines specification of a Kong Service.
	// +apireference:kgo:include
	type KongServiceAPISpec struct {
	// TODO(pmalek): client certificate implement ref
	// TODO(pmalek): ca_certificates implement ref
	// TODO(pmalek): field below are basically copy pasted from sdkkonnectcomp.CreateService
	// The reason for this is that Service creation request contains a Konnect ID
	// reference to a client certificate. This is not what we want to expose to the user.
	// Instead we want to expose a namespaced reference to a client certificate.
	// Even if the cross namespace reference is not planned, the structured reference
	// type is preferred because it allows for easier extension in the future.
	//
	// sdkkonnectcomp.ServiceInput`json:",inline"`
	// Helper field to set `protocol`, `host`, `port` and `path` using a URL. This field is write-only and is not returned in responses.
	URL *string `json:"url,omitempty"`
	// The timeout in milliseconds for establishing a connection to the upstream server.
	ConnectTimeout *int64 `json:"connect_timeout,omitempty"`
	// Whether the Service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). Default: `true`.
	Enabled *bool `json:"enabled,omitempty"`
	// The host of the upstream server. Note that the host value is case sensitive.
	// +kubebuilder:validation:Required
	Host string `json:"host"`
	// The Service name.
	Name *string `json:"name,omitempty"`
	// The path to be used in requests to the upstream server.
	Path *string `json:"path,omitempty"`
	// The upstream server port.
	Port int64 `json:"port,omitempty"`
	// The protocol used to communicate with the upstream.
	Protocol sdkkonnectcomp.Protocol `json:"protocol,omitempty"`
	// The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.
	ReadTimeout *int64 `json:"read_timeout,omitempty"`
	// The number of retries to execute upon failure to proxy.
	Retries *int64 `json:"retries,omitempty"`
	// An optional set of strings associated with the Service for grouping and filtering.
	Tags common.Tags `json:"tags,omitempty"`
	// Whether to enable verification of upstream server TLS certificate. If set to `null`, then the Nginx default is respected.
	TLSVerify *bool `json:"tls_verify,omitempty"`
	// Maximum depth of chain while verifying Upstream server's TLS certificate. If set to `null`, then the Nginx default is respected.
	TLSVerifyDepth *int64 `json:"tls_verify_depth,omitempty"`
	// The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.
	WriteTimeout *int64 `json:"write_timeout,omitempty"`
	}

Possible solutions

• Add a post generation step which would change the struct types into interfaces, and then generate:

  • k8s types with stripped fields
  • implement the interface returning ServiceInput on both of the original and k8s flavored type (the latter would leave these fields empty basically)
  • cons?
    • inconsistent API unless we do this for all types (might be a lot of work)

• Add a post generation "copy paste" step that would provide a k8s flavored functions which would basically do

  func (s *Services) CreateServiceK8s(ctx context.Context, controlPlaneID string, service components.ServiceInputK8s, opts ...operations.Option) (*operations.CreateServiceResponse, error) {
      // TODO transform the requested service input
      si := ...
      return s.CreateService(ctx , controlPlaneID, si, opts...)
  }
  

  • cons?
    • transforming input types feels like work that we do in operator today which will probably require some manual maintenance anyway, e.g. https://github.com/Kong/gateway-operator/blob/8c7fbd40e945bb95c5247288131eac3df9cc7113/controller/konnect/ops/ops_kongroute.go#L86-L114

Anything else

Related slack thread: https://kongstrong.slack.com/archives/C011RQPHDC7/p1731951022019939?thread_ts=1731624171.431279&cid=C011RQPHDC7