---
title: Node Affinity
sidebar_label: Node Affinity
description: Control workload scheduling within a Private Cluster by organizing nodes into groups and applying affinity-based scheduling rules.
displayed_sidebar: tirSideBar
---

# Node Affinity

By default, workloads in a Private Cluster are scheduled automatically. Node Affinity gives you control over that decision. You can define exactly which nodes a workload should be scheduled to, or which ones it should avoid, without changing how the workload itself is configured.

> In short: group your nodes, set a rule, and the scheduler does the rest.

---

## 1. Node Groups

A node group is a user-defined label applied to a set of cluster nodes, used as a scheduling target. Once created, you can reference a group in any workload's scheduling configuration.

### What this means in practice

| Capability | Benefit |
|------------|---------|
| **Logical grouping** | Organize nodes by purpose — GPU-heavy training, lightweight inference, or staging environments. |
| **Reusability** | Define a group once and apply it across multiple workloads. |
| **Flexibility** | Add or remove nodes from a group at any time to reflect changes in cluster layout. |

**Example node group names:**

- `gpu-nodes-1` — dedicated high-memory GPU nodes
- `worker-1` — general compute nodes
- `testing-workers` — isolated nodes for experimental workloads
- `high-workload-nodes` — nodes reserved for resource-intensive jobs

---

## 2. Scheduling Rules

When creating or configuring a workload, you can optionally assign a scheduling rule through the **Affinity Group** section. If no rule is selected, the scheduler uses default placement logic with no affinity constraints.

| Rule | Behaviour |
|------|-----------|
| **All Nodes** | The workload can run on any available node in the cluster. |
| **Affinity** | The workload runs only on nodes in the selected group. |
| **Anti-Affinity** | The workload avoids nodes in the selected group. |

---

## 3. Managing Node Groups

### Node Groups Page

The **Node Groups** page gives you a full view of how your cluster nodes are organized.

| Field | Description |
|-------|-------------|
| **Total Nodes** | Total number of nodes available in the selected cluster. |
| **Total Groups** | Number of node groups currently defined. |
| **Search** | Quickly find a group by name. |
| **Group List** | Browse all existing groups along with their assigned nodes and available actions. |

When no groups have been created yet, the page shows an empty state with an option to create your first group.

---

### Create a Node Group

1. Go to the **Node Groups** page.
2. Select **New group**.
3. Enter a **Group name**.
4. Use node search to find and select one or more nodes.
5. Confirm to create the group.

---

### View Node Groups

Each group card gives you an at-a-glance summary:

| Field | Description |
|-------|-------------|
| **Group name** | The name used to identify and reference this group in workload configurations. |
| **Assigned nodes** | Count of nodes currently in the group. |
| **Edit** | Update the group name or its node membership. |
| **Delete** | Remove the group when it is no longer needed. |

---

### Edit a Node Group

Use **Edit** to rename a group or change which nodes belong to it.

:::warning
Changes to a node group are **not applied to instances that are already running**. To apply updated affinity settings, remove the affinity rule from the instance, update the group, then reapply the rule to trigger rescheduling.
:::

---

### Delete a Node Group

Use **Delete** to remove a node group that is no longer needed.

:::tip
A node group that is currently referenced by a running workload cannot be deleted. Remove the affinity rule from all active workloads first.
:::

---

## Best Practices

- **Name groups by purpose**, not by node ID — e.g., `inference-nodes` is easier to maintain than `node-3-4-7`.
- **Use Affinity** when you need guaranteed hardware placement for GPU-specific or high-memory workloads.
- **Use Anti-Affinity** to separate stable production workloads from experimental or bursty jobs on the same cluster.
- **Keep groups small and specific** — broad groups reduce the benefit of affinity-based scheduling.
- Before editing a group, **check which workloads reference it** to avoid unintended scheduling side effects.

---