Add NginxProxy CRD (#1815)

Problem: Users want to be able to configure global Gateway  settings, such as the Otel tracing exporter, for all Gateways in a Class.

Solution: Add the NginxProxy CRD, which provides a way to configure these settings.
Note: this PR contains the CRD only. A subsequent PR will add the implementation.

Author: sjberman

apis/v1alpha1/clientsettingspolicy_types.go

@@ -114,13 +114,6 @@ type ClientKeepAliveTimeout struct {
 	Header *Duration `json:"header,omitempty"`
 }
 
-// Duration is a string value representing a duration in time.
-// Duration can be specified in milliseconds (ms) or seconds (s) A value without a suffix is seconds.
-// Examples: 120s, 50ms.
-//
-// +kubebuilder:validation:Pattern=`^\d{1,4}(ms|s)?$`
-type Duration string
-
 // Size is a string value representing a size. Size can be specified in bytes, kilobytes (k), megabytes (m),
 // or gigabytes (g).
 // Examples: 1024, 8k, 1m.

apis/v1alpha1/nginxproxy_types.go

@@ -0,0 +1,107 @@
+package v1alpha1
+
+import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+// +kubebuilder:object:root=true
+// +kubebuilder:storageversion
+// +kubebuilder:resource:categories=nginx-gateway-fabric,scope=Cluster
+// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
+
+// NginxProxy is a configuration object that is attached to a GatewayClass parametersRef. It provides a way
+// to configure global settings for all Gateways defined from the GatewayClass.
+type NginxProxy struct { //nolint:govet // standard field alignment, don't change it
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	// Spec defines the desired state of the NginxProxy.
+	Spec NginxProxySpec `json:"spec"`
+}
+
+// +kubebuilder:object:root=true
+
+// NginxProxyList contains a list of NginxProxies.
+type NginxProxyList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []NginxProxy `json:"items"`
+}
+
+// NginxProxySpec defines the desired state of the NginxProxy.
+type NginxProxySpec struct {
+	// Telemetry specifies the OpenTelemetry configuration.
+	//
+	// +optional
+	Telemetry *Telemetry `json:"telemetry,omitempty"`
+}
+
+// Telemetry specifies the OpenTelemetry configuration.
+type Telemetry struct {
+	// Exporter specifies OpenTelemetry export parameters.
+	//
+	// +optional
+	Exporter *TelemetryExporter `json:"exporter,omitempty"`
+
+	// ServiceName is the "service.name" attribute of the OpenTelemetry resource.
+	// Default is 'ngf:<gateway-namespace>:<gateway-name>'. If a value is provided by the user,
+	// then the default becomes a prefix to that value.
+	//
+	// +optional
+	// +kubebuilder:validation:MaxLength=127
+	// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9_-]+$`
+	ServiceName *string `json:"serviceName,omitempty"`
+
+	// SpanAttributes are custom key/value attributes that are added to each span.
+	//
+	// +optional
+	// +listType=map
+	// +listMapKey=key
+	// +kubebuilder:validation:MaxItems=64
+	SpanAttributes []SpanAttribute `json:"spanAttributes,omitempty"`
+}
+
+// TelemetryExporter specifies OpenTelemetry export parameters.
+type TelemetryExporter struct {
+	// Interval is the maximum interval between two exports.
+	// Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_exporter
+	//
+	// +optional
+	Interval *Duration `json:"interval,omitempty"`
+
+	// BatchSize is the maximum number of spans to be sent in one batch per worker.
+	// Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_exporter
+	//
+	// +optional
+	// +kubebuilder:validation:Minimum=0
+	BatchSize *int32 `json:"batchSize,omitempty"`
+
+	// BatchCount is the number of pending batches per worker, spans exceeding the limit are dropped.
+	// Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_exporter
+	//
+	// +optional
+	// +kubebuilder:validation:Minimum=0
+	BatchCount *int32 `json:"batchCount,omitempty"`
+
+	// Endpoint is the address of OTLP/gRPC endpoint that will accept telemetry data.
+	// Format: alphanumeric hostname with optional http scheme and optional port.
+	//
+	//nolint:lll
+	// +kubebuilder:validation:Pattern=`^(?:http?:\/\/)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*(?::\d{1,5})?$`
+	Endpoint string `json:"endpoint"`
+}
+
+// SpanAttribute is a key value pair to be added to a tracing span.
+type SpanAttribute struct {
+	// Key is the key for a span attribute.
+	//
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=255
+	// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9_-]+$`
+	Key string `json:"key"`
+
+	// Value is the value for a span attribute.
+	//
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=255
+	// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9_-]+$`
+	Value string `json:"value"`
+}

apis/v1alpha1/register.go

@@ -34,6 +34,8 @@ func addKnownTypes(scheme *runtime.Scheme) error {
 	scheme.AddKnownTypes(SchemeGroupVersion,
 		&NginxGateway{},
 		&NginxGatewayList{},
+		&NginxProxy{},
+		&NginxProxyList{},
 		&ClientSettingsPolicy{},
 		&ClientSettingsPolicyList{},
 	)

apis/v1alpha1/shared_types.go

@@ -0,0 +1,8 @@
+package v1alpha1
+
+// Duration is a string value representing a duration in time.
+// Duration can be specified in milliseconds (ms) or seconds (s) A value without a suffix is seconds.
+// Examples: 120s, 50ms.
+//
+// +kubebuilder:validation:Pattern=`^\d{1,4}(ms|s)?$`
+type Duration string