Skip to main content
Version: v1.1.x

ComputePool Configuration Reference

This page provides technical reference information for configuring ComputePools.

Complete ComputePool Example​

The following example shows a complete, production-ready ComputePool manifest with all major fields. Use this as a template and refer to the detailed sections below for field-specific guidance.

apiVersion: spectrocloud.com/v1alpha1
kind: ComputePool
metadata:
  name: ml-cluster
  namespace: my-project
  labels:
    environment: production
    team: ml-platform
  annotations:
    description: 'Production ML compute cluster'
    owner: 'ml-platform-team'
spec:
  # Deletion policy - what happens when ComputePool is deleted
  deletionPolicy: delete

  # ProfileBundle reference - defines infrastructure and application stacks
  profileBundleRef:
    name: edge-profilebundle
    namespace: my-project
    cloudType: edge-native

  # Cluster variant configuration
  clusterVariant:
    # Optional: Resource groups filter which hosts are eligible for this cluster
    controlPlaneResourceGroups:
      'palette.ai': 'true'
    workerResourceGroups:
      'palette.ai': 'true'
      'gpu-enabled': 'true'

    # Dedicated cluster configuration
    dedicated:
      paletteClusterDeploymentConfig:
        # Cloud type for deployment
        cloudType: edge-native

        # Node pool requirements
        nodePoolRequirements:
          # Control plane configuration
          controlPlanePool:
            nodeCount: 3
            workerNodeEligible: false
            architecture: AMD64
            cpu:
              cpuCount: 4
            memory:
              memory: '16 GB'
            labels:
              node-role: control-plane
            annotations:
              description: 'Control plane node'

          # Worker pools
          workerPools:
            - name: cpu-pool
              architecture: AMD64
              cpu:
                cpuCount: 8
              memory:
                memory: '32 GB'
              labels:
                workload-type: cpu-intensive
              annotations:
                description: 'CPU worker pool'
            - name: gpu-pool
              architecture: AMD64
              cpu:
                cpuCount: 16
              memory:
                memory: '64 GB'
              gpu:
                family: NVIDIA-A100
                gpuCount: 2
                gpuMemory: '80 GB'
              labels:
                workload-type: gpu-training
              annotations:
                description: 'GPU worker pool for ML training'

        # Optional: SSH keys for cluster node access
        sshKeys:
          - 'ssh-rsa AAAAB3Nza... your-ssh-key'

        # Edge configuration (overrides ComputeConfig defaults)
        edge:
          # Required: Virtual IP for cluster control plane
          vip: '10.10.162.130'
          # Optional: NTP servers for time synchronization
          ntpServers:
            - time.google.com
            - time.cloudflare.com
          # Optional: Network overlay configuration
          networkOverlayConfig:
            enabled: false
            staticIp: false
            cidr: '192.168.1.0/24'
          # Optional: Two-node deployment mode
          isTwoNode: false
YAML Structure

All configuration shown in the sections below fits into the structure shown in this complete example. Pay special attention to the nesting hierarchy to avoid placement errors.

Key nesting paths:

  • Control plane config: spec.clusterVariant.dedicated.paletteClusterDeploymentConfig.nodePoolRequirements.controlPlanePool
  • Worker pools config: spec.clusterVariant.dedicated.paletteClusterDeploymentConfig.nodePoolRequirements.workerPools
  • Edge config: spec.clusterVariant.dedicated.paletteClusterDeploymentConfig.edge
  • Deletion policy: spec.deletionPolicy

Control Plane Configuration​

