Deploy a Single-Node Compute Pool

This guide describes how to deploy a single-node Compute Pool. A single-node Compute Pool uses one Edge host for both the Kubernetes control plane and workload scheduling. A cluster is automatically recognized as single-node when all three conditions are met: the control plane pool has exactly one node, the control plane is worker-eligible, and no worker pools are defined. You can deploy a single-node Compute Pool using the PaletteAI UI or YAML Kubernetes manifests.

warning

A single-node Compute Pool is not considered a High Availability (HA) setup. If the Edge host fails, the cluster and all workloads running on it become unavailable. Use single-node Compute Pools for development, experimentation, or non-critical deployments only.

Prerequisites

Before you begin, confirm that you have the following PaletteAI resources configured.

UI Workflow

• A Project in Ready status

• A Settings resource with valid Palette API credentials

• A Profile Bundle of type Infrastructure or Fullstack

• A Compute resource with available Edge hosts registered in Palette

• Edge hosts with a resolved default NIC (and per-host static IP where required for multi-NIC hosts). Configure these on the Compute tab in Project Settings, Tenant Settings, or System Settings before provisioning.

• A reserved Virtual IP (VIP) address for the cluster control plane endpoint

• A user with Project Admin permissions. The Project Editor role has read-only access to Compute Pools.

YAML Workflow

• A Project in Ready status

• A Settings resource with valid Palette API credentials

• A Profile Bundle of type Infrastructure or Fullstack

• A Compute resource with available Edge hosts registered in Palette

• Edge hosts with a resolved default NIC (and per-host static IP where required for multi-NIC hosts). Configure these on the Compute tab in Project Settings, Tenant Settings, or System Settings before provisioning.

• A reserved Virtual IP (VIP) address for the cluster control plane endpoint

• kubectl installed and available in your $PATH

• The KUBECONFIG environment variable set to the path of the PaletteAI hub cluster's kubeconfig file.

  export KUBECONFIG=<kubeconfig-location>

• A user with Project Admin permissions. The Project Editor role has read-only access to Compute Pools.

Create a Compute Config

Create a Compute Config that specifies a single control plane node with worker eligibility enabled and no worker pools.

UI Workflow

1. Log in to PaletteAI, and then open your Project.

2. From the left main menu, select Settings, and then select the Compute Config tab.

3. Select Create Compute Config. Follow the Create and Manage Compute Configs guide for details on each page, using the following single-node values on the Node Pool Defaults page.

   Field	Value
   Node Count	Set to 1.
   Run workloads on control plane	Turn on. The control plane node also schedules workloads.
   Architecture	CPU architecture of the target Edge host (for example, AMD64 or ARM64).
   CPU Count	Total CPU cores the single node needs.
   Memory	Total memory the single node needs.
   GPU Variant (Optional)	GPU variant the single node needs. Expand GPU Resources and select Add GPU variant.
   Physical GPU Count (Optional)	Total number of GPUs the single node needs. Required when a GPU variant is selected.

4. Do not configure worker pool settings. A single-node cluster has no worker pools.

5. On the Review page, confirm your settings, and then submit the Compute Config.

YAML Workflow

1. Define a YAML manifest for the ComputeConfig.

   single-node-compute-config.yaml

   apiVersion: spectrocloud.com/v1alpha1
   kind: ComputeConfig
   metadata:
     name: single-node-compute-config
     namespace: <project-namespace>
   spec:
     paletteClusterConfig:
       defaults:
         controlPlanePool:
           # nodeCount 1 + workerNodeEligible + no workerPools = single-node cluster
           nodeCount: 1
           workerNodeEligible: true
           architecture: <target-architecture>
           cpu:
             cpuCount: 8
           memory:
             memory: '16 GB'
           gpu:
             variant: 'NVIDIA H100 PCIe | 80 GB'
             gpuCount: 1

   Replace <project-namespace> with the namespace of your Project, and <target-architecture> with the CPU architecture of the target edge host (for example, AMD64 or ARM64). Adjust the CPU, memory, and GPU requirements to match the target Edge host. The gpu section is optional; omit it for CPU-only single-node clusters.

