Skip to main content
Version: v1.1.x

Air-Gapped Deployment Guide

This guide walks through an end-to-end deployment of PaletteAI VerteX in an air-gapped environment on edge appliances, from ISO installation through workload cluster deployment. Follow the steps in order — several steps have hard prerequisites on earlier ones completing successfully.

Overview​

StepTopic
1Download the PaletteAI VerteX ISO from Artifact Studio
2Boot the node from the ISO and complete the Palette TUI
3Access Local UI and form the management cluster
4Download pack bundles from Artifact Studio Packs Catalog
5Import pack bundles into the internal Zot registry
6Import Cluster Profiles into Palette VerteX
7Register edge compute nodes
8Create a Compute Pool
9Deploy a Profile Bundle
10Validate the workload cluster

Prerequisites​

  • A machine with internet access (for downloading the ISO and pack bundles before transfer to the air-gapped environment).
  • The paletteai CLI installed on your machine. Refer to the PaletteAI CLI reference for installation instructions.
  • Access to Artifact Studio. Contact your Spectro Cloud representative if you do not have access.
  • Hardware meeting the requirements in Appliance Installation.

Step 1 — Download the ISO​

  1. Log in to Artifact Studio.

  2. On the landing page, locate the Install PaletteAI VerteX card and click Download. This downloads the management appliance ISO.

info

Artifact Studio has two separate download areas. The landing page cards provide the management appliance ISO used in this step. The Packs Catalog (artifact-studio.spectrocloud.com/packs-catalog) is a separate area used in Step 4 to download pack bundles (.zst files) for the internal Zot registry. These are distinct steps performed at different phases of the deployment.

  1. Transfer the ISO to a bootable device (USB drive or datastore) accessible to each appliance node.

Step 2 — Install the Edge Image and Complete the TUI​

Boot each appliance node from the ISO and configure it using the Palette TUI.

For detailed instructions, refer to Install the PaletteAI Edge Image.

Key steps:

  • Select the target disk and post-install action in the interactive installer.
  • After reboot, complete the Palette TUI: set credentials, configure network adapters, and set DNS.
  • After the TUI completes, the terminal displays Device Info and prompts you to continue with Local UI.

For air-gapped nodes that need SSH access during setup, configure SSH keys in user-data at the initramfs stage before booting. Refer to Configure SSH Access for Edge Nodes.

Step 3 — Form the Management Cluster in Local UI​

Access Local UI on the appliance and form the PaletteAI management cluster.

For detailed instructions, refer to Complete the Deployment.

  • Single node: Open https://<node-ip>:5080 and log in. No host linking is required.
  • Three-node: Open Local UI on the designated leader node. Use Linked Edge Hosts to link the two follower nodes. Wait for all hosts to show Ready / Synced / Healthy status.

After infrastructure is prepared, create the Palette VerteX cluster and install PaletteAI. Refer to Deploy Cluster and Install PaletteAI.

Step 4 — Download Pack Bundles from Artifact Studio Packs Catalog​

Pack bundles (.zst files) are separate from the ISO and must be downloaded from the Packs Catalog.

  1. Log in to Artifact Studio on a machine with internet access.

  2. Navigate to the Packs Catalog (artifact-studio.spectrocloud.com/packs-catalog).

  3. Search for and download each pack required by your Cluster Profiles. For PaletteAI VerteX edge deployments, the required packs typically include:

    PackVersion
    edge-native-byoi2.1.0
    edge-k8s1.34.2 or 1.35.3
    cni-cilium-fips1.19.1 (VerteX)
    csi-longhorn-fips1.10.1 (VerteX)
    lb-metallb-helm0.15.3
    kgateway2.2.2-rev1
    registry-connect0.1.0
    info

    The nvidia-gpu-operator-ai pack is not available in Artifact Studio. Use `paletteai mirror

export-packon a connected machine and thenpaletteai mirror push` to transfer it to the air-gapped Zot registry. Refer to Deploy Profile Bundles in Air-Gapped Environments for the export and push workflow.

:::

info

MetalLB (lb-metallb-helm) has no FIPS variant. If your Tenant is configured for FIPS-only packs, enable Allow non-FIPS packs in Tenant Settings before importing the pack.

  1. Transfer the downloaded .zst files to the air-gapped environment.

    tip

    The filename stem of each .zst file must match <name>-<version> exactly (for example, edge-k8s-1.34.2.zst). Do not rename the files.

Step 5 — Import Pack Bundles into the Internal Zot Registry​

Push the pack bundles into the Zot registry that is running on the management cluster.

  1. Retrieve the Zot credentials from the management cluster:

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

  2. Push each pack bundle to Zot using the paletteai mirror push command:

    paletteai mirror push \
      --registry <vertex-ip>:30003 \
      --username <zot-username> \
      --password <zot-password> \
      --pack-bundle /path/to/<pack-name>-<version>.zst

    Repeat for every .zst file you downloaded in Step 4.

  3. Verify the pack is available in Zot:

    curl --insecure --user <zot-username>:<zot-password> \
      https://<vertex-ip>:30003/v2/_catalog
warning

Cluster Profiles cannot be imported into Palette VerteX until all packs they reference are present in the Zot registry. Complete this step in full before proceeding to Step 6.

Step 6 — Import Cluster Profiles into Palette VerteX​

With all packs available in Zot, import the Cluster Profiles that your Profile Bundle requires.

  1. Log in to the Palette VerteX UI.

  2. Navigate to Profiles and click Import.

  3. Upload the Cluster Profile manifest from your extracted bundle archive. Repeat for each profile.

  4. Confirm that each profile shows a Ready or Active status before proceeding.

Step 7 — Register Edge Compute Nodes​

Register each bare-metal or virtual edge node with the Palette VerteX management cluster using a pairing key.

For detailed instructions, refer to Register an Edge Node.

Key steps:

  1. Generate a pairing key from the Palette VerteX UI under Edge Hosts.

  2. Embed the pairing key, SSH keys, and (in air-gapped environments) the internal Zot registry credentials in the node's user-data YAML.

  3. Boot the node from the PaletteAI ISO with the user-data applied.

  4. Verify the node appears in the Edge Hosts list with a Registered status.

Step 8 — Create a Compute Pool​

Create a Compute Pool that references the registered edge node and the Cluster Profiles imported in Step 6.

Refer to Create and Manage Compute Pools.

When configuring the Compute Pool, set the VIP address to an unused IP address on your network. The VIP cannot be changed after the Compute Pool is created.

Step 9 — Deploy a Profile Bundle​

Deploy a Profile Bundle that references your Compute Pool and includes the workload configurations for your AI/ML environment.

Refer to Deploy Profile Bundles in Air-Gapped Environments for the full workflow, including:

  • Downloading and extracting the bundle archive.
  • Uploading pack content through the Palette VerteX Local UI.
  • Mirroring Helm charts and container images to the internal Zot registry using paletteai mirror.
  • Patching mural-variables for the air-gapped environment.
  • Copying the Zot CA certificate to the spoke cluster namespace.

Step 10 — Validate the Workload Cluster​

After the Profile Bundle deployment completes, verify that the workload cluster is running.

  1. In the Palette VerteX UI, navigate to Clusters and confirm the cluster status is Running.

  2. Check the Compute Pool status in the PaletteAI UI. The Overview tab should show the cluster in a healthy state.

  3. Optionally, verify cluster access with kubectl:

    kubectl get nodes --kubeconfig /path/to/workload-cluster-kubeconfig

    All nodes should show Ready status.

If the node remains stuck in provisioning, refer to Node Stuck in Provisioning (Air-Gapped).

Resources​