> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Nodes

> Manage Kubernetes cluster nodes with cordon, drain, and scheduling controls

Nodes are the worker machines that run containerized workloads. Manage node lifecycle, control scheduling, and configure taints and labels for workload placement.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Node" icon="hard-drive">
    A worker machine (physical or virtual) that runs pods.
  </Card>

  <Card title="Cordon" icon="lock">
    Mark a node as unschedulable to prevent new pods.
  </Card>

  <Card title="Drain" icon="droplet">
    Safely evict all pods before maintenance.
  </Card>

  <Card title="Taint" icon="ban">
    Prevent pods from scheduling unless they have matching tolerations.
  </Card>
</CardGroup>

## Required Permissions

| Action                | Permission                                    |
| --------------------- | --------------------------------------------- |
| View nodes            | `iam:project:infrastructure:kubernetes:read`  |
| Add/Remove nodes      | `iam:project:infrastructure:kubernetes:write` |
| Cordon/Drain/Uncordon | `iam:project:infrastructure:kubernetes:write` |
| Manage taints/labels  | `iam:project:infrastructure:kubernetes:write` |

## How to Add Nodes to a Cluster

<Steps>
  <Step title="Configure Nodes">
    First, configure nodes in cluster settings with hostname, IP, and role.
  </Step>

  <Step title="Click Add Node">
    Click **Add Node** in the header.
  </Step>

  <Step title="Select Nodes">
    Select available nodes from the list.
  </Step>

  <Step title="Join Nodes">
    Click **Add Selected** to join nodes to the cluster.
  </Step>
</Steps>

<Info>
  Nodes must be reachable via SSH and meet cluster requirements before joining.
</Info>

## How to Remove Nodes

<Steps>
  <Step title="Select Nodes">
    Use checkboxes to select nodes to remove.
  </Step>

  <Step title="Click Remove">
    Click **Remove**.
  </Step>

  <Step title="Confirm">
    Confirm removal. Nodes will be drained and removed.
  </Step>
</Steps>

<Warning>
  Ensure other nodes have capacity for evicted pods before removing nodes.
</Warning>

## How to Cordon a Node

Cordoning prevents new pods from being scheduled on a node. Existing pods continue running.

<Steps>
  <Step title="Find the Node">
    Locate the node in the list or detail page.
  </Step>

  <Step title="Click Cordon">
    Click **Cordon** from the actions menu.
  </Step>

  <Step title="Verify">
    The node shows a cordoned indicator.
  </Step>
</Steps>

## How to Drain a Node

Draining evicts all pods from a node before maintenance.

<Steps>
  <Step title="Find the Node">
    Locate the node to drain.
  </Step>

  <Step title="Click Drain">
    Click **Drain** from the actions menu.
  </Step>

  <Step title="Confirm">
    Confirm the drain operation.
  </Step>
</Steps>

**Drain behavior:**

* Regular pods are evicted and rescheduled
* DaemonSet pods are skipped
* Static pods are skipped
* Pods with local storage may fail without force flag

<Warning>
  Drain makes the node unschedulable. Use uncordon to allow scheduling again.
</Warning>

## How to Uncordon a Node

<Steps>
  <Step title="Find the Cordoned Node">
    Locate the node showing cordoned status.
  </Step>

  <Step title="Click Uncordon">
    Click **Uncordon** from the actions menu.
  </Step>

  <Step title="Verify">
    The node can now accept new pods.
  </Step>
</Steps>

## How to Add a Taint

Taints prevent pods from scheduling unless they have matching tolerations.

<Steps>
  <Step title="Open Node Detail">
    Click on a node to open details.
  </Step>

  <Step title="Click Add Taint">
    Click **Add Taint** in the Taints section.
  </Step>

  <Step title="Configure Taint">
    * **Key** - Taint identifier (e.g., `dedicated`, `gpu`)
    * **Value** - Optional value (e.g., `gpu-node`)
    * **Effect** - Scheduling behavior
  </Step>

  <Step title="Add">
    Click **Add Taint**.
  </Step>
</Steps>

**Taint effects:**

| Effect             | Description                                              |
| ------------------ | -------------------------------------------------------- |
| `NoSchedule`       | Pods without toleration won't be scheduled               |
| `PreferNoSchedule` | System tries to avoid scheduling pods without toleration |
| `NoExecute`        | Existing pods without toleration will be evicted         |

## How to Remove a Taint

<Steps>
  <Step title="Find the Taint">
    Locate the taint in the node detail page.
  </Step>

  <Step title="Click Remove">
    Click the delete icon on the taint.
  </Step>

  <Step title="Confirm">
    Confirm the removal.
  </Step>
</Steps>

## How to Add a Label

Labels help organize nodes and enable workload targeting.

<Steps>
  <Step title="Open Node Detail">
    Click on a node to open details.
  </Step>

  <Step title="Click Add Label">
    Click **Add Label** in the Labels section.
  </Step>

  <Step title="Configure Label">
    * **Key** - Label key (e.g., `environment`, `tier`)
    * **Value** - Label value (e.g., `production`, `frontend`)
  </Step>

  <Step title="Add">
    Click **Add Label**.
  </Step>
</Steps>

## How to Remove a Label

<Steps>
  <Step title="Find the Label">
    Locate the label badge in the node detail page.
  </Step>

  <Step title="Click Remove">
    Click on the label to remove it.
  </Step>

  <Step title="Confirm">
    Confirm the removal.
  </Step>
</Steps>

<Warning>
  Avoid removing system labels prefixed with `kubernetes.io/` or `node.kubernetes.io/` as they may affect cluster functionality.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Node shows NotReady status">
    * Check kubelet is running on the node
    * Verify network connectivity to control plane
    * Check node conditions for memory, disk, or PID pressure
    * Review kubelet logs
  </Accordion>

  <Accordion title="Drain operation fails">
    * Some pods may have PodDisruptionBudgets preventing eviction
    * Pods with local storage may not drain without force
    * Check drain summary for specific failures
  </Accordion>

  <Accordion title="Pods not scheduling on node">
    * Check if node is cordoned
    * Verify node has sufficient resources
    * Check for taints that may prevent scheduling
    * Ensure pods have matching tolerations
  </Accordion>

  <Accordion title="Cannot add taint or label">
    * Verify you have write permission
    * Check key format is valid
    * System labels may be protected
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between cordon and drain?">
    **Cordon** only marks the node as unschedulable. **Drain** both cordons AND evicts all pods.
  </Accordion>

  <Accordion title="What happens to pods when I drain?">
    Pods are gracefully terminated and rescheduled on other nodes. DaemonSet and static pods are skipped.
  </Accordion>

  <Accordion title="How do taints and tolerations work?">
    Taints on nodes repel pods. Tolerations on pods allow them to schedule on tainted nodes. A pod must tolerate all taints on a node to schedule there.
  </Accordion>

  <Accordion title="Can I remove a master node?">
    Yes, but ensure you have other masters for high availability. Removing the last master makes the cluster unavailable.
  </Accordion>
</AccordionGroup>