Use nodePoolRequirements.controlPlanePool to configure the control plane node pool.

  • Node count: 1, 3, or 5.

  • Single-node clusters: To deploy a single-node cluster, set singleNodeCluster: true. When singleNodeCluster is true, you must also set nodeCount: 1 and workerNodeEligible: true, and include at least one worker pool in the configuration (the worker pool is used for edge host selection). Without these settings, single-node clusters cannot schedule workloads and will not become Ready.

  • Worker eligibility: For multi-node clusters (3 or 5 nodes), you have two options:

    1. Set to false to keep the control plane dedicated and define one or more worker pools
    2. Set to true with an empty workerPools array to schedule workloads directly on control plane nodes (HA control-plane-only topology)

  • Architecture: AMD64 or ARM64. Defaults to AMD64.

  • Resource requirements: Set cpu.cpuCount and optional memory.memory (a string with units, for example '16 GB').

Example for a single-node cluster:

controlPlanePool:
  nodeCount: 1
  singleNodeCluster: true
  workerNodeEligible: true
  architecture: AMD64
  cpu:
    cpuCount: 4
  memory:
    memory: '16 GB'

workerPools:
  - name: default-pool
    architecture: AMD64
    cpu:
      cpuCount: 4
    memory:
      memory: '16 GB'

Example for a multi-node cluster:

controlPlanePool:
  nodeCount: 3
  workerNodeEligible: false
  architecture: AMD64
  cpu:
    cpuCount: 4
  memory:
    memory: '16 GB'

Worker Pool Configuration​

Use nodePoolRequirements.workerPools to define worker pools.

  • Create multiple worker pools to separate workload types (for example, CPU-only and GPU-enabled).

  • Each worker pool can have different resource requirements.

  • Set gpu values for GPU-enabled worker pools.

  • Each worker pool must have a unique name within the ComputePool.

Empty Worker Pools

The workerPools array can be empty if and only if:

  • The control plane has more than one node (nodeCount is 3 or 5)
  • controlPlanePool.workerNodeEligible is set to true

For single-node clusters (singleNodeCluster: true), at least one worker pool is required even when workerNodeEligible is true; the worker pool is used for edge host selection. For dedicated (non-worker-eligible) control planes, at least one worker pool is required because workloads cannot schedule on the control plane.

workerPools:
  - name: cpu-pool
    architecture: AMD64
    cpu:
      cpuCount: 4
  - name: gpu-pool
    architecture: AMD64
    cpu:
      cpuCount: 8
    gpu:
      family: NVIDIA-A100
      gpuCount: 2
      gpuMemory: '80 GB'

Worker Pool Fields​

Required fields:

  • name. The unique name of the worker pool. Must start with a letter and must not contain any of the following characters: /&#+%?,$. Must not exceed 62 characters. These naming rules apply when a worker pool is first named; names that already exist on a Compute Pool remain valid on update.

Optional fields:

  • architecture. CPU architecture (AMD64 or ARM64). Defaults to AMD64.

  • cpu. CPU requirements for the worker pool.

    • cpuCount. Number of CPU cores per node.

  • memory. Memory requirements for the worker pool.

    • memory. Memory per node as a string with units (for example, '16 GB' or '8192 MiB').

  • gpu. GPU requirements for GPU-enabled worker pools.

    • family. GPU family name (for example, NVIDIA-A100).

    • gpuCount. Total number of GPUs across all selected edge hosts in the pool.

    • gpuMemory. Total GPU memory across all selected edge hosts, as a string with units (for example, '80 GB').

  • labels. Key-value pairs to apply to nodes in this worker pool.

  • annotations. Key-value pairs to attach metadata to nodes in this worker pool.

Edge Configuration​

Use edge to configure edge clusters.

VIP Requirements​

The Virtual IP (VIP) is the control plane endpoint for the Kubernetes cluster. Proper VIP planning is critical for successful cluster deployment.

VIP Planning Checklist:

