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

# VirtualBox

> Creating Talos Kubernetes cluster using VirtualBox VMs.

export const release_v1_13 = 'v1.13.0';

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 />

In this guide we will create a Kubernetes cluster using VirtualBox.

## Video walkthrough

To see a live demo of this writeup, visit Youtube here:

<iframe width="560" height="315" src="https://www.youtube.com/embed/bIszwavcBiU" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

## Installation

### How to get VirtualBox

Install VirtualBox with your operating system package manager or from the [website](https://www.virtualbox.org/).
For example, on Ubuntu for x86:

```bash theme={null}
apt install virtualbox
```

### Install talosctl

You can download `talosctl` on MacOS and Linux via:

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

For manual installation and other platforms please see the [talosctl installation guide](../../getting-started/talosctl).

### Download ISO image

Download the ISO image from [Image Factory](https://www.talos.dev/latest/talos-guides/install/boot-assets/#image-factory).

```bash theme={null}
mkdir -p _out/
curl https://factory.talos.dev/image/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba/<version>/metal-<arch>.iso -L -o _out/metal-<arch>.iso
```

For example version \${release_v1_13} for `linux` platform:

<CodeBlock lang="sh">
  {`
    mkdir -p _out/
    curl https://factory.talos.dev/image/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba/${release_v1_13}/metal-amd64.iso -L -o _out/metal-amd64.iso
    `}
</CodeBlock>

## Create VMs

Start by creating a new VM by clicking the "New" button in the VirtualBox UI:

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-new-vm.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=00f14c5a7ac555977d7309f57f099b7d" width="500px" data-path="talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-new-vm.png" />

Supply a name for this VM, and specify the Type and Version:

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-vm-name.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=059bea0b1ac9614db45a69ac7da6437e" width="500px" data-path="talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-vm-name.png" />

> Note: Make sure type is set as `Linux / Other Linux (64-bit)`.

Edit the memory to supply at least 2GB of RAM for the VM:

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-vm-memory.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=2bbafec43e67b7ed5dff446a838db980" width="500px" data-path="talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-vm-memory.png" />

Proceed through the disk settings, keeping the defaults.
You can increase the disk space if desired.

Once created, select the VM and hit "Settings":

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-edit-settings.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=5640290299ec2cbba02dac1759d5f430" width="500px" data-path="talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-edit-settings.png" />

In the "System" section, supply at least 2 CPUs:

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-edit-cpu.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=4ef1261dab57f304d53db2da27f48151" width="500px" data-path="talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-edit-cpu.png" />

In the "Network" section, switch the network "Attached To" section to "Bridged Adapter":

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-edit-nic.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=a7bb8ae4eb8c65fdca7bef3736836151" width="500px" data-path="talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-edit-nic.png" />

Finally, in the "Storage" section, select the optical drive and, on the right, select the ISO by browsing your filesystem:

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-add-iso.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=34afb32ad4754aaa890ad358cf3e9dde" width="500px" data-path="talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-add-iso.png" />

Repeat this process for a second VM to use as a worker node.
You can also repeat this for additional nodes desired.

## Start control plane node

Once the VMs have been created and updated, start the VM that will be the first control plane node.
This VM will boot the ISO image specified earlier and enter "maintenance mode".
Once the machine has entered maintenance mode, there will be a console log that details the IP address that the node received.
Take note of this IP address, which will be referred to as `$CONTROL_PLANE_IP` for the rest of this guide.
If you wish to export this IP as a bash variable, simply issue a command like `export CONTROL_PLANE_IP=1.2.3.4`.

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-maintenance-mode.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=b91086061a4a7b9f8c13f096aafa5422" width="500px" data-path="talos/v1.13/platform-specific-installations/local-platforms/images/virtualbox-maintenance-mode.png" />

## Generate machine configurations

With the IP address above, you can now generate the machine configurations to use for installing Talos and Kubernetes.
Issue the following command, updating the output directory, cluster name, and control plane IP as you see fit:

```bash theme={null}
talosctl gen config talos-vbox-cluster https://$CONTROL_PLANE_IP:6443 --output-dir _out
```

This will create several files in the `_out` directory: controlplane.yaml, worker.yaml, and talosconfig.

## Create control plane node

Using the `controlplane.yaml` generated above, you can now apply this config using talosctl.
Issue:

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

You should now see some action in the VirtualBox console for this VM.
Talos will be installed to disk, the VM will reboot, and then Talos will configure the Kubernetes control plane on this VM.

> Note: This process can be repeated multiple times to create an HA control plane.
>
> Note: If you encounter the following error in the console:
>
> `Talos is already installed to disk but booted from another media and talos.halt_if_installed kernel parameter set. Please reboot from another disk.`
>
> Simply remove the ISO image from the VM and restart it.

## Create worker node

Create at least a single worker node using a process similar to the control plane creation above.
Start the worker node VM and wait for it to enter "maintenance mode".
Take note of the worker node's IP address, which will be referred to as `$WORKER_IP`.
If you wish to export this IP as a bash variable, simply issue a command like `export WORKER_IP=1.2.3.4`.

Issue:

```bash theme={null}
talosctl apply-config --insecure --nodes $WORKER_IP --file _out/worker.yaml
```

> Note: This process can be repeated multiple times to add additional workers.

### Bootstrap `etcd`

Before the cluster is ready, the `etcd` has to be bootstrapped.
The cluster will be in stage `Booting` and `healthy` state until this is stage is completed.

Set the `endpoints` and `nodes`:

```bash theme={null}
talosctl --talosconfig $TALOSCONFIG config endpoint <control plane 1 IP>
talosctl --talosconfig $TALOSCONFIG config node <control plane 1 IP>
```

Bootstrap `etcd` by running the following command.
You should see stage change to `Running` and your cluster is now ready.

```bash theme={null}
talosctl --talosconfig $TALOSCONFIG bootstrap
```

## Using the cluster

Once the cluster is available, you can make use of `talosctl` and `kubectl` to interact with the cluster.
For example, to view current running containers, run `talosctl containers` for a list of containers in the `system` namespace, or `talosctl containers -k` for the `k8s.io` namespace.
To view the logs of a container, use `talosctl logs <container>` or `talosctl logs -k <container>`.

First, configure talosctl to talk to your control plane node by issuing the following, updating paths and IPs as necessary:

```bash theme={null}
export TALOSCONFIG="_out/talosconfig"
talosctl config endpoint $CONTROL_PLANE_IP
talosctl config node $CONTROL_PLANE_IP
```

### Retrieve the `kubeconfig`

At this point we can retrieve the admin `kubeconfig` by running:

```bash theme={null}
talosctl --talosconfig $TALOSCONFIG kubeconfig .
```

Export the config so kubectl can find it: `export KUBECONFIG=$(pwd)/kubeconfig`.

You can then use kubectl in this fashion:

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

## Cleaning up

To cleanup, simply stop and delete the virtual machines from the VirtualBox UI.