Skip to content

Commit ddc2a5b

Browse files
Billy99Billy99
committed
api review: update field descriptions
As part of the API review, a comment was made to improve the description of all fields. This commit makes a pass at the ClusterBpfApplication and BpfApplication CRD fields. Signed-off-by: Billy McFall <[email protected]>
1 parent d749d10 commit ddc2a5b

27 files changed

+3201
-1003
lines changed

‎apis/v1alpha1/bpf_application_state_types.go

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,9 @@ type BpfApplicationProgramState struct {
6464
URetProbe *UprobeProgramInfoState `json:"uretprobe,omitempty"`
6565
}
6666

67-
// BpfApplicationStateStatus reflects the status of the BpfApplication on the given node
67+
// status reflects the status of the BpfApplication for the given node.
68+
// appLoadStatus and conditions provide an overall status for the given node
69+
// while programs provides a per eBPF program status for the given node.
6870
type BpfApplicationStateStatus struct {
6971
// updateCount is the number of times the BpfApplicationState has been updated. Set to 1
7072
// when the object is created, then it is incremented prior to each update.
@@ -92,7 +94,10 @@ type BpfApplicationStateStatus struct {
9294
// +kubebuilder:subresource:status
9395
// +kubebuilder:resource:scope=Namespaced
9496

95-
// BpfApplicationState contains the per-node state of a BpfApplication.
97+
// BpfApplicationState contains the state of a BpfApplication instance for a
98+
// given Kubernetes node. When a user creates a BpfApplication instance, bpfman
99+
// creates a BpfApplicationState instance for each node in a Kubernetes
100+
// cluster.
96101
// +kubebuilder:printcolumn:name="Node",type=string,JSONPath=".status.node"
97102
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[0].reason`
98103
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"

‎apis/v1alpha1/bpf_application_types.go

Lines changed: 111 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -28,52 +28,142 @@ 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. The
42+
// type dictates which eBPF hook point to use. This is where the eBPF program
43+
// is executed.
44+
//
45+
// Allowed values are:
46+
// TC, TCX, UProbe, URetProbe, XDP
47+
//
48+
// When set to TC, the eBPF program can attach to network devices (interfaces).
49+
// The program can be attached on either packet ingress or egress, so the
50+
// program will be called on every incoming or outgoing packet seen by the
51+
// network device. When using the TC program type, the tc field is required.
52+
// See tc for more details on TC programs.
53+
//
54+
// When set to TCX, the eBPF program can attach to network devices
55+
// (interfaces). The program can be attached on either packet ingress or
56+
// egress, so the program will be called on every incoming or outgoing packet
57+
// seen by the network device. When using the TCX program type, the tcx field
58+
// is required. See tcx for more details on TCX programs.
59+
//
60+
// When set to UProbe, the program can attach in user-space. The UProbe is
61+
// attached to a binary, library or function name, and optionally an offset in
62+
// the code. When using the UProbe program type, the uprobe field is required.
63+
// See uprobe for more details on UProbe programs.
64+
//
65+
// When set to URetProbe, the program can attach in user-space.
66+
// The URetProbe is attached to the return of a binary, library or function
67+
// name, and optionally an offset in the code. When using the URetProbe
68+
// program type, the uretprobe field is required. See uretprobe for more
69+
// details on URetProbe programs.
70+
//
71+
// When set to XDP, the eBPF program can attach to network devices (interfaces)
72+
// and will be called on every incoming packet received by the network device.
73+
// When using the XDP program type, the xdp field is required. See xdp for more
74+
// details on XDP programs.
3975
// +unionDiscriminator
4076
// +required
4177
// +kubebuilder:validation:Enum:="XDP";"TC";"TCX";"UProbe";"URetProbe"
4278
Type EBPFProgType `json:"type"`
4379

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

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

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

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

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

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

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.
155+
// programs is a required field and is the list of eBPF programs in a BPF
156+
// Application CRD that should be loaded in kernel memory. At least one entry
157+
// is required. eBPF programs in this list will be loaded on the system based
158+
// the nodeSelector. Even if an eBPF program is loaded in kernel memory, it
159+
// cannot be triggered until an attachment point is provided. The different
160+
// program types have different ways of attaching. The attachment points can be
161+
// added at creation time or modified (added or removed) at a later time to
162+
// activate or deactivate the eBPF program as desired.
163+
// CAUTION: When programs are added or removed from the list, that requires all
164+
// programs in the list to be reloaded, which could be temporarily service
165+
// effecting. For this reason, modifying the list is currently not allowed.
166+
// +required
77167
// +kubebuilder:validation:MinItems:=1
78168
Programs []BpfApplicationProgram `json:"programs,omitempty"`
79169
}
@@ -83,7 +173,15 @@ type BpfApplicationSpec struct {
83173
// +kubebuilder:subresource:status
84174
// +kubebuilder:resource:scope=Namespaced
85175

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

‎apis/v1alpha1/cluster_bpf_application_state_types.go

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,9 @@ type ClBpfApplicationProgramState struct {
9494
TracePoint *ClTracepointProgramInfoState `json:"tracepoint,omitempty"`
9595
}
9696

97-
// ClBpfApplicationStateStatus reflects the status of the ClusterBpfApplicationState on the given node
97+
// status reflects the status of the ClusterBpfApplication for the given node.
98+
// appLoadStatus and conditions provide an overall status for the given node
99+
// while programs provides a per eBPF program status for the given node.
98100
type ClBpfApplicationStateStatus struct {
99101
// updateCount is the number of times the BpfApplicationState has been updated. Set to 1
100102
// when the object is created, then it is incremented prior to each update.
@@ -123,7 +125,10 @@ type ClBpfApplicationStateStatus struct {
123125
// +kubebuilder:subresource:status
124126
// +kubebuilder:resource:scope=Cluster
125127

126-
// ClusterBpfApplicationState contains the per-node state of a BpfApplication.
128+
// ClusterBpfApplicationState contains the state of a ClusterBpfApplication
129+
// instance for a given Kubernetes node. When a user creates a
130+
// ClusterBpfApplication instance, bpfman creates a ClusterBpfApplicationState
131+
// instance for each node in a Kubernetes cluster.
127132
// +kubebuilder:printcolumn:name="Node",type=string,JSONPath=".status.node"
128133
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[0].reason`
129134
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"

0 commit comments

Comments
 (0)