Before provisioning a Compute Pool, complete the following VIP requirements:

  1. Reserve the VIP from your network team or IPAM system. The VIP must be allocated and documented before cluster creation.

  2. Verify network placement:

    • The VIP must be in the same Layer 2 network segment as the control plane nodes.
    • The VIP must be reachable from all edge hosts that will join the cluster.
    • The VIP must not be in a CIDR range routed through a proxy.

  3. Confirm VIP availability:

    • The VIP must not be assigned to any other device or cluster.
    • Verify no IP conflicts exist using Address Resolution Protocol (ARP) or ping tests.

  4. VIP format:

    • The VIP can be an IPv4 address (for example, 10.10.162.130) or a Fully Qualified Domain Name (FQDN) that resolves to an IP address.
    • Ensure DNS resolution is configured if using an FQDN.

  5. VIP advertisement mechanism:

    • PaletteAI edge clusters use kube-vip to advertise the VIP using Layer 2 ARP or BGP.
    • Layer 2 (ARP) mode is the default and most common configuration:
      • The VIP is advertised via ARP (Address Resolution Protocol)
      • Requires that control plane nodes are on the same L2 network segment
      • Confirm that your network allows ARP traffic between control plane nodes
      • No additional configuration needed in the ComputePool manifest
    • BGP mode (advanced) requires additional Palette cluster profile configuration:
      • The VIP is advertised via BGP peering with network routers
      • Requires BGP configuration in the Palette cluster profile (not in the ComputePool manifest)
      • Use when control plane nodes span multiple L2 segments
      • Requires coordination with your network team for BGP peering setup
    • How to determine which mode is used:
      • By default, kube-vip operates in Layer 2 (ARP) mode
      • BGP mode must be explicitly configured in the Palette infrastructure profile
      • Check your ProfileBundle's referenced Palette cluster profile for kube-vip BGP settings
      • If no BGP configuration exists, Layer 2 mode is active

Pre-flight VIP validation:

Before applying the Compute Pool manifest, validate the VIP from each edge host:

# Verify VIP is not in use (should timeout or fail)
ping -c 3 <vip-address>

# Check ARP table for conflicts (should return no results)
arp -a | grep <vip-address>

# Verify VIP is in same subnet as control plane nodes
ip route get <vip-address>

# If using FQDN, verify DNS resolution
nslookup <vip-fqdn>

VIP constraints:

  • The VIP is immutable after cluster creation. You cannot change the VIP without deleting and recreating the cluster.

  • The VIP must be unique across all Compute Pools in your environment.

  • The VIP must not be used by any other device, service, or load balancer on your network.

Example edge configuration with VIP:

# This configuration goes under:
# spec.clusterVariant.dedicated.paletteClusterDeploymentConfig.edge
edge:
  vip: '10.10.162.130'
  ntpServers:
    - time.google.com
    - time.cloudflare.com
  networkOverlayConfig:
    enabled: true
    cidr: '192.168.1.0/24'

Optional Edge Settings​

YAML path: spec.clusterVariant.dedicated.paletteClusterDeploymentConfig.edge

Additional edge configuration options (all are optional except VIP):

  • NTP servers (ntpServers): Configure time synchronization servers. Use this when edge hosts do not have default NTP configuration or when specific time sources are required.

    edge:
      ntpServers:
        - time.google.com
        - time.cloudflare.com

  • Network overlay (networkOverlayConfig): Configure VXLAN overlay network for pod-to-pod communication across nodes. Use this for advanced networking scenarios or when the underlying network does not support native pod routing.

    edge:
      networkOverlayConfig:
        enabled: true
        staticIp: false
        cidr: '192.168.1.0/24'

    Fields:

    • enabled (boolean) - Enable or disable overlay network
    • staticIp (boolean) - Use static IP assignment for overlay
    • cidr (string) - CIDR range for overlay network

    The schema also accepts an overlayNetworkType field, but it is not read when deploying the cluster. VXLAN is the only supported overlay network type.

  • SSH keys (sshKeys): Configure SSH access to cluster nodes. Use this for operational access and troubleshooting. This is under paletteClusterDeploymentConfig (sibling to edge), not inside edge.

    paletteClusterDeploymentConfig:
      sshKeys:
        - 'ssh-rsa AAAAB3Nza... your-key-1'
        - 'ssh-rsa AAAAB3Nza... your-key-2'

  • Two-node deployment (isTwoNode): Enable two-node cluster mode. Special configuration for edge deployments with exactly two nodes.

    edge:
      isTwoNode: true
    warning

    Two-node deployment is only supported with Palette Optimized K3s or Palette Optimized Canonical Kubernetes. Other Kubernetes distributions (such as Palette Optimized RKE2 or PXK-E) do not support two-node deployment.

