Register an Edge Node

This guide explains how to register a bare-metal or virtual edge node with the Palette VerteX management cluster so it can be used as compute capacity in a Compute Pool. The process involves generating a pairing key in the Palette VerteX UI, embedding that key along with registry credentials in the node's user-data YAML, and then verifying the node appears as registered.

Prerequisites

• A running Palette VerteX management cluster. Refer to Appliance Installation for setup instructions.
• Administrative access to the Palette VerteX UI and the PaletteAI project.
• The PaletteAI ISO loaded on the edge node to be registered.
• In air-gapped environments: all required pack .zst bundles already imported into the internal Zot registry. Refer to Deploy Profile Bundles in Air-Gapped Environments.
• Network connectivity from the edge node to the Palette VerteX management cluster on the following ports:
  • TCP/443 — Palette VerteX API
  • TCP/30003 — Internal Zot OCI registry (air-gapped deployments)

Generate a Pairing Key

A pairing key is a one-time credential that authorizes an edge node to register itself with the Palette VerteX management cluster.

1. Log in to the Palette VerteX UI.

2. From the left navigation menu, select Edge Hosts.

3. Click Add Edge Host or Register Node, depending on your Palette VerteX version.

4. Copy the displayed Pairing Key. You embed this key in the node's user-data YAML in the next section.

info

Pairing keys are single-use. If you need to register multiple nodes, generate a separate key for each node, or check your Palette VerteX version for bulk registration options.

Prepare the User-Data YAML

The user-data YAML configures the node during boot. It embeds the pairing key, SSH access, and (for air-gapped environments) the internal Zot registry credentials.

Create or update your user-data.yaml with the following content:

#cloud-config
stages:
  initramfs:
    - users:
        kairos:
          groups:
            - sudo
          ssh_authorized_keys:
            - 'ssh-rsa AAAAB3NzaC1yc2E... your-public-key'

palette:
  pairing_key: '<your-pairing-key>'

Replace the following values:

Placeholder	Value
your-public-key	Contents of your SSH public key file (e.g., ~/.ssh/id_ed25519.pub)
<your-pairing-key>	The pairing key copied from the Palette VerteX UI

Air-Gapped: Add Zot Registry Credentials

In an air-gapped environment, the node must be configured to pull images from the internal Zot registry instead of the internet. Add the registry section to your user-data:

#cloud-config
stages:
  initramfs:
    - users:
        kairos:
          groups:
            - sudo
          ssh_authorized_keys:
            - 'ssh-rsa AAAAB3NzaC1yc2E... your-public-key'

palette:
  pairing_key: '<your-pairing-key>'
  registries:
    - domain: '<vertex-ip>:30003'
      insecure: false
      credentials:
        username: '<zot-username>'
        password: '<zot-password>'

Retrieve the Zot credentials from the management cluster:

kubectl get secret zot-secret --namespace palette-system --output jsonpath='{.data.htpasswd}' | base64 --decode

The output contains the username and bcrypt-hashed password. Use the plain text credentials you set when configuring Zot, not the hashed value from the secret.

Configure Subnet Restrictions (Optional)

To restrict the node to communicate only within an internal subnet (for example, 192.168.1.0/24), configure network settings in user-data:

network:
  dns:
    nameservers:
      - 192.168.1.1
  interfaces:
    - name: eth0
      addresses:
        - 192.168.1.50/24
      gateway: 192.168.1.1

Adjust the interface name, IP address, and gateway to match your network topology.

Apply the User-Data to the Node

How you supply user-data depends on your infrastructure:

Bare Metal

1. Create a small FAT32 or ISO9660 partition or a USB key labeled cidata containing a file named user-data with the YAML content above and an empty meta-data file.

2. Attach the cidata drive to the node before boot.

3. Boot the node from the PaletteAI ISO.

VMware vSphere

1. Encode the user-data YAML as Base64:

   base64 --wrap=0 user-data.yaml

2. In the vSphere Client, open the VM settings and add the Base64 string as the guestinfo.userdata extra configuration key. Set guestinfo.userdata.encoding to base64.

3. Power on the VM.

Verify Node Registration

After the node boots and connects to the management cluster, verify that it appears as registered.

1. Log in to the Palette VerteX UI.

2. Navigate to Edge Hosts.

3. Confirm the node appears in the list with a Registered or Ready status.

Alternatively, check the registered edge hosts using kubectl on the management cluster:

kubectl get edgehosts --all-namespaces

Expected output:

NAMESPACE       NAME             STATUS     AGE
palette-system  edge-node-abc1   Registered  2m

If the node does not appear after a few minutes, refer to Troubleshooting Compute Pools for common causes and debug steps.

Next Steps

Once the edge node is registered, you can reference it when creating a Compute Pool. Refer to Create and Manage Compute Pools.