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,
BpfApplication, ClusterBpfApplicationState and BpfApplicationState CRD
fields.

Signed-off-by: Billy McFall <[email protected]>

Author: Billy99

apis/v1alpha1/bpf_application_state_types.go

@@ -22,7 +22,6 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/client"
 )
 
-// BpfApplicationProgramState defines the desired state of BpfApplication
 // +union
 // +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"
 // +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,96 @@ import (
 type BpfApplicationProgramState struct {
 	BpfProgramStateCommon `json:",inline"`
 
-	// type specifies the bpf program type
+	// type specifies the provisioned eBPF program type for this program entry.
+	// Type will be one of:
+	//   TC, TCX, UProbe, URetProbe, XDP
+	//
+	// When set to TC, the tc object will be populated with the eBPF program data
+	// associated with a TC program.
+	//
+	// When set to TCX, the tcx object will be populated with the eBPF program
+	// data associated with a TCX program.
+	//
+	// When set to UProbe, the uprobe object will be populated with the eBPF
+	// program data associated with a UProbe program.
+	//
+	// When set to URetProbe, the uretprobe object will be populated with the eBPF
+	// program data associated with a URetProbe program.
+	//
+	// When set to XDP, the xdp object will be populated with the eBPF program data
+	// associated with a URetProbe program.
 	// +unionDiscriminator
 	// +required
 	// +kubebuilder:validation:Enum:="XDP";"TC";"TCX";"UProbe";"URetProbe"
 	Type EBPFProgType `json:"type"`
 
-	// xdp defines the desired state of the application's XdpPrograms.
+	// xdp contains the attachment data for an XDP program when type is set to XDP.
 	// +unionMember
 	// +optional
 	XDP *XdpProgramInfoState `json:"xdp,omitempty"`
 
-	// tc defines the desired state of the application's TcPrograms.
+	// tc contains the attachment data for a TC program when type is set to TC.
 	// +unionMember
 	// +optional
 	TC *TcProgramInfoState `json:"tc,omitempty"`
 
-	// tcx defines the desired state of the application's TcxPrograms.
+	// tcx contains the attachment data for a TCX program when type is set to TCX.
 	// +unionMember
 	// +optional
 	TCX *TcxProgramInfoState `json:"tcx,omitempty"`
 
-	// uprobe defines the desired state of the application's UprobePrograms.
+	// uprobe contains the attachment data for a UProbe program when type is set to
+	// UProbe.
 	// +unionMember
 	// +optional
 	UProbe *UprobeProgramInfoState `json:"uprobe,omitempty"`
 
-	// uretprobe defines the desired state of the application's UretprobePrograms.
+	// uretprobe contains the attachment data for a URetProbe program when type is
+	// set to URetProbe.
 	// +unionMember
 	// +optional
 	URetProbe *UprobeProgramInfoState `json:"uretprobe,omitempty"`
 }
 