ProfileBundle Reference​

profileBundleRef defines the infrastructure stack and, optionally, application stacks for deployment. This is a top-level field under spec.

YAML path: spec.profileBundleRef

Required fields:

  • name - Name of the ProfileBundle resource

  • namespace - Namespace of the ProfileBundle (must match the Project namespace)

Optional fields:

  • cloudType - Cloud provider type (edge-native or maas)

ProfileBundle types:

  • infrastructure - Contains only infrastructure profiles (Kubernetes, networking, storage)

  • fullstack - Contains both infrastructure and application profiles

  • application - Contains only application profiles (for Imported clusters only)

Example:

spec:
  profileBundleRef:
    name: edge-profilebundle
    namespace: my-project
    cloudType: edge-native

Deletion Policy​

deletionPolicy controls what happens to the Palette cluster when you delete the Compute Pool resource from PaletteAI.

YAML path: spec.deletionPolicy

info

The nested spec.clusterVariant.dedicated.paletteClusterDeploymentConfig.deletionPolicy field is deprecated. Use the top-level spec.deletionPolicy field instead.

  • delete (default). Deletes the Palette cluster when the Compute Pool is deleted. Use this for ephemeral or development clusters where you want complete cleanup.

  • orphan. Keeps the Palette cluster running when the Compute Pool is deleted. The cluster becomes unmanaged by PaletteAI. Use this when you want to preserve the cluster infrastructure but stop managing it through PaletteAI.

Affected Resources​

When a Compute Pool is deleted, PaletteAI cleans up associated resources. Which resources are removed depends on the deletion policy.

Always deleted (regardless of policy):

  • AIWorkloads — all AIWorkloads referencing the Compute Pool are force-deleted before the Compute Pool is removed. Orphaning AIWorkloads is not supported.
  • WorkloadDeployments — all WorkloadDeployments associated with the Compute Pool itself are deleted. Such WorkloadDeployments only exist when the active InfrastructureVariant from the Compute Pool's Profile Bundle includes WorkloadProfiles of type infrastructure. The controller waits for all WorkloadDeployments to be fully removed before proceeding with cluster cleanup.

Deleted when deletionPolicy: delete:

  • Palette Cluster — the underlying Kubernetes cluster is deleted from Palette.
  • Environment — the Environment resource created for the Compute Pool is deleted. For Shared Compute Pools with multiple clusters, the Environment is only deleted if all clusters have deletionPolicy: delete. If any cluster uses orphan, the Environment is preserved.

Preserved when deletionPolicy: orphan:

  • Palette Cluster — the cluster continues running in Palette, unmanaged by PaletteAI.
  • Environment — the Environment resource is retained.

Example:

spec:
  deletionPolicy: delete

Orphan mode cleanup:

When using deletionPolicy: orphan, you must manually clean up resources:

  1. The Kubernetes cluster remains running in Palette and continues to consume infrastructure resources.

  2. Any workloads deployed by PaletteAI remain running but are no longer managed.

  3. You must manually delete the cluster from Palette if you no longer need it.

  4. Edge hosts remain allocated to the cluster until you delete the cluster from Palette.

UI Field to YAML Mapping​

The following table maps User Interface wizard fields to their corresponding YAML paths in the ComputePool manifest. Use this when translating UI configurations created in Canvas to Kubernetes manifests for kubectl or GitOps workflows.

