rename agent to worker and add documentation

Signed-off-by: Geoff Flarity <[email protected]>

Author: gflarity

operator/e2e_testing/setup/k8s_clusters.go

@@ -58,21 +58,22 @@ type NodeTaint struct {
 
 // NodeLabel represents a Kubernetes node label with its target node filters
 type NodeLabel struct {
-	Key         string   // Label key
-	Value       string   // Label value
+	Key   string // Label key
+	Value string // Label value
+	// k3s refers to worker nodes as agent nodes
 	NodeFilters []string // Node filters (e.g., "server:*", "agent:*", "server:0", "agent:1")
 }
 
 // ClusterConfig holds configuration for creating a k3d cluster
 type ClusterConfig struct {
 	Name             string      // Name of the k3d cluster
-	Servers          int         // Number of server/non-worker nodes
-	Agents           int         // Number of agent/worker nodes
+	ServerNodes      int         // Number of server (non-worker) nodes
+	WorkerNodes      int         // Number of worker nodes (called agents in k3s terminology)
 	Image            string      // Docker image to use for k3d cluster (e.g., "rancher/k3s:v1.28.8-k3s1")
 	HostPort         string      // Port on host to expose Kubernetes API (e.g., "6550")
 	LoadBalancerPort string      // Load balancer port mapping in format "hostPort:containerPort" (e.g., "8080:80")
 	NodeLabels       []NodeLabel // Kubernetes labels to apply with specific node filters
-	AgentNodeTaints  []NodeTaint // Taints to apply to agent nodes
+	WorkerNodeTaints []NodeTaint // Taints to apply to worker nodes
 	WorkerMemory     string      // Memory allocation for worker/agent nodes (e.g., "150m")
 	EnableRegistry   bool        // Enable built-in Docker registry
 	RegistryPort     string      // Port for the Docker registry (e.g., "5001")
@@ -82,8 +83,8 @@ type ClusterConfig struct {
 func DefaultClusterConfig() ClusterConfig {
 	return ClusterConfig{
 		Name:             "test-k3d-cluster",
-		Servers:          1,
-		Agents:           2,
+		ServerNodes:      1,
+		WorkerNodes:      2,
 		Image:            "rancher/k3s:v1.28.8-k3s1",
 		HostPort:         "6550",
 		LoadBalancerPort: "8080:80",
@@ -126,8 +127,9 @@ func SetupCompleteK3DCluster(ctx context.Context, cfg ClusterConfig, skaffoldYAM
 		{
 			"key":      "node_role.e2e.grove.nvidia.com",
 			"operator": "Equal",
-			"value":    "agent",
-			"effect":   "NoSchedule",
+			// k3s refers to worker nodes as agent nodes
+			"value":  "agent",
+			"effect": "NoSchedule",
 		},
 	}
 
@@ -227,9 +229,10 @@ func SetupK3DCluster(ctx context.Context, cfg ClusterConfig, logger *logrus.Logg
 		ObjectMeta: types.ObjectMeta{
 			Name: cfg.Name,
 		},
-		Servers: cfg.Servers,
-		Agents:  cfg.Agents,
-		Image:   cfg.Image,
+		Servers: cfg.ServerNodes,
+		// k3s calls these agents, but we call them worker nodes
+		Agents: cfg.WorkerNodes,
+		Image:  cfg.Image,
 		ExposeAPI: v1alpha5.SimpleExposureOpts{
 			Host:     "0.0.0.0",
 			HostPort: cfg.HostPort,
@@ -242,6 +245,7 @@ func SetupK3DCluster(ctx context.Context, cfg ClusterConfig, logger *logrus.Logg
 		},
 		Options: v1alpha5.SimpleConfigOptions{
 			Runtime: v1alpha5.SimpleConfigOptionsRuntime{
+				// worker node memory
 				AgentsMemory: cfg.WorkerMemory,
 			},
 		},
@@ -258,12 +262,13 @@ func SetupK3DCluster(ctx context.Context, cfg ClusterConfig, logger *logrus.Logg
 		)
 	}
 
-	// Apply agent node taints if specified
-	for _, taint := range cfg.AgentNodeTaints {
+	// Apply worker node taints if specified
+	for _, taint := range cfg.WorkerNodeTaints {
 		clusterConfig.Options.K3sOptions.ExtraArgs = append(
 			clusterConfig.Options.K3sOptions.ExtraArgs,
 			v1alpha5.K3sArgWithNodeFilters{
-				Arg:         fmt.Sprintf("--node-taint=%s=%s:%s", taint.Key, taint.Value, taint.Effect),
+				Arg: fmt.Sprintf("--node-taint=%s=%s:%s", taint.Key, taint.Value, taint.Effect),
+				// k3s refers to worker nodes as agent nodes
 				NodeFilters: []string{"agent:*"},
 			},
 		)
@@ -297,8 +302,8 @@ func SetupK3DCluster(ctx context.Context, cfg ClusterConfig, logger *logrus.Logg
 	}
 
 	// Create cluster
-	logger.Debugf("🚀 Creating cluster '%s' with %d server(s) and %d agent(s)...",
-		k3dConfig.Name, cfg.Servers, cfg.Agents)
+	logger.Debugf("🚀 Creating cluster '%s' with %d server(s) and %d worker node(s)...",
+		k3dConfig.Name, cfg.ServerNodes, cfg.WorkerNodes)
 
 	if err := client.ClusterRun(ctx, runtimes.Docker, k3dConfig); err != nil {
 		return nil, cleanup, fmt.Errorf("failed to create cluster: %w", err)

operator/e2e_testing/setup/shared_cluster.go

@@ -43,7 +43,7 @@ type SharedClusterManager struct {
 	cleanup                  func()
 	logger                   *logrus.Logger
 	isSetup                  bool
-	agentNodes               []string
+	workerNodes              []string
 	registryPort             string
 	relativeSkaffoldYAMLPath string
 }
@@ -70,11 +70,11 @@ func (scm *SharedClusterManager) Setup(ctx context.Context, testImages []string)
 		return nil
 	}
 
-	// Configuration for maximum cluster size needed (28 agents + 3 servers)
+	// Configuration for maximum cluster size needed (28 worker nodes + 3 server nodes)
 	customCfg := ClusterConfig{
 		Name:             "shared-e2e-test-cluster",
-		Servers:          3,
-		Agents:           28,     // Maximum needed across all tests
+		ServerNodes:      3,
+		WorkerNodes:      28,     // Maximum needed across all tests
 		WorkerMemory:     "150m", // 150m memory per agent node to fit one workload pod
 		Image:            "rancher/k3s:v1.33.5-k3s1",
 		HostPort:         "6560", // Use a different port to avoid conflicts
@@ -83,20 +83,23 @@ func (scm *SharedClusterManager) Setup(ctx context.Context, testImages []string)
 		RegistryPort:     "5001",
 		NodeLabels: []NodeLabel{
 			{
-				Key:         "node_role.e2e.grove.nvidia.com",
+				Key: "node_role.e2e.grove.nvidia.com",
+				// k3s refers to worker nodes as agent nodes
 				Value:       "agent",
 				NodeFilters: []string{"agent:*"},
 			},
 			// we currently don't want GPUs in e2e tests as validator is causing issues
 			{
-				Key:         "nvidia.com/gpu.deploy.operands",
-				Value:       "false",
+				Key:   "nvidia.com/gpu.deploy.operands",
+				Value: "false",
+				// k3s refers to worker nodes as agent nodes
 				NodeFilters: []string{"server:*", "agent:*"},
 			},
 		},
-		AgentNodeTaints: []NodeTaint{
+		WorkerNodeTaints: []NodeTaint{
 			{
-				Key:    "node_role.e2e.grove.nvidia.com",
+				Key: "node_role.e2e.grove.nvidia.com",
+				// k3s refers to worker nodes as agent nodes
 				Value:  "agent",
 				Effect: "NoSchedule",
 			},
@@ -137,41 +140,41 @@ func (scm *SharedClusterManager) Setup(ctx context.Context, testImages []string)
 		return fmt.Errorf("failed to setup registry test images: %w", err)
 	}
 
-	// Get list of agent nodes for cordoning management
+	// Get list of worker nodes for cordoning management
 	nodes, err := clientset.CoreV1().Nodes().List(ctx, metav1.ListOptions{})
 	if err != nil {
 		cleanup()
 		return fmt.Errorf("failed to list nodes: %w", err)
 	}
 
-	scm.agentNodes = make([]string, 0)
+	scm.workerNodes = make([]string, 0)
 	for _, node := range nodes.Items {
 		if _, isServer := node.Labels["node-role.kubernetes.io/control-plane"]; !isServer {
-			scm.agentNodes = append(scm.agentNodes, node.Name)
+			scm.workerNodes = append(scm.workerNodes, node.Name)
 		}
 	}
 
-	scm.logger.Infof("✅ Shared cluster setup complete with %d agent nodes", len(scm.agentNodes))
+	scm.logger.Infof("✅ Shared cluster setup complete with %d worker nodes", len(scm.workerNodes))
 	scm.isSetup = true
 	return nil
 }
 
 // PrepareForTest prepares the cluster for a specific test by cordoning the appropriate nodes
-func (scm *SharedClusterManager) PrepareForTest(ctx context.Context, requiredAgents int) error {
+func (scm *SharedClusterManager) PrepareForTest(ctx context.Context, requiredWorkerNodes int) error {
 	if !scm.isSetup {
 		return fmt.Errorf("shared cluster not setup")
 	}
 
 	// First, uncordon all nodes to reset state
-	for _, nodeName := range scm.agentNodes {
+	for _, nodeName := range scm.workerNodes {
 		if err := utils.CordonNode(ctx, scm.clientset, nodeName, false); err != nil {
 			return fmt.Errorf("failed to uncordon node %s: %w", nodeName, err)
 		}
 	}
 
 	// Cordon nodes that are not needed for this test
-	if requiredAgents < len(scm.agentNodes) {
-		nodesToCordon := scm.agentNodes[requiredAgents:]
+	if requiredWorkerNodes < len(scm.workerNodes) {
+		nodesToCordon := scm.workerNodes[requiredWorkerNodes:]
 		for _, nodeName := range nodesToCordon {
 			if err := utils.CordonNode(ctx, scm.clientset, nodeName, true); err != nil {
 				return fmt.Errorf("failed to cordon node %s: %w", nodeName, err)
@@ -276,9 +279,9 @@ func (scm *SharedClusterManager) listRemainingPods(ctx context.Context, namespac
 	}
 }
 
-// resetNodeStates uncordons all agent nodes to reset cluster state
+// resetNodeStates uncordons all worker nodes to reset cluster state
 func (scm *SharedClusterManager) resetNodeStates(ctx context.Context) error {
-	for _, nodeName := range scm.agentNodes {
+	for _, nodeName := range scm.workerNodes {
 		if err := utils.CordonNode(ctx, scm.clientset, nodeName, false); err != nil {
 			scm.logger.Warnf("failed to uncordon node %s: %v", nodeName, err)
 			return fmt.Errorf("failed to uncordon node %s: %w", nodeName, err)
@@ -406,9 +409,9 @@ func (scm *SharedClusterManager) GetRegistryPort() string {
 	return scm.registryPort
 }
 
-// GetAgentNodes returns the list of agent node names
-func (scm *SharedClusterManager) GetAgentNodes() []string {
-	return scm.agentNodes
+// GetWorkerNodes returns the list of worker node names
+func (scm *SharedClusterManager) GetWorkerNodes() []string {
+	return scm.workerNodes
 }
 
 // IsSetup returns whether the shared cluster is setup

operator/e2e_testing/tests/gang_scheduling_test.go

@@ -41,20 +41,20 @@ func Test_GS1_GangSchedulingWithFullReplicas(t *testing.T) {
 	clientset, restConfig, _, cleanup, _ := setupTestCluster(ctx, t, 10)
 	defer cleanup()
 
-	// Get agent (worker) nodes for cordoning
-	agentNodes, err := getAgentNodes(ctx, clientset)
+	// Get worker nodes for cordoning
+	workerNodes, err := getWorkerNodes(ctx, clientset)
 	if err != nil {
-		t.Fatalf("Failed to get agent nodes: %v", err)
+		t.Fatalf("Failed to get worker nodes: %v", err)
 	}
 
-	if len(agentNodes) < 1 {
-		t.Fatalf("Need at least 1 agent node to cordon, but found %d", len(agentNodes))
+	if len(workerNodes) < 1 {
+		t.Fatalf("Need at least 1 worker node to cordon, but found %d", len(workerNodes))
 	}
 
-	agentNodeToCordon := agentNodes[0]
-	logger.Debugf("🚫 Cordoning agent node: %s", agentNodeToCordon)
-	if err := utils.CordonNode(ctx, clientset, agentNodeToCordon, true); err != nil {
-		t.Fatalf("Failed to cordon node %s: %v", agentNodeToCordon, err)
+	workerNodeToCordon := workerNodes[0]
+	logger.Debugf("🚫 Cordoning worker node: %s", workerNodeToCordon)
+	if err := utils.CordonNode(ctx, clientset, workerNodeToCordon, true); err != nil {
+		t.Fatalf("Failed to cordon node %s: %v", workerNodeToCordon, err)
 	}
 
 	logger.Info("2. Deploy workload WL1, and verify 10 newly created pods")
@@ -91,8 +91,8 @@ func Test_GS1_GangSchedulingWithFullReplicas(t *testing.T) {
 	}
 
 	logger.Info("4. Uncordon the node and verify all pods get scheduled")
-	if err := utils.CordonNode(ctx, clientset, agentNodeToCordon, false); err != nil {
-		t.Fatalf("Failed to uncordon node %s: %v", agentNodeToCordon, err)
+	if err := utils.CordonNode(ctx, clientset, workerNodeToCordon, false); err != nil {
+		t.Fatalf("Failed to uncordon node %s: %v", workerNodeToCordon, err)
 	}
 
 	// Wait for all pods to be scheduled and ready
@@ -108,7 +108,7 @@ func Test_GS1_GangSchedulingWithFullReplicas(t *testing.T) {
 		t.Fatalf("Failed to list workload pods: %v", err)
 	}
 
-	// Verify that each pod is scheduled on a unique node, agent nodes have 150m memory
+	// Verify that each pod is scheduled on a unique node, worker nodes have 150m memory
 	// and workload pods requests 80m memory, so only 1 should fit per node
 	assertPodsOnDistinctNodes(t, pods.Items)
 

operator/e2e_testing/tests/main_test.go

@@ -104,10 +104,10 @@ func TestMain(m *testing.M) {
 }
 
 // setupTestCluster initializes a shared Kubernetes cluster for testing.
-// It creates the cluster if needed, ensures the required number of agent nodes are available,
+// It creates the cluster if needed, ensures the required number of worker nodes are available,
 // and returns K8s clients along with a cleanup function and registry port.
 // The cleanup function removes workloads and optionally tears down the cluster for individual test runs.
-func setupTestCluster(ctx context.Context, t *testing.T, requiredAgents int) (*kubernetes.Clientset, *rest.Config, dynamic.Interface, func(), string) {
+func setupTestCluster(ctx context.Context, t *testing.T, requiredWorkerNodes int) (*kubernetes.Clientset, *rest.Config, dynamic.Interface, func(), string) {
 	// Always use shared cluster approach
 	sharedCluster := setup.SharedCluster(logger, "../../skaffold.yaml")
 
@@ -118,7 +118,7 @@ func setupTestCluster(ctx context.Context, t *testing.T, requiredAgents int) (*k
 		}
 	}
 
-	if err := sharedCluster.PrepareForTest(ctx, requiredAgents); err != nil {
+	if err := sharedCluster.PrepareForTest(ctx, requiredWorkerNodes); err != nil {
 		t.Errorf("Failed to prepare shared cluster for test: %v", err)
 	}
 
@@ -139,22 +139,22 @@ func setupTestCluster(ctx context.Context, t *testing.T, requiredAgents int) (*k
 	return clientset, restConfig, dynamicClient, cleanup, sharedCluster.GetRegistryPort()
 }
 
-// getAgentNodes retrieves the names of all agent (worker) nodes in the cluster,
+// getWorkerNodes retrieves the names of all worker nodes in the cluster,
 // excluding control plane nodes. Returns an error if the node list cannot be retrieved.
-func getAgentNodes(ctx context.Context, clientset kubernetes.Interface) ([]string, error) {
+func getWorkerNodes(ctx context.Context, clientset kubernetes.Interface) ([]string, error) {
 	nodes, err := clientset.CoreV1().Nodes().List(ctx, metav1.ListOptions{})
 	if err != nil {
 		return nil, fmt.Errorf("failed to list nodes: %w", err)
 	}
 
-	agentNodes := make([]string, 0)
+	workerNodes := make([]string, 0)
 	for _, node := range nodes.Items {
 		if _, isServer := node.Labels["node-role.kubernetes.io/control-plane"]; !isServer {
-			agentNodes = append(agentNodes, node.Name)
+			workerNodes = append(workerNodes, node.Name)
 		}
 	}
 
-	return agentNodes, nil
+	return workerNodes, nil
 }
 
 // assertPodsOnDistinctNodes asserts that the pods are scheduled on distinct nodes and fails the test if not.