-// BpfApplicationStateStatus reflects the status of the BpfApplication on the given node
 type BpfApplicationStateStatus struct {
-	// updateCount is the number of times the BpfApplicationState has been updated. Set to 1
-	// when the object is created, then it is incremented prior to each update.
-	// This allows us to verify that the API server has the updated object prior
-	// to starting a new Reconcile operation.
+	// updateCount is the number of times the BpfApplicationState has been updated.
+	// Set to 1 when the object is created, then it is incremented prior to each
+	// update. This is used to verify that the API server has the updated object
+	// prior to starting a new Reconcile operation.
 	UpdateCount int64 `json:"updateCount"`
-	// node is the name of the node for this BpfApplicationStateSpec.
+	// node is the name of the Kubernets node for this BpfApplicationState.
 	Node string `json:"node"`
-	// appLoadStatus reflects the status of loading the bpf application on the
-	// given node.
+	// appLoadStatus reflects the status of loading the eBPF application on the
+	// given node. Whether or not the eBPF program is attached to an attachment
+	// point is tracked by the linkStatus field, which is under of each link of
+	// each program.
+	//
+	// NotLoaded is a temporary state that is assigned when a
+	// ClusterBpfApplicationState is created and the initial reconcile is being
+	// processed.
+	//
+	// LoadSuccess is returned if all the programs have been loaded with no errors.
+	//
+	// LoadError is returned if one or more programs encountered an error and were
+	// not loaded.
+	//
+	// NotSelected is returned if this application did not select to run on this
+	// Kubernetes node.
+	//
+	// UnloadSuccess is returned when all the programs were successfully unloaded.
+	//
+	// UnloadError is returned if one or more programs encountered an error when
+	// being unloaded.
 	AppLoadStatus AppLoadStatus `json:"appLoadStatus"`
-	// programs is a list of bpf programs contained in the parent application.
+	// programs is a list of eBPF programs contained in the parent BpfApplication
+	// instance. Each entry in the list contains the derived program attributes as
+	// well as the attach status for each program on the given Kubernetes node.
 	Programs []BpfApplicationProgramState `json:"programs,omitempty"`
-	// Conditions contains the overall status of the BpfApplicationState object
-	// on the given node.
+	// conditions contains the summary state of the BpfApplication for the given
+	// Kubernetes node. If one or more programs failed to load or attach to the
+	// designated attachment point, the condition will report the error. If more
+	// than one error has occurred, condition will contain the first error
+	// encountered.
 	// +patchMergeKey=type
 	// +patchStrategy=merge
 	// +listType=map
@@ -92,14 +133,21 @@ type BpfApplicationStateStatus struct {
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:scope=Namespaced
 
-// BpfApplicationState contains the per-node state of a BpfApplication.
+// BpfApplicationState contains the state of a BpfApplication instance for a
+// given Kubernetes node. When a user creates a BpfApplication instance, bpfman
+// creates a BpfApplicationState instance for each node in a Kubernetes
+// cluster.
 // +kubebuilder:printcolumn:name="Node",type=string,JSONPath=".status.node"
 // +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[0].reason`
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
 type BpfApplicationState struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// status reflects the status of a BpfApplication instance for the given node.
+	// appLoadStatus and conditions provide an overall status for the given node,
+	// while each item in the programs list provides a per eBPF program status for
+	// the given node.
 	Status BpfApplicationStateStatus `json:"status,omitempty"`
 }
 

apis/v1alpha1/bpf_application_types.go

@@ -28,52 +28,143 @@ import (
 // +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"
 // +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"
 type BpfApplicationProgram struct {
-	// name is the name of the function that is the entry point for the BPF
-	// program
+	// name is a required field and is the name of the function that is the entry
+	// point for the eBPF program. name must not be an empty string, must not
+	// exceed 64 characters in length, must start with alpha characters and must
+	// only contain alphanumeric characters.
+	// +required
 	// +kubebuilder:validation:Pattern="^[a-zA-Z][a-zA-Z0-9_]+."
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=64
 	Name string `json:"name"`
 
-	// type specifies the bpf program type
+	// type is a required field used to specify the type of the eBPF program. The
+	// type dictates which eBPF attachment point to use. This is where the eBPF
+	// program is executed.
+	//
+	// Allowed values are:
+	//   TC, TCX, UProbe, URetProbe, XDP
+	//
+	// When set to TC, the eBPF program can attach to network devices (interfaces).
+	// The program can be attached on either packet ingress or egress, so the
+	// program will be called on every incoming or outgoing packet seen by the
+	// network device. When using the TC program type, the tc field is required.
+	// See tc for more details on TC programs.
+	//
+	// When set to TCX, the eBPF program can attach to network devices
+	// (interfaces). The program can be attached on either packet ingress or
+	// egress, so the program will be called on every incoming or outgoing packet
+	// seen by the network device. When using the TCX program type, the tcx field
+	// is required. See tcx for more details on TCX programs.
+	//
+	// When set to UProbe, the program can attach in user-space. The UProbe is
+	// attached to a binary, library or function name, and optionally an offset in
+	// the code. When using the UProbe program type, the uprobe field is required.
+	// See uprobe for more details on UProbe programs.
+	//
+	// When set to URetProbe, the program can attach in user-space.
+	// The URetProbe is attached to the return of a binary, library or function
+	// name, and optionally an offset in the code.  When using the URetProbe
+	// program type, the uretprobe field is required. See uretprobe for more
+	// details on URetProbe programs.
+	//
+	// When set to XDP, the eBPF program can attach to network devices (interfaces)
+	// and will be called on every incoming packet received by the network device.
+	// When using the XDP program type, the xdp field is required. See xdp for more
+	// details on XDP programs.
 	// +unionDiscriminator
 	// +required
 	// +kubebuilder:validation:Enum:="XDP";"TC";"TCX";"UProbe";"URetProbe"
 	Type EBPFProgType `json:"type"`
 
-	// xdp defines the desired state of the application's XdpPrograms.
+	// xdp is an optional field, but required when the type field is set to XDP.
+	// xdp defines the desired state of the application's XDP programs. XDP program
+	// can be attached to network devices (interfaces) and will be called on every
+	// incoming packet received by the network device. The XDP attachment point is
+	// just after the packet has been received off the wire, but before the Linux
+	// kernel has allocated an sk_buff, which is used to pass the packet through
+	// the kernel networking stack.
 	// +unionMember
 	// +optional
 	XDP *XdpProgramInfo `json:"xdp,omitempty"`
 
-	// tc defines the desired state of the application's TcPrograms.
+	// tc is an optional field, but required when the type field is set to TC. tc
+	// defines the desired state of the application's TC programs. TC programs are
+	// attached to network devices (interfaces). The program can be attached on
+	// either packet ingress or egress, so the program will be called on every
+	// incoming or outgoing packet seen by the network device. The TC attachment
+	// point is in Linux's Traffic Control (tc) subsystem, which is after the
+	// Linux kernel has allocated an sk_buff. TCX is newer implementation of TC
+	// with enhanced performance and better support for running multiple programs
+	// on a given network device. This makes TC useful for packet classification
+	// actions.
 	// +unionMember
 	// +optional
 	TC *TcProgramInfo `json:"tc,omitempty"`
 
-	// tcx defines the desired state of the application's TcxPrograms.
+	// tcx is an optional field, but required when the type field is set to TCX.
+	// tcx defines the desired state of the application's TCX programs. TCX
+	// programs are attached to network devices (interfaces). The program can be
+	// attached on either packet ingress or egress, so the program will be called
+	// on every incoming or outgoing packet seen by the network device. The TCX
+	// attachment point is in Linux's Traffic Control (tc) subsystem, which is
+	// after the Linux kernel has allocated an sk_buff. This makes TCX useful for
+	// packet classification actions. TCX is a newer implementation of TC with
+	// enhanced performance and better support for running multiple programs on a
+	// given network device.
 	// +unionMember
 	// +optional
 	TCX *TcxProgramInfo `json:"tcx,omitempty"`
 
-	// uprobe defines the desired state of the application's UprobePrograms.
+	// uprobe is an optional field, but required when the type field is set to
+	// UProbe. uprobe defines the desired state of the application's UProbe
+	// programs. UProbe programs are user-space probes. A target must be provided,
+	// which is the library name or absolute path to a binary or library where the
+	// probe is attached. Optionally, a function name can also be provided to
+	// provide finer granularity on where the probe is attached. They can be
+	// attached at any point in the binary, library or function using the optional
+	// offset field. However, caution must be taken when using the offset, ensuring
+	// the offset is still in the desired bytecode.
 	// +unionMember
 	// +optional
 	UProbe *UprobeProgramInfo `json:"uprobe,omitempty"`
 
-	// uretprobe defines the desired state of the application's UretprobePrograms.
+	// uretprobe is an optional field, but required when the type field is set to
+	// URetProbe. uretprobe defines the desired state of the application's
+	// URetProbe programs. URetProbe programs are user-space probes. A target must
+	// be provided, which is the library name or absolute path to a binary or
+	// library where the probe is attached. Optionally, a function name can also be
+	// provided to provide finer granularity on where the probe is attached. They
+	// are attached to the return point of the binary, library or function, but can
+	// be set anywhere using the optional offset field. However, caution must be
+	// taken when using the offset, ensuring the offset is still in the desired
+	// bytecode.
 	// +unionMember
 	// +optional
 	URetProbe *UprobeProgramInfo `json:"uretprobe,omitempty"`
 }
 
-// BpfApplicationSpec defines the desired state of BpfApplication
+// spec defines the desired state of the BpfApplication. The BpfApplication
+// describes the set of one or more namespace scoped eBPF programs that should
+// be loaded for a given application and attributes for how they should be
+// loaded. eBPF programs that are grouped together under the same
+// BpfApplication instance can share maps and global data between the eBPF
+// programs loaded on the same Kubernetes Node.
 type BpfApplicationSpec struct {
 	BpfAppCommon `json:",inline"`
 
-	// programs is the list of bpf programs in the BpfApplication that should be
-	// loaded. The application can selectively choose which program(s) to run
-	// from this list based on the optional attach points provided.
+	// programs is a required field and is the list of eBPF programs in a BPF
+	// Application CRD that should be loaded in kernel memory. At least one entry
+	// is required. eBPF programs in this list will be loaded on the system based
+	// the nodeSelector. Even if an eBPF program is loaded in kernel memory, it
+	// cannot be triggered until an attachment point is provided. The different
+	// program types have different ways of attaching. The attachment points can be
+	// added at creation time or modified (added or removed) at a later time to
+	// activate or deactivate the eBPF program as desired.
+	// CAUTION: When programs are added or removed from the list, that requires all
+	// programs in the list to be reloaded, which could be temporarily service
+	// effecting. For this reason, modifying the list is currently not allowed.
+	// +required
 	// +kubebuilder:validation:MinItems:=1
 	Programs []BpfApplicationProgram `json:"programs,omitempty"`
 }
@@ -83,7 +174,15 @@ type BpfApplicationSpec struct {
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:scope=Namespaced
 
-// BpfApplication is the Schema for the bpfapplications API
+// BpfApplication is the schema for the namespace scoped BPF Applications API.
+// Using this API allows applications to load one or more eBPF programs on a
+// Kubernetes cluster using bpfman to load the programs.
+//
+// The bpfApplication.status field reports the overall status of the
+// BpfApplication CRD. A given BpfApplication CRD can result in loading and
+// attaching multiple eBPF programs on multiple nodes, so this status is just a
+// summary. More granular per-node status details can be found in the
+// corresponding BpfApplicationState CRD that bpfman creates for each node.
 // +kubebuilder:printcolumn:name="NodeSelector",type=string,JSONPath=`.spec.nodeselector`
 // +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[0].reason`
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"