Skip to content

Commit 6f44f20

Browse files
andreaskarisandreaskaris
committed
Align APIs with OpenShift API conventions for optional fields
This commit updates the v1alpha1 API types to follow OpenShift API standards by: - Adding `omitempty` JSON tags to all optional and status fields - Using `omitzero` for required spec fields to ensure they're validated - Adding field-level documentation comments for metadata, spec, and status - Adding validation constraints (MaxItems, MinLength, MaxLength) to arrays and strings - Setting proper list types (atomic, map) for arrays - Reordering Status fields to place Conditions first per convention - Improving consistency in field documentation across all types Signed-off-by: Andreas Karis <[email protected]>
1 parent 1a3b0a5 commit 6f44f20

28 files changed

+1478
-745
lines changed

‎apis/v1alpha1/bpf_application_state_types.go‎

Lines changed: 31 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ type BpfApplicationProgramState struct {
5050
// +unionDiscriminator
5151
// +required
5252
// +kubebuilder:validation:Enum:="XDP";"TC";"TCX";"UProbe";"URetProbe"
53-
Type EBPFProgType `json:"type"`
53+
Type EBPFProgType `json:"type,omitempty"`
5454

5555
// xdp contains the attachment data for an XDP program when type is set to XDP.
5656
// +unionMember
@@ -81,15 +81,32 @@ type BpfApplicationProgramState struct {
8181
}
8282

8383
type BpfApplicationStateStatus struct {
84-
// UpdateCount tracks the number of times the BpfApplicationState object has
84+
// conditions contains the summary state of the BpfApplication for the given
85+
// Kubernetes node. If one or more programs failed to load or attach to the
86+
// designated attachment point, the condition will report the error. If more
87+
// than one error has occurred, condition will contain the first error
88+
// encountered.
89+
// +patchMergeKey=type
90+
// +patchStrategy=merge
91+
// +listType=map
92+
// +listMapKey=type
93+
// +optional
94+
// +kubebuilder:validation:MaxItems=1023
95+
Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
96+
// updateCount tracks the number of times the BpfApplicationState object has
8597
// been updated. The bpfman agent initializes it to 1 when it creates the
8698
// object, and then increments it before each subsequent update. It serves
8799
// as a lightweight sequence number to verify that the API server is serving
88100
// the most recent version of the object before beginning a new Reconcile
89101
// operation.
90-
UpdateCount int64 `json:"updateCount"`
91-
// node is the name of the Kubernets node for this BpfApplicationState.
92-
Node string `json:"node"`
102+
// +kubebuilder:validation:Minimum=1
103+
// +optional
104+
UpdateCount int64 `json:"updateCount,omitempty"`
105+
// node is the name of the Kubernetes node for this BpfApplicationState.
106+
// +kubebuilder:validation:MinLength=1
107+
// +kubebuilder:validation:MaxLength=253
108+
// +optional
109+
Node string `json:"node,omitempty"`
93110
// appLoadStatus reflects the status of loading the eBPF application on the
94111
// given node.
95112
//
@@ -111,21 +128,15 @@ type BpfApplicationStateStatus struct {
111128
//
112129
// UnloadError is returned if one or more programs encountered an error when
113130
// being unloaded.
114-
AppLoadStatus AppLoadStatus `json:"appLoadStatus"`
131+
// +optional
132+
AppLoadStatus AppLoadStatus `json:"appLoadStatus,omitempty"`
115133
// programs is a list of eBPF programs contained in the parent BpfApplication
116134
// instance. Each entry in the list contains the derived program attributes as
117135
// well as the attach status for each program on the given Kubernetes node.
136+
// +kubebuilder:validation:MaxItems=1023
137+
// +listType=atomic
138+
// +optional
118139
Programs []BpfApplicationProgramState `json:"programs,omitempty"`
119-
// conditions contains the summary state of the BpfApplication for the given
120-
// Kubernetes node. If one or more programs failed to load or attach to the
121-
// designated attachment point, the condition will report the error. If more
122-
// than one error has occurred, condition will contain the first error
123-
// encountered.
124-
// +patchMergeKey=type
125-
// +patchStrategy=merge
126-
// +listType=map
127-
// +listMapKey=type
128-
Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
129140
}
130141

131142
// +genclient
@@ -141,13 +152,16 @@ type BpfApplicationStateStatus struct {
141152
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[0].reason`
142153
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
143154
type BpfApplicationState struct {
144-
metav1.TypeMeta `json:",inline"`
155+
metav1.TypeMeta `json:",inline"`
156+
// metadata is the object's metadata.
157+
// +optional
145158
metav1.ObjectMeta `json:"metadata,omitempty"`
146159

147160
// status reflects the status of a BpfApplication instance for the given node.
148161
// appLoadStatus and conditions provide an overall status for the given node,
149162
// while each item in the programs list provides a per eBPF program status for
150163
// the given node.
164+
// +optional
151165
Status BpfApplicationStateStatus `json:"status,omitempty"`
152166
}
153167

‎apis/v1alpha1/bpf_application_types.go‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,12 @@ type BpfApplicationProgram struct {
3131
// name is a required field and is the name of the function that is the entry
3232
// point for the eBPF program. name must not be an empty string, must not
3333
// exceed 64 characters in length, must start with alpha characters and must
34-
// only contain alphanumeric characters.
34+
// only contain alphanumeric characters and underscores.
3535
// +required
3636
// +kubebuilder:validation:Pattern="^[a-zA-Z][a-zA-Z0-9_]+."
3737
// +kubebuilder:validation:MinLength=1
3838
// +kubebuilder:validation:MaxLength=64
39-
Name string `json:"name"`
39+
Name string `json:"name,omitempty"`
4040

4141
// type is a required field used to specify the type of the eBPF program.
4242
//
@@ -73,7 +73,7 @@ type BpfApplicationProgram struct {
7373
// +unionDiscriminator
7474
// +required
7575
// +kubebuilder:validation:Enum:="XDP";"TC";"TCX";"UProbe";"URetProbe"
76-
Type EBPFProgType `json:"type"`
76+
Type EBPFProgType `json:"type,omitempty"`
7777

7878
// xdp is an optional field, but required when the type field is set to XDP.
7979
// xdp defines the desired state of the application's XDP programs. XDP program
@@ -163,7 +163,9 @@ type BpfApplicationSpec struct {
163163
// programs in the list to be reloaded, which could be temporarily service
164164
// effecting. For this reason, modifying the list is currently not allowed.
165165
// +required
166-
// +kubebuilder:validation:MinItems:=1
166+
// +kubebuilder:validation:MinItems=1
167+
// +kubebuilder:validation:MaxItems=1023
168+
// +listType=atomic
167169
Programs []BpfApplicationProgram `json:"programs,omitempty"`
168170
}
169171

@@ -185,11 +187,17 @@ type BpfApplicationSpec struct {
185187
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[0].reason`
186188
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
187189
type BpfApplication struct {
188-
metav1.TypeMeta `json:",inline"`
190+
metav1.TypeMeta `json:",inline"`
191+
// metadata is the object's metadata.
192+
// +optional
189193
metav1.ObjectMeta `json:"metadata,omitempty"`
190194

191-
Spec BpfApplicationSpec `json:"spec,omitempty"`
192-
Status BpfAppStatus `json:"status,omitempty"`
195+
// spec defines the desired state of the BpfApplication.
196+
// +required
197+
Spec BpfApplicationSpec `json:"spec,omitzero"`
198+
// status reflects the observed state of the BpfApplication.
199+
// +optional
200+
Status BpfAppStatus `json:"status,omitempty"`
193201
}
194202

195203
// +kubebuilder:object:root=true

‎apis/v1alpha1/cluster_bpf_application_state_types.go‎

Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ type ClBpfApplicationProgramState struct {
7171
// +unionDiscriminator
7272
// +required
7373
// +kubebuilder:validation:Enum:="FEntry";"FExit";"KProbe";"KRetProbe";"TC";"TCX";"TracePoint";"UProbe";"URetProbe";"XDP"
74-
Type EBPFProgType `json:"type"`
74+
Type EBPFProgType `json:"type,omitempty"`
7575

7676
// xdp contains the attachment data for an XDP program when type is set to XDP.
7777
// +unionMember
@@ -132,15 +132,32 @@ type ClBpfApplicationProgramState struct {
132132
}
133133

134134
type ClBpfApplicationStateStatus struct {
135-
// UpdateCount tracks the number of times the BpfApplicationState object has
135+
// conditions contains the summary state of the ClusterBpfApplication for the
136+
// given Kubernetes node. If one or more programs failed to load or attach to
137+
// the designated attachment point, the condition will report the error. If
138+
// more than one error has occurred, condition will contain the first error
139+
// encountered.
140+
// +patchMergeKey=type
141+
// +patchStrategy=merge
142+
// +listType=map
143+
// +listMapKey=type
144+
// +optional
145+
// +kubebuilder:validation:MaxItems=1023
146+
Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
147+
// updateCount tracks the number of times the BpfApplicationState object has
136148
// been updated. The bpfman agent initializes it to 1 when it creates the
137149
// object, and then increments it before each subsequent update. It serves
138150
// as a lightweight sequence number to verify that the API server is serving
139151
// the most recent version of the object before beginning a new Reconcile
140152
// operation.
141-
UpdateCount int64 `json:"updateCount"`
153+
// +kubebuilder:validation:Minimum=1
154+
// +optional
155+
UpdateCount int64 `json:"updateCount,omitempty"`
142156
// node is the name of the Kubernetes node for this ClusterBpfApplicationState.
143-
Node string `json:"node"`
157+
// +kubebuilder:validation:MinLength=1
158+
// +kubebuilder:validation:MaxLength=253
159+
// +optional
160+
Node string `json:"node,omitempty"`
144161
// appLoadStatus reflects the status of loading the eBPF application on the
145162
// given node.
146163
//
@@ -160,22 +177,16 @@ type ClBpfApplicationStateStatus struct {
160177
//
161178
// UnloadError is returned if one or more programs encountered an error when
162179
// being unloaded.
163-
AppLoadStatus AppLoadStatus `json:"appLoadStatus"`
180+
// +optional
181+
AppLoadStatus AppLoadStatus `json:"appLoadStatus,omitempty"`
164182
// programs is a list of eBPF programs contained in the parent
165183
// ClusterBpfApplication instance. Each entry in the list contains the derived
166184
// program attributes as well as the attach status for each program on the
167185
// given Kubernetes node.
186+
// +kubebuilder:validation:MaxItems=1023
187+
// +listType=atomic
188+
// +optional
168189
Programs []ClBpfApplicationProgramState `json:"programs,omitempty"`
169-
// conditions contains the summary state of the ClusterBpfApplication for the
170-
// given Kubernetes node. If one or more programs failed to load or attach to
171-
// the designated attachment point, the condition will report the error. If
172-
// more than one error has occurred, condition will contain the first error
173-
// encountered.
174-
// +patchMergeKey=type
175-
// +patchStrategy=merge
176-
// +listType=map
177-
// +listMapKey=type
178-
Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
179190
}
180191

181192
// +genclient
@@ -192,13 +203,16 @@ type ClBpfApplicationStateStatus struct {
192203
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[0].reason`
193204
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
194205
type ClusterBpfApplicationState struct {
195-
metav1.TypeMeta `json:",inline"`
206+
metav1.TypeMeta `json:",inline"`
207+
// metadata is the object's metadata.
208+
// +optional
196209
metav1.ObjectMeta `json:"metadata,omitempty"`
197210

198211
// status reflects the status of a ClusterBpfApplication instance for the given
199212
// node. appLoadStatus and conditions provide an overall status for the given
200213
// node, while each item in the programs list provides a per eBPF program
201214
// status for the given node.
215+
// +optional
202216
Status ClBpfApplicationStateStatus `json:"status,omitempty"`
203217
}
204218

‎apis/v1alpha1/cluster_bpf_application_types.go‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -77,12 +77,12 @@ type ClBpfApplicationProgram struct {
7777
// name is a required field and is the name of the function that is the entry
7878
// point for the eBPF program. name must not be an empty string, must not
7979
// exceed 64 characters in length, must start with alpha characters and must
80-
// only contain alphanumeric characters.
80+
// only contain alphanumeric characters and underscores.
8181
// +required
8282
// +kubebuilder:validation:Pattern="^[a-zA-Z][a-zA-Z0-9_]+."
8383
// +kubebuilder:validation:MinLength=1
8484
// +kubebuilder:validation:MaxLength=64
85-
Name string `json:"name"`
85+
Name string `json:"name,omitempty"`
8686

8787
// type is a required field used to specify the type of the eBPF program.
8888
//
@@ -143,7 +143,7 @@ type ClBpfApplicationProgram struct {
143143
// +unionDiscriminator
144144
// +required
145145
// +kubebuilder:validation:Enum:="XDP";"TC";"TCX";"FEntry";"FExit";"KProbe";"KRetProbe";"UProbe";"URetProbe";"TracePoint"
146-
Type EBPFProgType `json:"type"`
146+
Type EBPFProgType `json:"type,omitempty"`
147147

148148
// xdp is an optional field, but required when the type field is set to XDP.
149149
// xdp defines the desired state of the application's XDP programs. XDP program
@@ -293,7 +293,9 @@ type ClBpfApplicationSpec struct {
293293
// effecting. For this reason, modifying the list is currently not allowed.
294294
// +required
295295
// +kubebuilder:validation:MinItems:=1
296-
Programs []ClBpfApplicationProgram `json:"programs"`
296+
// +kubebuilder:validation:MaxItems=1023
297+
// +listType=atomic
298+
Programs []ClBpfApplicationProgram `json:"programs,omitempty"`
297299
}
298300

299301
// +genclient
@@ -316,11 +318,17 @@ type ClBpfApplicationSpec struct {
316318
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[0].reason`
317319
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
318320
type ClusterBpfApplication struct {
319-
metav1.TypeMeta `json:",inline"`
321+
metav1.TypeMeta `json:",inline"`
322+
// metadata is the standard object's metadata.
323+
// +optional
320324
metav1.ObjectMeta `json:"metadata,omitempty"`
321325

322-
Spec ClBpfApplicationSpec `json:"spec,omitempty"`
323-
Status BpfAppStatus `json:"status,omitempty"`
326+
// spec defines the desired state of the BpfApplication.
327+
// +required
328+
Spec ClBpfApplicationSpec `json:"spec,omitzero"`
329+
// status reflects the observed state of the BpfApplication.
330+
// +optional
331+
Status BpfAppStatus `json:"status,omitempty"`
324332
}
325333

326334
// +kubebuilder:object:root=true

‎apis/v1alpha1/cluster_fentry_program_types.go‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ type ClFentryProgramInfo struct {
3030
// the program, add an entry to links with mode set to Attach. To detach it,
3131
// remove the entry from links.
3232
// +optional
33+
// +listType=atomic
3334
// +kubebuilder:validation:MaxItems=1
3435
Links []ClFentryAttachInfo `json:"links,omitempty"`
3536
}
@@ -39,11 +40,11 @@ type ClFentryLoadInfo struct {
3940
// function to attach the FEntry program. function must not be an empty string,
4041
// must not exceed 64 characters in length, must start with alpha characters
4142
// and must only contain alphanumeric characters.
42-
// +required
43+
// +optional
4344
// +kubebuilder:validation:Pattern="^[a-zA-Z][a-zA-Z0-9_]+."
4445
// +kubebuilder:validation:MinLength=1
4546
// +kubebuilder:validation:MaxLength=64
46-
Function string `json:"function"`
47+
Function string `json:"function,omitempty"`
4748
}
4849

4950
type AttachTypeAttach string
@@ -57,7 +58,7 @@ type ClFentryAttachInfo struct {
5758
// attempt to be attached. To detach the FEntry program, remove the link entry.
5859
// +required
5960
// +kubebuilder:validation:Enum=Attach;
60-
Mode AttachTypeAttach `json:"mode"`
61+
Mode AttachTypeAttach `json:"mode,omitempty"`
6162
}
6263

6364
type ClFentryProgramInfoState struct {
@@ -68,6 +69,7 @@ type ClFentryProgramInfoState struct {
6869
// successful or not on this node, a linkId, which is the kernel ID for the
6970
// link if successfully attached, and other attachment specific data.
7071
// +optional
72+
// +listType=atomic
7173
// +kubebuilder:validation:MaxItems=1
7274
Links []ClFentryAttachInfoState `json:"links,omitempty"`
7375
}

‎apis/v1alpha1/cluster_fexit_program_types.go‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,28 +30,30 @@ type ClFexitProgramInfo struct {
3030
// the program, add an entry to links with mode set to Attach. To detach it,
3131
// remove the entry from links.
3232
// +optional
33+
// +listType=atomic
3334
// +kubebuilder:validation:MaxItems=1
3435
Links []ClFexitAttachInfo `json:"links,omitempty"`
3536
}
3637

3738
type ClFexitLoadInfo struct {
3839
// function is a required field and specifies the name of the Linux kernel
3940
// function to attach the FExit program. function must not be an empty string,
40-
// must not exceed 64 characters in length, must start with alpha characters
41-
// and must only contain alphanumeric characters.
42-
// +required
41+
// must be between 1 and 64 characters in length, must start with alpha
42+
// characters and must only contain alphanumeric characters and underscores.
43+
// The pattern ^[a-zA-Z][a-zA-Z0-9_]+. is enforced.
44+
// +optional
4345
// +kubebuilder:validation:Pattern="^[a-zA-Z][a-zA-Z0-9_]+."
4446
// +kubebuilder:validation:MinLength=1
4547
// +kubebuilder:validation:MaxLength=64
46-
Function string `json:"function"`
48+
Function string `json:"function,omitempty"`
4749
}
4850

4951
type ClFexitAttachInfo struct {
5052
// mode is a required field. When set to Attach, the FExit program will
5153
// attempt to be attached. To detach the FExit program, remove the link entry.
5254
// +required
5355
// +kubebuilder:validation:Enum=Attach;
54-
Mode AttachTypeAttach `json:"mode"`
56+
Mode AttachTypeAttach `json:"mode,omitempty"`
5557
}
5658

5759
type ClFexitProgramInfoState struct {
@@ -62,6 +64,7 @@ type ClFexitProgramInfoState struct {
6264
// successful or not, a linkId, which is the kernel ID for the link if
6365
// successfully attached, and other attachment specific data.
6466
// +optional
67+
// +listType=atomic
6568
// +kubebuilder:validation:MaxItems=1
6669
Links []ClFexitAttachInfoState `json:"links,omitempty"`
6770
}

0 commit comments

Comments
 (0)