Review comments from Andre

Signed-off-by: Andre Fredette <[email protected]>

Author: anfredette

apis/v1alpha1/bpf_application_state_types.go

@@ -83,31 +83,33 @@ type BpfApplicationProgramState struct {
 }
 
 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 is used to verify that the API server has the updated object
-	// prior to starting a new Reconcile operation.
+	// UpdateCount tracks the number of times the BpfApplicationState object has
+	// been updated. The bpfman agent initializes it to 1 when it creates the
+	// object, and then increments it before each subsequent update. It serves
+	// as a lightweight sequence number to verify that the API server is serving
+	// the most recent version of the object before beginning a new Reconcile
+	// operation.
 	UpdateCount int64 `json:"updateCount"`
 	// node is the name of the Kubernets node for this BpfApplicationState.
 	Node string `json:"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.
+	// given node.
 	//
 	// 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.
+	// 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.
+	// 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.
+	// UnloadSuccess is returned when all the programs were successfully
+	// unloaded.
 	//
 	// UnloadError is returned if one or more programs encountered an error when
 	// being unloaded.

apis/v1alpha1/bpf_application_types.go

@@ -38,9 +38,7 @@ type BpfApplicationProgram struct {
 	// +kubebuilder:validation:MaxLength=64
 	Name string `json:"name"`
 
-	// 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.
+	// type is a required field used to specify the type of the eBPF program.
 	//
 	// Allowed values are:
 	//   TC, TCX, UProbe, URetProbe, XDP
@@ -175,8 +173,8 @@ type BpfApplicationSpec struct {
 // +kubebuilder:resource:scope=Namespaced
 
 // 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.
+// This API allows applications to use bpfman to load and attach one or more
+// eBPF programs on a Kubernetes cluster.
 //
 // The bpfApplication.status field reports the overall status of the
 // BpfApplication CRD. A given BpfApplication CRD can result in loading and

apis/v1alpha1/cluster_bpf_application_state_types.go

@@ -134,17 +134,17 @@ type ClBpfApplicationProgramState struct {
 }
 
 type ClBpfApplicationStateStatus struct {
-	// updateCount is the number of times the ClusterBpfApplicationState 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 tracks the number of times the BpfApplicationState object has
+	// been updated. The bpfman agent initializes it to 1 when it creates the
+	// object, and then increments it before each subsequent update. It serves
+	// as a lightweight sequence number to verify that the API server is serving
+	// the most recent version of the object before beginning a new Reconcile
+	// operation.
 	UpdateCount int64 `json:"updateCount"`
 	// node is the name of the Kubernetes node for this ClusterBpfApplicationState.
 	Node string `json:"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.
+	// given node.
 	//
 	// NotLoaded is a temporary state that is assigned when a
 	// ClusterBpfApplicationState is created and the initial reconcile is being

apis/v1alpha1/cluster_bpf_application_types.go