2. (Optional) Set the Compute Config as the project default so the Compute Pool wizard pre-populates single-node mode before the Resource groups step. In Project Settings, open the Compute Config tab, select your Compute Config, and select Set as default from the action menu. Refer to Project Settings.

3. Apply the manifest.

   kubectl apply --filename single-node-compute-config.yaml

4. Verify the ComputeConfig was created.

   kubectl get computeconfig single-node-compute-config --namespace <project-namespace>

   Example Output

   NAME                        AGE
   single-node-compute-config  10s

Resource Groups and Single-Node Host Selection

Single-node Compute Pools use Control Plane Resource Groups (spec.clusterVariant.controlPlaneResourceGroups) to filter which Edge host PaletteAI selects. The control plane pool requirements define the hardware the single node needs (CPU, memory, and GPU). PaletteAI uses both the requirements and the control plane resource groups to select the Edge host.

Edge hosts tagged with both palette.ai/control-plane: true and palette.ai/worker: true appear only in worker inventory on the Compute resource. Their palette.ai.rg/<key> labels therefore surface under worker compute, not control plane compute. When the Compute Pool wizard detects single-node mode, it merges worker inventory resource groups into the Control Plane Resource Groups list so you can target a specific dual-role host.

The Compute Pool creation wizard presents Resource groups before Node config. Single-node mode is usually chosen on Node config (or pre-populated from a Compute Config). Use one of the following approaches so control plane resource groups stay selectable:

1. Set a single-node Compute Config as the project default before you open Create Compute Pool. The wizard pre-populates single-node mode from that default, so the Resource groups step already includes worker inventory tags in the control plane list.

2. Return to the Resource groups step after Node config. Complete Node config, apply your single-node Compute Config, then use the wizard's back navigation to open Resource groups again. The control plane list refreshes with worker inventory tags once single-node mode is inferred.

Reordering the wizard so Node config precedes Resource groups would remove the need for these workarounds, but that change is out of scope for this fix and left as a follow-up.

Resource group labels are assigned on Edge hosts in Palette (palette.ai.rg/<key>: "<value>"). PaletteAI reads them from Compute inventory; it does not infer resource groups from control plane or worker role labels alone.

Worker Resource Groups

A single-node cluster never saves worker resource groups. PaletteAI applies only spec.clusterVariant.controlPlaneResourceGroups for host selection on a single-node pool, so a save from the Resource Groups tab leaves the resource's existing workerResourceGroups value untouched, and the wizard's review step reports Not saved (single-node cluster) for the Worker row.

When you edit an existing pool, set Control Plane Resource Groups to target a specific dual-role host. Any worker resource groups carried over from an earlier multi-node configuration stay on the resource but have no effect on host selection.

Create a Single-Node Compute Pool

UI Workflow

Create a Compute Pool that references the Compute Config you created. The control plane pool requirements you configure determine which Edge host PaletteAI selects for the single-node cluster.

1. Log in to PaletteAI and navigate to your project.

2. From the left main menu, select Compute Pools.

3. Select Create Compute Pool.

4. Complete the General information, Mode (select Dedicated resources), Profile Bundle, and Variables screens. Refer to Create and Manage Compute Pools for details on each screen.

   Select Next after completing each screen.

5. On the Resource groups screen, optionally add Control Plane Resource Groups to restrict host selection. If you set a single-node Compute Config as the project default, the control plane list already includes worker inventory tags and you can configure resource groups here. Otherwise, you can skip this screen for now and return after Node config (described below).

   Select Next.

6. On the Node config screen, select the gear icon in the top-right to open the Advanced settings drawer.

7. From the Compute Config drop-down menu, select single-node-compute-config, and then select Apply. When the confirmation dialog appears, select Replace values.

   The Compute Config auto-populates the control plane pool with Node Count: 1, Run workloads on control plane enabled, and the hardware requirements (CPU, memory, GPU) you defined. These control plane pool requirements determine which Edge host PaletteAI selects for the single node.

