Skip to content

Commit 9ecc49b

Browse files
mergify[bot]mergify[bot]
authored
Merge pull request #419 from Billy99/billy99-api-review-01
api review: update field descriptions
2 parents cd81bc6 + 4e2b3e7 commit 9ecc49b

29 files changed

+4754
-2071
lines changed

‎apis/v1alpha1/bpf_application_state_types.go‎

Lines changed: 68 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,6 @@ import (
2222
"sigs.k8s.io/controller-runtime/pkg/client"
2323
)
2424

25-
// BpfApplicationProgramState defines the desired state of BpfApplication
2625
// +union
2726
// +kubebuilder:validation:XValidation:rule="has(self.type) && self.type == 'XDP' ? has(self.xdp) : !has(self.xdp)",message="xdp configuration is required when type is xdp, and forbidden otherwise"
2827
// +kubebuilder:validation:XValidation:rule="has(self.type) && self.type == 'TC' ? has(self.tc) : !has(self.tc)",message="tc configuration is required when type is tc, and forbidden otherwise"
@@ -32,54 +31,98 @@ import (
3231
type BpfApplicationProgramState struct {
3332
BpfProgramStateCommon `json:",inline"`
3433

35-
// type specifies the bpf program type
34+
// type specifies the provisioned eBPF program type for this program entry.
35+
// Type will be one of:
36+
// TC, TCX, UProbe, URetProbe, XDP
37+
//
38+
// When set to TC, the tc object will be populated with the eBPF program data
39+
// associated with a TC program.
40+
//
41+
// When set to TCX, the tcx object will be populated with the eBPF program
42+
// data associated with a TCX program.
43+
//
44+
// When set to UProbe, the uprobe object will be populated with the eBPF
45+
// program data associated with a UProbe program.
46+
//
47+
// When set to URetProbe, the uretprobe object will be populated with the eBPF
48+
// program data associated with a URetProbe program.
49+
//
50+
// When set to XDP, the xdp object will be populated with the eBPF program data
51+
// associated with a URetProbe program.
3652
// +unionDiscriminator
3753
// +required
3854
// +kubebuilder:validation:Enum:="XDP";"TC";"TCX";"UProbe";"URetProbe"
3955
Type EBPFProgType `json:"type"`
4056

41-
// xdp defines the desired state of the application's XdpPrograms.
57+
// xdp contains the attachment data for an XDP program when type is set to XDP.
4258
// +unionMember
4359
// +optional
4460
XDP *XdpProgramInfoState `json:"xdp,omitempty"`
4561

46-
// tc defines the desired state of the application's TcPrograms.
62+
// tc contains the attachment data for a TC program when type is set to TC.
4763
// +unionMember
4864
// +optional
4965
TC *TcProgramInfoState `json:"tc,omitempty"`
5066

51-
// tcx defines the desired state of the application's TcxPrograms.
67+
// tcx contains the attachment data for a TCX program when type is set to TCX.
5268
// +unionMember
5369
// +optional
5470
TCX *TcxProgramInfoState `json:"tcx,omitempty"`
5571

56-
// uprobe defines the desired state of the application's UprobePrograms.
72+
// uprobe contains the attachment data for a UProbe program when type is set to
73+
// UProbe.
5774
// +unionMember
5875
// +optional
5976
UProbe *UprobeProgramInfoState `json:"uprobe,omitempty"`
6077

61-
// uretprobe defines the desired state of the application's UretprobePrograms.
78+
// uretprobe contains the attachment data for a URetProbe program when type is
79+
// set to URetProbe.
6280
// +unionMember
6381
// +optional
6482
URetProbe *UprobeProgramInfoState `json:"uretprobe,omitempty"`
6583
}
6684

67-
// BpfApplicationStateStatus reflects the status of the BpfApplication on the given node
6885
type BpfApplicationStateStatus struct {
69-
// updateCount is the number of times the BpfApplicationState has been updated. Set to 1
70-
// when the object is created, then it is incremented prior to each update.
71-
// This allows us to verify that the API server has the updated object prior
72-
// to starting a new Reconcile operation.
86+
// UpdateCount tracks the number of times the BpfApplicationState object has
87+
// been updated. The bpfman agent initializes it to 1 when it creates the
88+
// object, and then increments it before each subsequent update. It serves
89+
// as a lightweight sequence number to verify that the API server is serving
90+
// the most recent version of the object before beginning a new Reconcile
91+
// operation.
7392
UpdateCount int64 `json:"updateCount"`
74-
// node is the name of the node for this BpfApplicationStateSpec.
93+
// node is the name of the Kubernets node for this BpfApplicationState.
7594
Node string `json:"node"`
76-
// appLoadStatus reflects the status of loading the bpf application on the
95+
// appLoadStatus reflects the status of loading the eBPF application on the
7796
// given node.
97+
//
98+
// NotLoaded is a temporary state that is assigned when a
99+
// ClusterBpfApplicationState is created and the initial reconcile is being
100+
// processed.
101+
//
102+
// LoadSuccess is returned if all the programs have been loaded with no
103+
// errors.
104+
//
105+
// LoadError is returned if one or more programs encountered an error and
106+
// were not loaded.
107+
//
108+
// NotSelected is returned if this application did not select to run on this
109+
// Kubernetes node.
110+
//
111+
// UnloadSuccess is returned when all the programs were successfully
112+
// unloaded.
113+
//
114+
// UnloadError is returned if one or more programs encountered an error when
115+
// being unloaded.
78116
AppLoadStatus AppLoadStatus `json:"appLoadStatus"`
79-
// programs is a list of bpf programs contained in the parent application.
117+
// programs is a list of eBPF programs contained in the parent BpfApplication
118+
// instance. Each entry in the list contains the derived program attributes as
119+
// well as the attach status for each program on the given Kubernetes node.
80120
Programs []BpfApplicationProgramState `json:"programs,omitempty"`
81-
// Conditions contains the overall status of the BpfApplicationState object
82-
// on the given node.
121+
// conditions contains the summary state of the BpfApplication for the given
122+
// Kubernetes node. If one or more programs failed to load or attach to the
123+
// designated attachment point, the condition will report the error. If more
124+
// than one error has occurred, condition will contain the first error
125+
// encountered.
83126
// +patchMergeKey=type
84127
// +patchStrategy=merge
85128
// +listType=map
@@ -92,14 +135,21 @@ type BpfApplicationStateStatus struct {
92135
// +kubebuilder:subresource:status
93136
// +kubebuilder:resource:scope=Namespaced
94137

95-
// BpfApplicationState contains the per-node state of a BpfApplication.
138+
// BpfApplicationState contains the state of a BpfApplication instance for a
139+
// given Kubernetes node. When a user creates a BpfApplication instance, bpfman
140+
// creates a BpfApplicationState instance for each node in a Kubernetes
141+
// cluster.
96142
// +kubebuilder:printcolumn:name="Node",type=string,JSONPath=".status.node"
97143
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[0].reason`
98144
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
99145
type BpfApplicationState struct {
100146
metav1.TypeMeta `json:",inline"`
101147
metav1.ObjectMeta `json:"metadata,omitempty"`
102148

149+
// status reflects the status of a BpfApplication instance for the given node.
150+
// appLoadStatus and conditions provide an overall status for the given node,
151+
// while each item in the programs list provides a per eBPF program status for
152+
// the given node.
103153
Status BpfApplicationStateStatus `json:"status,omitempty"`
104154
}
105155

‎apis/v1alpha1/bpf_application_types.go‎

Lines changed: 110 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -28,52 +28,141 @@ import (
2828
// +kubebuilder:validation:XValidation:rule="has(self.type) && self.type == 'UProbe' ? has(self.uprobe) : !has(self.uprobe)",message="uprobe configuration is required when type is uprobe, and forbidden otherwise"
2929
// +kubebuilder:validation:XValidation:rule="has(self.type) && self.type == 'URetProbe' ? has(self.uretprobe) : !has(self.uretprobe)",message="uretprobe configuration is required when type is uretprobe, and forbidden otherwise"
3030
type BpfApplicationProgram struct {
31-
// name is the name of the function that is the entry point for the BPF
32-
// program
31+
// name is a required field and is the name of the function that is the entry
32+
// point for the eBPF program. name must not be an empty string, must not
33+
// exceed 64 characters in length, must start with alpha characters and must
34+
// only contain alphanumeric characters.
35+
// +required
3336
// +kubebuilder:validation:Pattern="^[a-zA-Z][a-zA-Z0-9_]+."
3437
// +kubebuilder:validation:MinLength=1
3538
// +kubebuilder:validation:MaxLength=64
3639
Name string `json:"name"`
3740

38-
// type specifies the bpf program type
41+
// type is a required field used to specify the type of the eBPF program.
42+
//
43+
// Allowed values are:
44+
// TC, TCX, UProbe, URetProbe, XDP
45+
//
46+
// When set to TC, the eBPF program can attach to network devices (interfaces).
47+
// The program can be attached on either packet ingress or egress, so the
48+
// program will be called on every incoming or outgoing packet seen by the
49+
// network device. When using the TC program type, the tc field is required.
50+
// See tc for more details on TC programs.
51+
//
52+
// When set to TCX, the eBPF program can attach to network devices
53+
// (interfaces). The program can be attached on either packet ingress or
54+
// egress, so the program will be called on every incoming or outgoing packet
55+
// seen by the network device. When using the TCX program type, the tcx field
56+
// is required. See tcx for more details on TCX programs.
57+
//
58+
// When set to UProbe, the program can attach in user-space. The UProbe is
59+
// attached to a binary, library or function name, and optionally an offset in
60+
// the code. When using the UProbe program type, the uprobe field is required.
61+
// See uprobe for more details on UProbe programs.
62+
//
63+
// When set to URetProbe, the program can attach in user-space.
64+
// The URetProbe is attached to the return of a binary, library or function
65+
// name, and optionally an offset in the code. When using the URetProbe
66+
// program type, the uretprobe field is required. See uretprobe for more
67+
// details on URetProbe programs.
68+
//
69+
// When set to XDP, the eBPF program can attach to network devices (interfaces)
70+
// and will be called on every incoming packet received by the network device.
71+
// When using the XDP program type, the xdp field is required. See xdp for more
72+
// details on XDP programs.
3973
// +unionDiscriminator
4074
// +required
4175
// +kubebuilder:validation:Enum:="XDP";"TC";"TCX";"UProbe";"URetProbe"
4276
Type EBPFProgType `json:"type"`
4377

44-
// xdp defines the desired state of the application's XdpPrograms.
78+
// xdp is an optional field, but required when the type field is set to XDP.
79+
// xdp defines the desired state of the application's XDP programs. XDP program
80+
// can be attached to network devices (interfaces) and will be called on every
81+
// incoming packet received by the network device. The XDP attachment point is
82+
// just after the packet has been received off the wire, but before the Linux
83+
// kernel has allocated an sk_buff, which is used to pass the packet through
84+
// the kernel networking stack.
4585
// +unionMember
4686
// +optional
4787
XDP *XdpProgramInfo `json:"xdp,omitempty"`
4888

49-
// tc defines the desired state of the application's TcPrograms.
89+
// tc is an optional field, but required when the type field is set to TC. tc
90+
// defines the desired state of the application's TC programs. TC programs are
91+
// attached to network devices (interfaces). The program can be attached on
92+
// either packet ingress or egress, so the program will be called on every
93+
// incoming or outgoing packet seen by the network device. The TC attachment
94+
// point is in Linux's Traffic Control (tc) subsystem, which is after the
95+
// Linux kernel has allocated an sk_buff. TCX is newer implementation of TC
96+
// with enhanced performance and better support for running multiple programs
97+
// on a given network device. This makes TC useful for packet classification
98+
// actions.
5099
// +unionMember
51100
// +optional
52101
TC *TcProgramInfo `json:"tc,omitempty"`
53102

54-
// tcx defines the desired state of the application's TcxPrograms.
103+
// tcx is an optional field, but required when the type field is set to TCX.
104+
// tcx defines the desired state of the application's TCX programs. TCX
105+
// programs are attached to network devices (interfaces). The program can be
106+
// attached on either packet ingress or egress, so the program will be called
107+
// on every incoming or outgoing packet seen by the network device. The TCX
108+
// attachment point is in Linux's Traffic Control (tc) subsystem, which is
109+
// after the Linux kernel has allocated an sk_buff. This makes TCX useful for
110+
// packet classification actions. TCX is a newer implementation of TC with
111+
// enhanced performance and better support for running multiple programs on a
112+
// given network device.
55113
// +unionMember
56114
// +optional
57115
TCX *TcxProgramInfo `json:"tcx,omitempty"`
58116

59-
// uprobe defines the desired state of the application's UprobePrograms.
117+
// uprobe is an optional field, but required when the type field is set to
118+
// UProbe. uprobe defines the desired state of the application's UProbe
119+
// programs. UProbe programs are user-space probes. A target must be provided,
120+
// which is the library name or absolute path to a binary or library where the
121+
// probe is attached. Optionally, a function name can also be provided to
122+
// provide finer granularity on where the probe is attached. They can be
123+
// attached at any point in the binary, library or function using the optional
124+
// offset field. However, caution must be taken when using the offset, ensuring
125+
// the offset is still in the desired bytecode.
60126
// +unionMember
61127
// +optional
62128
UProbe *UprobeProgramInfo `json:"uprobe,omitempty"`
63129

64-
// uretprobe defines the desired state of the application's UretprobePrograms.
130+
// uretprobe is an optional field, but required when the type field is set to
131+
// URetProbe. uretprobe defines the desired state of the application's
132+
// URetProbe programs. URetProbe programs are user-space probes. A target must
133+
// be provided, which is the library name or absolute path to a binary or
134+
// library where the probe is attached. Optionally, a function name can also be
135+
// provided to provide finer granularity on where the probe is attached. They
136+
// are attached to the return point of the binary, library or function, but can
137+
// be set anywhere using the optional offset field. However, caution must be
138+
// taken when using the offset, ensuring the offset is still in the desired
139+
// bytecode.
65140
// +unionMember
66141
// +optional
67142
URetProbe *UprobeProgramInfo `json:"uretprobe,omitempty"`
68143
}
69144

70-
// BpfApplicationSpec defines the desired state of BpfApplication
145+
// spec defines the desired state of the BpfApplication. The BpfApplication
146+
// describes the set of one or more namespace scoped eBPF programs that should
147+
// be loaded for a given application and attributes for how they should be
148+
// loaded. eBPF programs that are grouped together under the same
149+
// BpfApplication instance can share maps and global data between the eBPF
150+
// programs loaded on the same Kubernetes Node.
71151
type BpfApplicationSpec struct {
72152
BpfAppCommon `json:",inline"`
73153

74-
// programs is the list of bpf programs in the BpfApplication that should be
75-
// loaded. The application can selectively choose which program(s) to run
76-
// from this list based on the optional attach points provided.
154+
// programs is a required field and is the list of eBPF programs in a BPF
155+
// Application CRD that should be loaded in kernel memory. At least one entry
156+
// is required. eBPF programs in this list will be loaded on the system based
157+
// the nodeSelector. Even if an eBPF program is loaded in kernel memory, it
158+
// cannot be triggered until an attachment point is provided. The different
159+
// program types have different ways of attaching. The attachment points can be
160+
// added at creation time or modified (added or removed) at a later time to
161+
// activate or deactivate the eBPF program as desired.
162+
// CAUTION: When programs are added or removed from the list, that requires all
163+
// programs in the list to be reloaded, which could be temporarily service
164+
// effecting. For this reason, modifying the list is currently not allowed.
165+
// +required
77166
// +kubebuilder:validation:MinItems:=1
78167
Programs []BpfApplicationProgram `json:"programs,omitempty"`
79168
}
@@ -83,7 +172,15 @@ type BpfApplicationSpec struct {
83172
// +kubebuilder:subresource:status
84173
// +kubebuilder:resource:scope=Namespaced
85174

86-
// BpfApplication is the Schema for the bpfapplications API
175+
// BpfApplication is the schema for the namespace scoped BPF Applications API.
176+
// This API allows applications to use bpfman to load and attach one or more
177+
// eBPF programs on a Kubernetes cluster.
178+
//
179+
// The bpfApplication.status field reports the overall status of the
180+
// BpfApplication CRD. A given BpfApplication CRD can result in loading and
181+
// attaching multiple eBPF programs on multiple nodes, so this status is just a
182+
// summary. More granular per-node status details can be found in the
183+
// corresponding BpfApplicationState CRD that bpfman creates for each node.
87184
// +kubebuilder:printcolumn:name="NodeSelector",type=string,JSONPath=`.spec.nodeselector`
88185
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[0].reason`
89186
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"

0 commit comments

Comments
 (0)