Align Config API with OpenShift API conventions

andreaskaris · andreaskaris · commit 703ef1cf31c4 · 2025-10-21T15:05:36.000+02:00
Make the following changes to align with OpenShift API standards:

- Update field documentation to use lowercase descriptions per
  OpenShift style guidelines
- Add explicit field descriptions for metadata, spec, and status
  on Config type
- Remove redundant +kubebuilder:validation:Required tags (implied
  by +required marker)
- Add validation constraints (MinLength, MaxLength) to string fields
- Change HealthProbePort type from int to int32 for consistency
- Make HealthProbePort optional, with default value 8175 applied
  in controller instead of API layer
- Add enum validation for AgentSpec.LogLevel
- Use omitzero JSON tag for required Spec field
- Add MaxItems validation for status Conditions array
- Add documentation for ConfigComponentStatus constants

Signed-off-by: Andreas Karis &lt;ak.karis@gmail.com&gt;
diff --git a/apis/v1alpha1/config_types.go b/apis/v1alpha1/config_types.go
@@ -31,64 +31,84 @@ import (
 // +kubebuilder:printcolumn:name="Progressing",type="string",JSONPath=".status.conditions[?(@.type=='Progressing')].status"
 // +kubebuilder:printcolumn:name="Available",type="string",JSONPath=".status.conditions[?(@.type=='Available')].status"
 type Config struct {
-	metav1.TypeMeta   `json:",inline"`
+	metav1.TypeMeta `json:",inline"`
+	// metadata is the object's metadata.
+	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   ConfigSpec   `json:"spec,omitempty"`
+	// spec defines the desired state of the bpfman-operator.
+	// +required
+	Spec ConfigSpec `json:"spec,omitzero"`
+	// status reflects the observed state of the bpfman-operator.
+	// +optional
 	Status ConfigStatus `json:"status,omitempty"`
 }
 
-// Spec defines the desired state of the bpfman-operator.
+// spec defines the desired state of the bpfman-operator.
 type ConfigSpec struct {
-	// Agent holds the configuration for the bpfman agent.
+	// agent specifies the configuration for the bpfman agent DaemonSet.
 	// +required
-	Agent AgentSpec `json:"agent,omitempty"`
-	// Configuration holds the content of bpfman.toml.
+	Agent AgentSpec `json:"agent,omitzero"`
+	// configuration specifies the content of bpfman.toml configuration file used by the bpfman DaemonSet.
 	// +required
-	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinLength=1
-	Configuration string `json:"configuration"`
-	// Image holds the image of the bpfman DaemonSets.
+	// +kubebuilder:validation:MaxLength=65536
+	Configuration string `json:"configuration,omitempty"`
+	// image specifies the container image for the bpfman DaemonSet.
 	// +required
-	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinLength=1
-	Image string `json:"image"`
-	// LogLevel holds the log level for the bpfman-operator.
+	// +kubebuilder:validation:MaxLength=1023
+	Image string `json:"image,omitempty"`
+	// logLevel specifies the log level for the bpfman DaemonSet via the RUST_LOG environment variable.
+	// The RUST_LOG environment variable controls logging with the syntax: RUST_LOG=[target][=][level][,...].
+	// For further information, see https://docs.rs/env_logger/latest/env_logger/.
 	// +optional
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=1024
 	LogLevel string `json:"logLevel,omitempty"`
-	// Namespace holds the namespace where bpfman-operator resources shall be
-	// deployed.
+	// namespace specifies the namespace where bpfman-operator resources will be deployed.
+	// If not specified, resources will be deployed in the default bpfman namespace.
+	// +optional
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=256
 	Namespace string `json:"namespace,omitempty"`
 }
 
 // AgentSpec defines the desired state of the bpfman agent.
 type AgentSpec struct {
-	// HealthProbePort holds the health probe bind port for the bpfman agent.
+	// healthProbePort specifies the port on which the bpfman agent's health probe endpoint will listen.
+	// If unspecified, the default port will be used.
 	// +optional
-	// +kubebuilder:default=8175
 	// +kubebuilder:validation:Minimum=1
 	// +kubebuilder:validation:Maximum=65535
-	HealthProbePort int `json:"healthProbePort"`
-	// Image holds the image for the bpfman agent.
+	HealthProbePort int32 `json:"healthProbePort,omitempty"`
+	// image specifies the container image for the bpfman agent DaemonSet.
 	// +required
-	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinLength=1
-	Image string `json:"image"`
-	// LogLevel holds the log level for the bpfman agent.
+	// +kubebuilder:validation:MaxLength=1023
+	Image string `json:"image,omitempty"`
+	// logLevel specifies the verbosity of logs produced by the bpfman agent.
+	// Valid values are: "info", "debug", "trace".
 	// +optional
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=256
+	// +kubebuilder:validation:Enum=info;debug;trace
 	LogLevel string `json:"logLevel,omitempty"`
 }
 
 // status reflects the status of the bpfman-operator configuration.
 type ConfigStatus struct {
-	// conditions store the status conditions of the bpfman-operator components.
+	// conditions represents the current state conditions of the bpfman-operator and its components.
+	// +optional
 	// +patchMergeKey=type
 	// +patchStrategy=merge
 	// +listType=map
 	// +listMapKey=type
+	// +kubebuilder:validation:MaxItems=1023
 	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
 
-	// components stores the status of all components.
+	// components represents the operational status of each individual bpfman-operator component such as the deployed
+	// DaemonSets.
 	// +optional
 	Components map[string]ConfigComponentStatus `json:"components,omitempty"`
 }
@@ -101,10 +121,14 @@ type ConfigList struct {
 	Items           []Config `json:"items"`
 }
 
+// ConfigComponentStatus holds the status of a single Config component.
 type ConfigComponentStatus string
 
 const (
-	ConfigStatusUnknown     ConfigComponentStatus = "Unknown"
+	// ConfigStatusUnknown indicates the component state cannot be determined.
+	ConfigStatusUnknown ConfigComponentStatus = "Unknown"
+	// ConfigStatusProgressing indicates the component is being updated or reconciled.
 	ConfigStatusProgressing ConfigComponentStatus = "Progressing"
-	ConfigStatusReady       ConfigComponentStatus = "Ready"
+	// ConfigStatusReady indicates the component is fully operational and ready.
+	ConfigStatusReady ConfigComponentStatus = "Ready"
 )
diff --git a/bundle/manifests/bpfman-operator.clusterserviceversion.yaml b/bundle/manifests/bpfman-operator.clusterserviceversion.yaml
@@ -1012,7 +1012,7 @@ metadata:
     capabilities: Basic Install
     categories: OpenShift Optional
     containerImage: quay.io/bpfman/bpfman-operator:latest
-    createdAt: "2025-10-08T15:10:52Z"
+    createdAt: "2025-10-21T13:05:28Z"
     description: The bpfman Operator is designed to manage eBPF programs for applications.
     features.operators.openshift.io/cnf: "false"
     features.operators.openshift.io/cni: "false"
diff --git a/bundle/manifests/bpfman.io_configs.yaml b/bundle/manifests/bpfman.io_configs.yaml
@@ -47,59 +47,82 @@ spec:
           metadata:
             type: object
           spec:
-            description: Spec defines the desired state of the bpfman-operator.
+            description: spec defines the desired state of the bpfman-operator.
             properties:
               agent:
-                description: Agent holds the configuration for the bpfman agent.
+                description: agent specifies the configuration for the bpfman agent
+                  DaemonSet.
                 properties:
                   healthProbePort:
-                    default: 8175
-                    description: HealthProbePort holds the health probe bind port
-                      for the bpfman agent.
+                    description: |-
+                      healthProbePort specifies the port on which the bpfman agent's health probe endpoint will listen.
+                      If unspecified, the default port will be used.
+                    format: int32
                     maximum: 65535
                     minimum: 1
                     type: integer
                   image:
-                    description: Image holds the image for the bpfman agent.
+                    description: image specifies the container image for the bpfman
+                      agent DaemonSet.
+                    maxLength: 1023
                     minLength: 1
                     type: string
                   logLevel:
-                    description: LogLevel holds the log level for the bpfman agent.
+                    description: |-
+                      logLevel specifies the verbosity of logs produced by the bpfman agent.
+                      Valid values are: "info", "debug", "trace".
+                    enum:
+                    - info
+                    - debug
+                    - trace
+                    maxLength: 256
+                    minLength: 1
                     type: string
-                required:
-                - image
                 type: object
               configuration:
-                description: Configuration holds the content of bpfman.toml.
+                description: configuration specifies the content of bpfman.toml configuration
+                  file used by the bpfman DaemonSet.
+                maxLength: 65536
                 minLength: 1
                 type: string
               image:
-                description: Image holds the image of the bpfman DaemonSets.
+                description: image specifies the container image for the bpfman DaemonSet.
+                maxLength: 1023
                 minLength: 1
                 type: string
               logLevel:
-                description: LogLevel holds the log level for the bpfman-operator.
+                description: |-
+                  logLevel specifies the log level for the bpfman DaemonSet via the RUST_LOG environment variable.
+                  The RUST_LOG environment variable controls logging with the syntax: RUST_LOG=[target][=][level][,...].
+                  For further information, see https://docs.rs/env_logger/latest/env_logger/.
+                maxLength: 1024
+                minLength: 1
                 type: string
               namespace:
                 description: |-
-                  Namespace holds the namespace where bpfman-operator resources shall be
-                  deployed.
+                  namespace specifies the namespace where bpfman-operator resources will be deployed.
+                  If not specified, resources will be deployed in the default bpfman namespace.
+                maxLength: 256
+                minLength: 1
                 type: string
             required:
-            - configuration
-            - image
+            - agent
             type: object
           status:
-            description: status reflects the status of the bpfman-operator configuration.
+            description: status reflects the observed state of the bpfman-operator.
             properties:
               components:
                 additionalProperties:
+                  description: ConfigComponentStatus holds the status of a single
+                    Config component.
                   type: string
-                description: components stores the status of all components.
+                description: |-
+                  components represents the operational status of each individual bpfman-operator component such as the deployed
+                  DaemonSets.
                 type: object
               conditions:
-                description: conditions store the status conditions of the bpfman-operator
-                  components.
+                description: conditions represents the current state conditions of
+                  the bpfman-operator and its components.
                 items:
                   description: "Condition contains details for one aspect of the current
                     state of this API Resource.\n---\nThis struct is intended for
@@ -167,11 +190,14 @@ spec:
                   - status
                   - type
                   type: object
+                maxItems: 1023
                 type: array
                 x-kubernetes-list-map-keys:
                 - type
                 x-kubernetes-list-type: map
             type: object
+        required:
+        - spec
         type: object
     served: true
     storage: true
diff --git a/config/crd/bases/bpfman.io_configs.yaml b/config/crd/bases/bpfman.io_configs.yaml
@@ -47,59 +47,82 @@ spec:
           metadata:
             type: object
           spec:
-            description: Spec defines the desired state of the bpfman-operator.
+            description: spec defines the desired state of the bpfman-operator.
             properties:
               agent:
-                description: Agent holds the configuration for the bpfman agent.
+                description: agent specifies the configuration for the bpfman agent
+                  DaemonSet.
                 properties:
                   healthProbePort:
-                    default: 8175
-                    description: HealthProbePort holds the health probe bind port
-                      for the bpfman agent.
+                    description: |-
+                      healthProbePort specifies the port on which the bpfman agent's health probe endpoint will listen.
+                      If unspecified, the default port will be used.
+                    format: int32
                     maximum: 65535
                     minimum: 1
                     type: integer
                   image:
-                    description: Image holds the image for the bpfman agent.
+                    description: image specifies the container image for the bpfman
+                      agent DaemonSet.
+                    maxLength: 1023
                     minLength: 1
                     type: string
                   logLevel:
-                    description: LogLevel holds the log level for the bpfman agent.
+                    description: |-
+                      logLevel specifies the verbosity of logs produced by the bpfman agent.
+                      Valid values are: "info", "debug", "trace".
+                    enum:
+                    - info
+                    - debug
+                    - trace
+                    maxLength: 256
+                    minLength: 1
                     type: string
-                required:
-                - image
                 type: object
               configuration:
-                description: Configuration holds the content of bpfman.toml.
+                description: configuration specifies the content of bpfman.toml configuration
+                  file used by the bpfman DaemonSet.
+                maxLength: 65536
                 minLength: 1
                 type: string
               image:
-                description: Image holds the image of the bpfman DaemonSets.
+                description: image specifies the container image for the bpfman DaemonSet.
+                maxLength: 1023
                 minLength: 1
                 type: string
               logLevel:
-                description: LogLevel holds the log level for the bpfman-operator.
+                description: |-
+                  logLevel specifies the log level for the bpfman DaemonSet via the RUST_LOG environment variable.
+                  The RUST_LOG environment variable controls logging with the syntax: RUST_LOG=[target][=][level][,...].
+                  For further information, see https://docs.rs/env_logger/latest/env_logger/.
+                maxLength: 1024
+                minLength: 1
                 type: string
               namespace:
                 description: |-
-                  Namespace holds the namespace where bpfman-operator resources shall be
-                  deployed.
+                  namespace specifies the namespace where bpfman-operator resources will be deployed.
+                  If not specified, resources will be deployed in the default bpfman namespace.
+                maxLength: 256
+                minLength: 1
                 type: string
             required:
-            - configuration
-            - image
+            - agent
             type: object
           status:
-            description: status reflects the status of the bpfman-operator configuration.
+            description: status reflects the observed state of the bpfman-operator.
             properties:
               components:
                 additionalProperties:
+                  description: ConfigComponentStatus holds the status of a single
+                    Config component.
                   type: string
-                description: components stores the status of all components.
+                description: |-
+                  components represents the operational status of each individual bpfman-operator component such as the deployed
+                  DaemonSets.
                 type: object
               conditions:
-                description: conditions store the status conditions of the bpfman-operator
-                  components.
+                description: conditions represents the current state conditions of
+                  the bpfman-operator and its components.
                 items:
                   description: "Condition contains details for one aspect of the current
                     state of this API Resource.\n---\nThis struct is intended for
@@ -167,11 +190,14 @@ spec:
                   - status
                   - type
                   type: object
+                maxItems: 1023
                 type: array
                 x-kubernetes-list-map-keys:
                 - type
                 x-kubernetes-list-type: map
             type: object
+        required:
+        - spec
         type: object
     served: true
     storage: true
diff --git a/controllers/bpfman-operator/config.go b/controllers/bpfman-operator/config.go
@@ -614,9 +614,12 @@ func (r *BpfmanConfigReconciler) handleDeletion(ctx context.Context, config *v1a
 	return ctrl.Result{}, nil
 }
 
-func healthProbeAddress(healthProbePort int) string {
-	if healthProbePort <= 0 || healthProbePort > 65535 {
+func healthProbeAddress(healthProbePort int32) string {
+	if healthProbePort < 0 || healthProbePort > 65535 {
 		return ""
 	}
+	if healthProbePort == 0 {
+		healthProbePort = internal.DefaultHealthProbePort
+	}
 	return fmt.Sprintf(":%d", healthProbePort)
 }
diff --git a/internal/constants.go b/internal/constants.go
@@ -48,6 +48,7 @@ const (
 	BpfmanLogLevel                = "bpfman.log.level"
 	BpfmanAgentLogLevel           = "bpfman.agent.log.level"
 	BpfmanAgentHealthProbeAddress = "bpfman.agent.healthprobeaddr"
+	DefaultHealthProbePort        = 8175
 	APIPrefix                     = "bpfman.io"
 )
 

Original file line number	Diff line number	Diff line change
`@@ -614,9 +614,12 @@ func (r BpfmanConfigReconciler) handleDeletion(ctx context.Context, config v1a`
`614`	`614`	`return ctrl.Result{}, nil`
`615`	`615`	`}`
`616`	`616`
`617`		`-func healthProbeAddress(healthProbePort int) string {`
`618`		`- if healthProbePort <= 0 \|\| healthProbePort > 65535 {`
	`617`	`+func healthProbeAddress(healthProbePort int32) string {`
	`618`	`+ if healthProbePort < 0 \|\| healthProbePort > 65535 {`
`619`	`619`	`return ""`
`620`	`620`	`}`
	`621`	`+ if healthProbePort == 0 {`
	`622`	`+ healthProbePort = internal.DefaultHealthProbePort`
	`623`	`+ }`
`621`	`624`	`return fmt.Sprintf(":%d", healthProbePort)`
`622`	`625`	`}`
Original file line number	Diff line number	Diff line change
`@@ -48,6 +48,7 @@ const (`
`48`	`48`	`BpfmanLogLevel = "bpfman.log.level"`
`49`	`49`	`BpfmanAgentLogLevel = "bpfman.agent.log.level"`
`50`	`50`	`BpfmanAgentHealthProbeAddress = "bpfman.agent.healthprobeaddr"`
	`51`	`+ DefaultHealthProbePort = 8175`
`51`	`52`	`APIPrefix = "bpfman.io"`
`52`	`53`	`)`
`53`	`54`