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

# Experimental: PoC nodes and cluster

> The start page's PoC tab: Talos node VMs on your vCenter and a Kubernetes cluster on them, built through the appliance's own Omni and ready for Celum to onboard.

> [!WARNING]
>
> This feature is experimental. It is off unless you switch it on, and it may change between releases.

The start page's **Experimental: PoC** tab builds a Kubernetes cluster for a proof of concept, before Celum manages anything:

1. **Nodes:** Talos VMs on your vCenter, cloned from a Talos template, that join the appliance's own Omni.
2. **Cluster:** a Kubernetes cluster on those nodes, from Omni's golden cluster template.
3. **Hand-over:** if you choose to, the cluster is added to Celum, ready to onboard.

The appliance records everything it creates, and **Tear down** removes exactly that.

## Switch it on

At deployment, tick **Experimental: PoC nodes and cluster** in the OVA's form. Or set it in `appliance.yaml`, at deployment or later:

```yaml theme={null}
experimental:
  poc:
    enabled: true
```

The start page reads the file again every few seconds, so the tab appears without a restart. The same steps also run over SSH, with `celum-appliance poc`; see [Over SSH](#over-ssh).

## Before you start

![The Before you start card of the PoC tab, with the network requirements and the Talos image](https://mintcdn.com/celum-dev/JO6zxMu9jmiBAwAv/images/start-page/poc-before-you-start.png?fit=max\&auto=format\&n=JO6zxMu9jmiBAwAv\&q=85\&s=5c1501e519d514d0e97ccaf7b5e44b80)

The first card lists what your network and vCenter must provide:

* **DHCP on the management port group.** The plan addresses the other networks statically.
* **From the management network to the appliance:** TCP 8090, Omni's machine API, and UDP 50180, SideroLink's WireGuard.
* **DNS on the management network that resolves `omni.DOMAIN`:** forward the appliance's domain to the appliance, or have DHCP hand out the appliance as the resolver.
* **The appliance reachable from the primary network.** Once a node's cluster configuration applies, its default route is the primary network's gateway. **Create cluster** pings that gateway first, and creates nothing when it does not answer: a node that cannot reach the appliance never comes up, and Omni cannot tear it down until its disk is wiped.
* **MTU 9000 end to end** on the overlay and storage port groups, unless you lower it in the plan.
* **Internet access for the nodes:** until Celum takes the cluster over, they pull Kubernetes' own images from `registry.k8s.io`, `ghcr.io` and `docker.io`.
* **Nested virtualisation** allowed on the hosts, which KubeVirt needs.
* **One CPU vendor per cluster:** a vCenter cluster that mixes Intel and AMD hosts is refused.
* **To import a Talos image:** the appliance reaches `factory.talos.dev`, and every ESXi host of the cluster on TCP 443. The upload goes to a host, not through vCenter.

The nodes get the appliance's CA with their join configuration, so there is nothing to install on them.

### The Talos image

The nodes are cloned from a vCenter template holding Talos v1.14.1's VMware image from the Image Factory, with the `drbd`, `iscsi-tools`, `multipath-tools`, `util-linux-tools` and `vmtoolsd-guest-agent` extensions. Intel and AMD hosts need different images: the AMD one adds the kernel argument `module_blacklist=amd64_edac`, without which the Intel image panics at boot on an AMD CPU.

You rarely need to do anything here. Once you choose a cluster in step 3, the tab names the image its hosts need and imports it into vCenter when none of the templates holds it. Where the appliance cannot reach `factory.talos.dev`, the card shows the `govc` commands to import it by hand.

## Build the cluster

**1. Connect vCenter**

![The vCenter card, with a saved connection](https://mintcdn.com/celum-dev/JO6zxMu9jmiBAwAv/images/start-page/poc-vcenter.png?fit=max\&auto=format\&n=JO6zxMu9jmiBAwAv\&q=85\&s=e40f93c93400a4599d8d31b17683ff6a)

Enter vCenter's **Address**, a **User** and its **Password**. Choose **Read fingerprint**, compare the certificate fingerprint with your vCenter's, then **Test and save**. The appliance logs in and saves the connection only if vCenter accepts it, and trusts vCenter by that fingerprint from then on.

The password is kept in the appliance's secret store and never shown again; the card only says **saved**. **Remove** forgets the connection and deletes the password. You cannot change the connection while VMs are recorded on it.

**2. Plan the nodes**

![The Nodes and Cluster cards, where you plan the VMs and the cluster's networks](https://mintcdn.com/celum-dev/JO6zxMu9jmiBAwAv/images/start-page/poc-nodes-cluster.png?fit=max\&auto=format\&n=JO6zxMu9jmiBAwAv\&q=85\&s=2e53c2069ab5061855bfcc3d4a88b682)

In **3. Nodes**, choose **Read vCenter**, then:

* the **Compute cluster** the VMs run on;
* four port groups: **Management** (DHCP), **Overlay**, **Storage** and **Primary**, which carries the API VIP and the default route;
* the **Datastore**, the **VM folder** and the **Resource pool**. By default these are the datacenter's VM folder and the cluster's root pool. **New VM folder…** and **New resource pool…** create one; vSphere offers resource pools only on a cluster with DRS on;
* the **Talos templates** for Intel and AMD hosts. If the hosts' image is missing, **Import the … image into vCenter** downloads it and makes the template;
* the number of **Control planes** (1, 3 or 5) and **Workers**, with vCPU, memory and disk for each. A **data disk** above 0 adds a second disk to each node, for example for Ceph.

**3. Plan the cluster**

In **4. Cluster**, set:

* the **Cluster name** and **Kubernetes version**;
* **DNS servers** and an **NTP server**. Blank uses the appliance for DNS, and Talos's default for NTP;
* for the **Overlay**, **Storage** and **Primary** networks: the network in CIDR form, the **First node address** and the **MTU**. The primary network also takes its **Gateway** and the **API VIP**. Each node gets consecutive addresses from the first one: control planes first, then workers;
* the **Pod** and **Service** networks.

Tick **The gateway drops ping…** if the primary gateway does not answer ping, so **Create cluster** does not wait for it. Tick **Add the cluster to Celum once it is up** to hand the cluster to Celum. Then choose **Save plan**.

The tab checks each field as you leave it, and the whole address plan once every address is filled: that the nodes fit, that no networks overlap, and that the VIP and gateway collide with nothing. You can save a plan in parts.

**4. Run**

![The Run card, with Create nodes, Create cluster, Tear down and Check machines](https://mintcdn.com/celum-dev/JO6zxMu9jmiBAwAv/images/start-page/poc-run.png?fit=max\&auto=format\&n=JO6zxMu9jmiBAwAv\&q=85\&s=66fdb70a854c6d275ecba8fb8a00e925)

* **Create nodes** clones the VMs from the template for the hosts' CPU vendor, then waits until Omni shows each one ready.
* **Create cluster** builds the cluster on the recorded nodes, once, and waits until the control plane is healthy and the Kubernetes API answers. It then writes a kubeconfig to `/var/lib/celum-appliance/poc/CLUSTER.kubeconfig`, with a token that does not expire, and adds the cluster to Celum if you asked for that. The template is applied once: later changes go through Celum. If a run stops after the cluster was created, **Finish cluster** completes it.
* **Check machines** shows whether each recorded VM is still in vCenter, where, and whether it joined Omni.
* **Tear down** removes what was recorded: the Omni cluster and its Celum registration, then the VMs, then their Omni machines.

**Create nodes**, **Create cluster** and **Tear down** ask you to confirm. One action runs at a time, and the **Last action** card shows its progress and log.

## Over SSH

Every step of the tab is also a `celum-appliance poc` command:

```bash theme={null}
celum-appliance poc vcenter thumbprint -url vcenter.example.com
celum-appliance poc vcenter set -url vcenter.example.com -username celum-poc@vsphere.local -thumbprint FINGERPRINT
celum-appliance poc inventory -datacenter DC -cluster CLUSTER
celum-appliance poc plan show > plan.json     # edit it, then:
celum-appliance poc plan set -f plan.json
celum-appliance poc template import -vendor intel   # or amd
celum-appliance poc nodes
celum-appliance poc cluster
celum-appliance poc status
celum-appliance poc check
celum-appliance poc teardown
```

The actions log to `journalctl -u 'celum-appliance-poc@*'`. `celum-appliance poc` with no arguments lists every command.

## Bare metal

The tab can also prepare boot media for bare-metal servers and add them to the cluster instead of VMs. That path has not been tested on hardware yet, so it is not described here.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.