8. If you need to set Control Plane Resource Groups and skipped the Resource groups screen earlier, use the wizard's back navigation to return to Resource groups now that single-node mode is enabled. Add the key/value pairs that match your target Edge host's palette.ai.rg/ labels, then continue forward to Node config again if needed.

9. Verify the control plane pool configuration matches your target Edge host. A single-node cluster has no worker pools.

   Select Next.

10. On the Deployment screen, select Edge Configuration in the left panel, and then select Configure. Enter the VIP address for the cluster control plane endpoint, and then select Save changes.

    Select Next.

11. On the Summary screen, review your configuration, and then select Submit.

YAML Workflow

Create a Compute Pool by applying a manifest with worker eligibility and node count set directly in the spec. The control plane pool requirements you configure determine which Edge host PaletteAI selects for the single-node cluster.

1. Define a YAML manifest for the ComputePool.

   single-node-compute-pool.yaml

   apiVersion: spectrocloud.com/v1alpha1
   kind: ComputePool
   metadata:
     name: single-node-compute-pool
     namespace: <project-namespace>
   spec:
     profileBundleRef:
       name: <profile-bundle-name>
       namespace: <project-namespace>
       cloudType: edge-native
     clusterVariant:
       controlPlaneResourceGroups:
         datacenter: us-west-1
       dedicated:
         paletteClusterDeploymentConfig:
           cloudType: edge-native
           nodePoolRequirements:
             controlPlanePool:
               # nodeCount 1 + workerNodeEligible + no workerPools = single-node cluster
               nodeCount: 1
               workerNodeEligible: true
               architecture: <target-architecture>
               cpu:
                 cpuCount: 8
               memory:
                 memory: '16 GB'
               gpu:
                 variant: 'NVIDIA H100 PCIe | 80 GB'
                 gpuCount: 1
           edge:
             vip: <vip-address>

   Replace the following placeholders:

   Placeholder	Description
   <project-namespace>	The namespace of your Project.
   <profile-bundle-name>	The name of your Profile Bundle resource.
   <target-architecture>	CPU architecture of the target Edge host (for example, AMD64 or ARM64).
   <vip-address>	The reserved VIP address for the cluster control plane endpoint.

   Adjust the CPU, memory, and GPU requirements to match the target Edge host. The gpu section is optional; omit it for CPU-only single-node clusters. For dual-role Edge hosts (both control plane and worker labels), set controlPlaneResourceGroups rather than workerResourceGroups. PaletteAI uses control plane resource groups for single-node host selection.

2. Apply the manifest.

   kubectl apply --filename single-node-compute-pool.yaml

3. Verify the ComputePool was created.

   kubectl get computepool single-node-compute-pool --namespace <project-namespace>

   Example Output

   NAME                       AGE
   single-node-compute-pool   10s

Validate

UI Workflow

1. Log in to PaletteAI and navigate to your project.

2. From the left main menu, select Compute Pools.

3. Confirm the Compute Pool appears with status Provisioning.

4. Confirm the status changes to Running. Provisioning typically takes 10–15 minutes depending on Edge host availability.

5. Select the Compute Pool to open its detail page, and then review the Total CPU and Total Memory stats to confirm they reflect a single edge host.

YAML Workflow

1. Confirm the Compute Pool status changes to Running. Provisioning typically takes 10–15 minutes depending on Edge host availability.

   kubectl get computepool single-node-compute-pool --namespace <project-namespace>

   Example Output

   NAME                       STATUS    AGE
   single-node-compute-pool   Running   15m

2. Confirm a single node is allocated by reviewing the Compute Pool details.

   kubectl describe computepool single-node-compute-pool --namespace <project-namespace>

   In the output, verify that the control plane pool has nodeCount: 1 and workerNodeEligible: true, and that no worker pools are defined.

Next Steps

• Create and Manage Compute Pools for standard multi-node Compute Pool configuration.

• Deploy applications to your Compute Pool.

• Troubleshoot common Compute Pool issues.