UI Wizard StepUI Field NameYAML PathNotes
GeneralCompute pool namemetadata.nameMust be unique in namespace
GeneralDescriptionmetadata.annotations.descriptionOptional annotation
GeneralLabels / Annotationsmetadata.labels /
metadata.annotations		Key-value pairs. See Operational Labels below.
ModeDedicated resourcesspec.clusterVariant.dedicatedMutually exclusive with shared
Profile BundleProfile Bundlespec.profileBundleRef.nameMust exist in same namespace
Profile BundleCloud Typespec.profileBundleRef.cloudTypeTypically edge-native
Profile BundleVersionspec.profileBundleRef.nameTo select a specific revision, use the format <profile-bundle-name>@v<revision> (for example, edge-profilebundle@v3).
Node ConfigNode Count
(control plane)		spec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.controlPlanePool.nodeCount		Values: 1, 3, or 5
Node ConfigWorkload Eligiblespec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.controlPlanePool.workerNodeEligible		Boolean: true for single-node
Node ConfigArchitecturespec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.controlPlanePool.architecture		Values: AMD64, ARM64
Node ConfigCPU Countspec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.controlPlanePool.cpu.cpuCount		Integer
Node ConfigMemoryspec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.controlPlanePool.memory.memory		String with units (for example, 16 GB).
Node ConfigWorker Pool
Name		spec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.workerPools[].name		Required. Must be unique within the ComputePool.
Node ConfigWorker Pool
Architecture		spec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.workerPools[].architecture		Array element
Node ConfigWorker Pool
CPU Count		spec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.workerPools[].cpu.cpuCount		Integer
Node ConfigWorker Pool
Memory		spec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.workerPools[].memory.memory		String with units (for example, 16 GB)
Node ConfigMin Worker Nodesspec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.workerPools[].minWorkerNodes		Minimum nodes to provision
Node ConfigGPU Familyspec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.workerPools[].gpu.family		e.g., NVIDIA-A100
Node ConfigGPU Countspec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.workerPools[].gpu.gpuCount		Integer. Total across all selected edge hosts.
Node ConfigGPU Memoryspec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.nodePoolRequirements
.workerPools[].gpu.gpuMemory		String with units (for example, 80 GB). Total across all selected edge hosts.
DeploymentDeletion Policyspec.deletionPolicyValues: delete, orphan
DeploymentSettings Refspec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.settingsRef.name		Settings resource name used for Palette integration.
DeploymentSSH Keysspec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.sshKeys		Array of SSH public keys
DeploymentVIPspec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.edge.vip		Required. Immutable.
DeploymentNetwork Overlay
(enabled)		spec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.edge.networkOverlayConfig
.enabled		Boolean
DeploymentNetwork Overlay
CIDR		spec.clusterVariant.dedicated
.paletteClusterDeploymentConfig
.edge.networkOverlayConfig
.cidr		CIDR notation

Operational Labels​

Operational labels control ComputePool behavior.

Pause Label​

Use the controller.spectrocloud.com/pause label to pause ComputePool reconciliation. When set to "true" (as a string), the controller skips reconciliation for the ComputePool.

YAML path: metadata.labels

Example:

apiVersion: spectrocloud.com/v1alpha1
kind: ComputePool
metadata:
  name: ml-cluster
  namespace: my-project
  labels:
    controller.spectrocloud.com/pause: 'true'
spec:
  # ... rest of configuration

Use this label to temporarily halt operations on a ComputePool without deleting it. This is useful during maintenance windows or troubleshooting. To resume reconciliation, remove the label or set it to any value other than "true".

info

The pause label only stops normal ComputePool reconciliation. It does not prevent deletion. When a ComputePool has metadata.deletionTimestamp set, the controller's delete and finalizer logic still executes even when the pause label is present. Therefore, the pause label cannot be used to block teardown or deletion of a ComputePool.