> ## 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.

# Clusters

> Create and manage Kubernetes clusters with automated provisioning

Kubernetes clusters are the foundation of your container infrastructure. Configure cluster settings, provision nodes, and manage the complete cluster lifecycle.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Cluster" icon="server">
    A Kubernetes cluster with control plane and worker nodes.
  </Card>

  <Card title="Build" icon="play">
    Automated provisioning that installs Kubernetes components on nodes.
  </Card>

  <Card title="Reset" icon="rotate">
    Complete cluster teardown that removes all configurations.
  </Card>

  <Card title="Upgrade" icon="arrow-up">
    Rolling update of Kubernetes and component versions.
  </Card>
</CardGroup>

## Required Permissions

| Action               | Permission                                     |
| -------------------- | ---------------------------------------------- |
| View clusters        | `iam:project:infrastructure:kubernetes:read`   |
| Create/Edit clusters | `iam:project:infrastructure:kubernetes:write`  |
| Delete clusters      | `iam:project:infrastructure:kubernetes:delete` |

## How to Create a Cluster

<Steps>
  <Step title="Click Add Cluster">
    Click the **Add Cluster** button.
  </Step>

  <Step title="Configure Basic Settings">
    * **Cluster Name** - Unique identifier
    * **Cluster Domain** - DNS domain (e.g., `cluster.local`)
  </Step>

  <Step title="Configure Versions">
    * **K8s Version** - Select Kubernetes version
    * **Runtime** - Container runtime (containerd)
    * **Runtime Version** - Specific runtime version
  </Step>

  <Step title="Configure Networking">
    * **Pod Network** - CIDR for pod IPs (e.g., `10.244.0.0/16`)
    * **Service Network** - CIDR for services (e.g., `10.96.0.0/12`)
    * **CNI Plugin** - Network plugin (Calico, Cilium, etc.)
  </Step>

  <Step title="Configure Options">
    * **Proxy Mode** - iptables (default) or ipvs
    * **CGroup Driver** - systemd (recommended) or cgroupfs
    * **Metrics Server** - Enable for resource monitoring
  </Step>

  <Step title="Create">
    Click **Create Cluster** to save the configuration.
  </Step>
</Steps>

<Info>
  Creating a cluster only saves the configuration. Run the **Build** operation to provision Kubernetes on the nodes.
</Info>

## How to Build a Cluster

Building installs Kubernetes components on all configured nodes.

<Steps>
  <Step title="Open Cluster">
    Click on the cluster to open details.
  </Step>

  <Step title="Click Build">
    Click **Build** in the Operations section.
  </Step>

  <Step title="Review Node Readiness">
    The wizard checks all nodes for:

    * SSH connectivity
    * OS compatibility
    * Disk, memory, and CPU availability
    * Required ports
  </Step>

  <Step title="Review Configuration">
    Verify Kubernetes version, runtime, CNI plugin, and node distribution.
  </Step>

  <Step title="Start Build">
    Click **Start Build** to begin provisioning.
  </Step>
</Steps>

<Warning>
  Build will fail if any node has critical issues. Resolve blockers before attempting to build.
</Warning>

## How to Reset a Cluster

Resetting removes all Kubernetes configurations and returns nodes to clean state.

<Steps>
  <Step title="Open Cluster">
    Click on the cluster to open details.
  </Step>

  <Step title="Click Reset">
    Click **Reset** in the Operations section.
  </Step>

  <Step title="Review Impact">
    The wizard shows affected resources:

    * Running workloads (pods, deployments)
    * Storage (PVs, PVCs)
    * Network resources (services, ingresses)
    * Configuration (configmaps, secrets)
  </Step>

  <Step title="Complete Safety Checklist">
    Acknowledge that:

    * Data has been backed up
    * Workloads will be terminated
    * Storage data will be lost
    * Action is irreversible
  </Step>

  <Step title="Confirm Reset">
    Type the cluster name to confirm.
  </Step>
</Steps>

<Warning>
  Reset is irreversible. All workloads, configurations, and persistent data will be permanently deleted.
</Warning>

## How to Upgrade a Cluster

<Steps>
  <Step title="Open Cluster">
    Click on the cluster to open details.
  </Step>

  <Step title="Click Upgrade">
    Click **Upgrade** in the Operations section.
  </Step>

  <Step title="Select Target Versions">
    Choose target versions for Kubernetes and components.
  </Step>

  <Step title="Execute Upgrade">
    The upgrade performs a rolling update to minimize downtime.
  </Step>
</Steps>

<Info>
  Upgrade is only available for clusters in Ready state.
</Info>

## How to Delete a Cluster

<Steps>
  <Step title="Find the Cluster">
    Locate the cluster in the list.
  </Step>

  <Step title="Click Delete">
    Click the delete icon.
  </Step>

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

<Warning>
  Deleting a cluster configuration does not reset the nodes. Run **Reset** first to clean up nodes before deleting.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Build fails with node readiness errors">
    * Check SSH connectivity to all nodes
    * Verify nodes meet minimum resource requirements
    * Ensure required ports are not in use
    * Check OS compatibility
  </Accordion>

  <Accordion title="Cluster shows Not Ready after build">
    * Check operation logs for errors
    * Verify network connectivity between nodes
    * Ensure CNI plugin installed correctly
    * Check control plane component logs
  </Accordion>

  <Accordion title="Cannot connect to cluster">
    * Verify API server is running
    * Check network connectivity to master nodes
    * Ensure kubeconfig is correct
    * Verify certificates are valid
  </Accordion>

  <Accordion title="Reset operation hangs">
    * Check operation logs for specific errors
    * Verify SSH connectivity to all nodes
    * Some resources may have finalizers preventing deletion
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between creating and building?">
    **Creating** saves the cluster configuration. **Building** actually provisions Kubernetes on the nodes. You must create first, then build.
  </Accordion>

  <Accordion title="Can I change Kubernetes version after building?">
    Use the **Upgrade** operation to change versions. Major version changes may require reset and rebuild.
  </Accordion>

  <Accordion title="What happens to data when I reset?">
    All data is permanently deleted including PersistentVolumes, ConfigMaps, Secrets, and container data.
  </Accordion>

  <Accordion title="Should I use iptables or ipvs proxy mode?">
    **iptables** is the default and works for most clusters. **ipvs** provides better performance for large clusters with 1000+ services.
  </Accordion>

  <Accordion title="What is Strict ARP mode?">
    Required for MetalLB Layer 2 mode. Prevents nodes from responding to ARP requests for IPs they don't own.
  </Accordion>
</AccordionGroup>