@@ -84,9 +84,7 @@ type ClBpfApplicationProgram struct {
 	// +kubebuilder:validation:MaxLength=64
 	Name string `json:"name"`
 
-	// 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.
+	// type is a required field used to specify the type of the eBPF program.
 	//
 	// Allowed values are:
 	//   FEntry, FExit, KProbe, KRetProbe, TC, TCX, TracePoint, UProbe, URetProbe,
@@ -305,8 +303,8 @@ type ClBpfApplicationSpec struct {
 // +kubebuilder:resource:scope=Cluster
 
 // ClusterBpfApplication is the schema for the cluster 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.
+// API. This API allows applications to use bpfman to load and attach one or
+// more eBPF programs on a Kubernetes cluster.
 //
 // The clusterBpfApplication.status field reports the overall status of the
 // ClusterBpfApplication CRD. A given ClusterBpfApplication CRD can result in

apis/v1alpha1/cluster_tc_program_types.go

@@ -89,7 +89,7 @@ type ClTcAttachInfo struct {
 	// program in the chain will be called. If a TC program returns Stolen, the
 	// next TC program in the chain will NOT be called.
 	// +optional
-	// +kubebuilder:default:={OK,Pipe,DispatcherReturn}
+	// +kubebuilder:default:={Pipe,DispatcherReturn}
 	ProceedOn []TcProceedOnValue `json:"proceedOn,omitempty"`
 }
 

apis/v1alpha1/cluster_uprobe_program_types.go

@@ -66,7 +66,7 @@ type ClUprobeAttachInfo struct {
 
 	// containers is an optional field that identifies the set of containers in
 	// which to attach the UProbe or URetProbe program. If containers is not
-	// specified, the eBPF program will be attached in the bpfman-agent container.
+	// specified, the eBPF program will be attached in the bpfman container.
 	// +optional
 	Containers *ClContainerSelector `json:"containers,omitempty"`
 }

apis/v1alpha1/cluster_xdp_program_types.go

@@ -30,10 +30,10 @@ type ClXdpProgramInfo struct {
 	// attached or detached.
 	//
 	// The attachment point for an XDP program is a network interface (or device).
-	// The interface can be specified by name, or by setting the
-	// primaryNodeInterface flag, which instructs bpfman to use the primary
-	// interface of a Kubernetes node. Optionally, the XDP program can also be
-	// installed into a set of network namespaces.
+	// The interface can be specified by name, by allowing bpfman to discover each
+	// interface, or by setting the primaryNodeInterface flag, which instructs
+	// bpfman to use the primary interface of a Kubernetes node. Optionally, the
+	// XDP program can also be installed into a set of network namespaces.
 	// +optional
 	Links []ClXdpAttachInfo `json:"links,omitempty"`
 }

apis/v1alpha1/shared_types.go

@@ -22,8 +22,8 @@ import (
 
 type InterfaceDiscovery struct {
 	// interfaceAutoDiscovery is an optional field. When enabled, the agent
-	// monitors the creation and deletion of interfaces and automatically attached
-	// eBPF programs to the newly discovered interfaces in both directions.
+	// monitors the creation and deletion of interfaces and automatically
+	// attached eBPF programs to the newly discovered interfaces.
 	// CAUTION: This has the potential to attach a given eBPF program to a large
 	// number of interfaces. Use with caution.
 	// +optional
@@ -52,7 +52,7 @@ type InterfaceDiscovery struct {
 	AllowedInterfaces []string `json:"allowedInterfaces,omitempty"`
 }
 
-// InterfaceSelector defines how to attach to interfaces.
+// InterfaceSelector describes the set of interfaces to attach a program to.
 // +kubebuilder:validation:MaxProperties=1
 // +kubebuilder:validation:MinProperties=1
 type InterfaceSelector struct {
@@ -76,9 +76,10 @@ type InterfaceSelector struct {
 	PrimaryNodeInterface *bool `json:"primaryNodeInterface,omitempty"`
 }
 
+// ClContainerSelector identifies a set of containers.
 type ClContainerSelector struct {
 	// namespace is an optional field and indicates the target Kubernetes
-	// namespace. If not provided, the default Kubernetes namespace is used.
+	// namespace. If not provided, all Kubernetes namespaces are included.
 	// +optional
 	Namespace string `json:"namespace,omitempty"`
 
@@ -88,15 +89,15 @@ type ClContainerSelector struct {
 	Pods metav1.LabelSelector `json:"pods"`
 
 	// containerNames is an optional field and is a list of container names in a
-	// pod to attach the eBPF program. If no names are  specified, all containers
+	// pod to attach the eBPF program. If no names are specified, all containers
 	// in the pod are selected.
 	// +optional
 	ContainerNames []string `json:"containerNames,omitempty"`
 }
 
-// ContainerSelector identifies a set of containers. It is different from ContainerSelector
+// ContainerSelector identifies a set of containers. It is different from ClContainerSelector
 // in that "Namespace" was removed. Namespace scoped programs can only attach to the namespace
-// they are created in, so namespace at this level doesn't apply.
+// they are created in.
 type ContainerSelector struct {
 	// pods is a required field and indicates the target pods. To select all pods
 	// use the standard metav1.LabelSelector semantics and make it empty.
@@ -264,8 +265,8 @@ type ByteCodeImage struct {
 	// When set to IfNotPresent, the given image will only be pulled if it is not
 	// present on the node.
 	//
-	// When set to Never, the given image will never be pulled and must be load on
-	// the node by some other means.
+	// When set to Never, the given image will never be pulled and must be
+	// loaded on the node by some other means.
 	// +optional
 	// +kubebuilder:default:=IfNotPresent
 	ImagePullPolicy PullPolicy `json:"imagePullPolicy,omitempty"`

apis/v1alpha1/uprobe_program_types.go

@@ -66,7 +66,7 @@ type UprobeAttachInfo struct {
 
 	// containers is an optional field that identifies the set of containers in
 	// which to attach the UProbe or URetProbe program. If containers is not
-	// specified, the eBPF program will be attached in the bpfman-agent container.
+	// specified, the eBPF program will be attached in the bpfman container.
 	// uprobe.
 	Containers ContainerSelector `json:"containers"`
 }