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

# Getting Started

> A guide to setting up a Talos cluster

export const VersionWarningBanner = () => {
  const latestVersion = "v1.13";
  const [latestUrl, setLatestUrl] = useState(null);
  const [currentVersion, setCurrentVersion] = useState(null);
  const [isBeta, setIsBeta] = useState(false);
  const parseVersion = v => v.replace("v", "").split(".").map(Number);
  const isGreaterVersion = (a, b) => {
    const [aMajor, aMinor] = parseVersion(a);
    const [bMajor, bMinor] = parseVersion(b);
    if (aMajor > bMajor) return true;
    if (aMajor === bMajor && aMinor > bMinor) return true;
    return false;
  };
  useEffect(() => {
    if (typeof window === "undefined") return;
    const {pathname, hash, search} = window.location;
    const match = pathname.match(/\/talos\/(v\d+\.\d+)\//);
    if (!match) return;
    const detectedVersion = match[1];
    if (detectedVersion === latestVersion) return;
    setCurrentVersion(detectedVersion);
    if (isGreaterVersion(detectedVersion, latestVersion)) {
      setIsBeta(true);
    }
    const newPath = pathname.replace(`/talos/${detectedVersion}/`, `/talos/${latestVersion}/`);
    setLatestUrl(`${newPath}${search}${hash}`);
  }, []);
  if (!latestUrl || !currentVersion) return null;
  return <div className="not-prose sticky top-6 z-50 my-6">
      <div className="border border-yellow-500/30 bg-yellow-500/10 px-4 py-3 rounded-xl">
        <div className="text-sm">
          {isBeta ? <>
              ⚠️ You are viewing a <strong>beta version</strong> of Talos ({currentVersion}).
              This version may be unstable.
              <a href={latestUrl} className="ml-2 underline text-yellow-400 hover:text-yellow-300 font-medium">
                View latest stable version {latestVersion} →
              </a>
            </> : <>
              ⚠️ You are viewing an older version of Talos ({currentVersion}).
              <a href={latestUrl} className="ml-2 underline text-yellow-400 hover:text-yellow-300 font-medium">
                View the latest version {latestVersion} →
              </a>
            </>}
        </div>
      </div>
    </div>;
};

<VersionWarningBanner />

This guide walks you through creating a simple Talos cluster with one control plane node and one or more worker nodes.

If you're looking to set up a cluster with multiple control plane nodes, see [Production Notes](./prodnotes).

**New to Talos?** Start with [Quickstart](./quickstart) to create a local virtual cluster on your workstation.

**Planning for production?** See [Production Notes](./prodnotes) for additional requirements and best practices.

**Installing on cloud or virtualized platforms?** Check out the [platform-specific guides](../platform-specific-installations) for installation methods tailored to different environments.

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/VKfE5BuqlSc" title="Create a bare metal Kubernetes cluster" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## Prerequisites

To create a Kubernetes cluster with Talos, you’ll need to:

* **Install talosctl**: `talosctl` is the CLI tool used to interact with the Talos API.
  Since Talos Linux does not have SSH access, `talosctl` is the primary tool for managing and configuring your Talos machines

  You can install `talosctl` on macOS or Linux by running:

```bash theme={null}
brew install siderolabs/tap/talosctl
```

Refer to the [talosctl installation guide](./talosctl) for installation on other platforms.

* **Ensure network access**: Your machines will need internet access to download the Talos installer and container images, sync time, and more.

  If you’re working in a restricted network environment, check out the official documentation on using [registry proxies](../configure-your-talos-cluster/images-container-runtime/pull-through-cache), local registries, or setting up an [air-gapped installation](../platform-specific-installations/air-gapped).

## Talos cluster setup overview

Every Talos cluster follows the same process, regardless of where you deploy it:

1. **Boot** - Start machines with the Talos Linux image
2. **Configure** - Create a root of trust certificate authority and generate configuration files
3. **Apply** - Apply machine configurations to the nodes
4. **Connect** - Set up your local `talosctl` client
5. **Bootstrap** - Initialize the Kubernetes cluster.

**Note**: You can also use [Omni](https://www.siderolabs.com/omni-signup/) to create a Talos cluster that spans multiple platforms, including bare metal, cloud providers, and virtual machines.

Let's walk through each step and create a Talos cluster.

## Step 1: Download the Talos Linux image

Get the latest ISO for your architecture from our [Image factory](https://factory.talos.dev/).

## Step 2: Boot your machine

Boot your hardware using the ISO you just downloaded.
At this stage, you'll:

* Boot one machine as your control plane node.
* Boot additional machines as worker nodes (this is optional).

You’ll see the Talos dashboard once your hardware boots from the ISO image.

**Note:** The ISO runs entirely in RAM and won't modify your disks until you apply a configuration.

**Troubleshooting network connectivity:** If your machine fails to establish a network connection after booting, you may need to add network drivers through system extensions.
Add these extensions to your Talos image via the [Image factory](https://factory.talos.dev/), or see the [system extensions repository](https://github.com/siderolabs/extensions) for more information.

## Step 3: Store your node IP addresses in a variable

To create variables for your machines’ IP addresses:

1. Copy the IP address displayed on each machine console, including the control plane and any worker nodes you’ve created.

   If you don’t have a display connected, retrieve the IP addresses from your DHCP server.

2. Create a variable for your control plane node’s IP address by replacing `<your-control-plane-ip>` with the actual IP:

   ```bash theme={null}
   export CONTROL_PLANE_IP=<your-control-plane-ip>
   ```

3. If you have worker nodes, store their IP addresses in a Bash array.
   Replace each `<worker-ip>` placeholder with the actual IP address of a worker node.
   You can include as many IP addresses as needed:

   ```bash theme={null}
   WORKER_IP=("<worker-ip-1>" "<worker-ip-2>" "<worker-ip-3>"...)
   ```

## Step 4: Unmount the ISO

Unplug your installation USB drive or unmount the ISO.
This prevents you from accidentally installing to the USB drive and makes it clearer which disk to select for installation.

## Step 5: Learn about your installation disks

When you first boot your machine from the ISO, Talos runs temporarily in memory.
This means that your Talos nodes, configurations, and cluster membership won't survive reboots or power cycles.

However, once you apply the machine configuration (which you'll do later in this guide), you'll install Talos, its complete operating system, and your configuration to a specified disk for permanent storage.

Run this command to view all the available disks on your control plane:

```bash theme={null}
talosctl get disks --insecure --nodes $CONTROL_PLANE_IP
```

Note the disk ID (e.g., `sda`, `vda`) as you will use it in the next step.

## Step 6: Generate cluster configuration

Talos Linux is configured entirely using declarative configuration files avoiding the need to deal with SSH and running commands.

To generate these declarative configuration files:

1. Define variables for your cluster name and the disk ID from step 5.
   Replace the placeholders with your actual values:

   ```bash theme={null}
   export CLUSTER_NAME=<cluster_name>
   export DISK_NAME=<control_plane_disk_name>
   ```

2. Run this command to generate the configuration file:

   ```bash theme={null}
   talosctl gen config $CLUSTER_NAME https://$CONTROL_PLANE_IP:6443 --install-disk /dev/$DISK_NAME
   ```

This command generates machine configurations that specify the Kubernetes API endpoint (which is your control plane node's IP) for cluster communication and the target disk for the Talos installation.

You'll get three files from this command:

* **controlplane.yaml**: The configuration for your control plane.
* **worker.yaml**: The configuration for your worker nodes.
* **talosconfig**: Your `talosctl` configuration file, used to connect to and authenticate access to your cluster.

## Step 7: Apply configurations

Now that you've created your configurations, it's time to apply them to bring your nodes and cluster online:

1. Run this command to apply the control plane configuration:

   ```bash theme={null}
   talosctl apply-config --insecure --nodes $CONTROL_PLANE_IP --file controlplane.yaml
   ```

2. Next, apply the worker node configuration:

   ```bash theme={null}
   for ip in "${WORKER_IP[@]}"; do
       echo "Applying config to worker node: $ip"
       talosctl apply-config --insecure --nodes "$ip" --file worker.yaml
   done
   ```

## Step 8: Set your endpoints

<Info>An endpoint is a control plane node or [Omni](../../../omni/getting-started/getting-started) domain. You can read more about the architecture [here](../learn-more/talosctl).</Info>

Set your endpoints with this:

```bash theme={null}
talosctl --talosconfig=./talosconfig config endpoints $CONTROL_PLANE_IP
```

## Step 9: Bootstrap your etcd cluster

Wait for your control plane node to finish booting, then bootstrap your etcd cluster by running:

```bash theme={null}
talosctl bootstrap --nodes $CONTROL_PLANE_IP --talosconfig=./talosconfig
```

**Note:** Run this command ONCE on a SINGLE control plane node.
If you have multiple control plane nodes, you can choose any of them.

## Step 10: Get Kubernetes access

Download your `kubeconfig` file to start using `kubectl`.

You have two download options: you can either merge your Kubernetes configurations **OR** keep them separate.

Here’s how to do both:

* Merge your new cluster into your local Kubernetes configuration:

```bash theme={null}
talosctl kubeconfig --nodes $CONTROL_PLANE_IP --talosconfig=./talosconfig
```

* Specify a filename if you prefer not to merge with your default Kubernetes configuration:

```bash theme={null}
talosctl kubeconfig alternative-kubeconfig --nodes $CONTROL_PLANE_IP --talosconfig=./talosconfig
export KUBECONFIG=./alternative-kubeconfig

```

## Step 11: Check cluster health

Run the following command to check the health of your nodes:

```bash theme={null}
talosctl --nodes $CONTROL_PLANE_IP --talosconfig=./talosconfig health
```

## Step 12: Verify node registration

Confirm that your nodes are registered in Kubernetes:

```bash theme={null}
kubectl get nodes
```

You should see your control plane and worker nodes listed with a **Ready** status.

## Next steps

Congratulations!
You now have a working Kubernetes cluster on Talos Linux.

For a list of all the commands and operations that `talosctl` provides, see the CLI reference.

### What's next?

* [Set up persistent storage](../../../kubernetes-guides/csi/storage)
* [Deploy a Metrics Server](../../../kubernetes-guides/monitoring-and-observability/deploy-metrics-server)
* [Explore the talosctl CLI reference](../reference/cli)
* [Plan your production deployment](./prodnotes)