spectrocloud-agent-mode

Agent Mode lets you bring your own host and OS to be managed by Palette. The Palette agent is installed on existing infrastructure - bare metal, VMs, cloud instances, or edge devices.

Key Constraints

• Node counts: 1-node or 3+ nodes only. No 2-node deployments in agent mode.
• BYOOS pack: Must use the Agent Mode preset, which sets system.uri: "NA" (not a custom provider image)
• Architecture: AMD64 and ARM64 supported

For API auth and project UID lookup, use the spectrocloud-common skill.

Prerequisites

Hardware

• CPU: 4+ cores
• Memory: 8+ GB
• Storage: 100+ GB SSD

Software (Ubuntu example)

sudo apt-get update && sudo apt-get install -y \
  bash jq zstd rsync systemd-timesyncd conntrack iptables rsyslog \
  --no-install-recommends

Required services:

• systemd-resolved (for DNS/overlay networks)
• systemd-networkd (for static IP/overlay networks)

Registration Tokens

Tokens link Edge hosts to a Palette project. Create via UI:

1. Log in as Tenant Admin
2. Go to Tenant Settings → Registration Tokens
3. Click Add New Registration Token
4. Set name, optional description, Default Project, and expiration
5. Save immediately - full token only shown once

Important: Either set a Default Project on the token OR provide stylus.site.projectName in user-data.

Installation (Central Management Mode)

Step 1: SSH to host

ssh -i /path/to/key ubuntu@<host-ip>

Step 2: Export token

export TOKEN=<your-registration-token>

Step 3: Create user-data

Minimal configuration (required fields only):

#cloud-config
install:
  reboot: true
stylus:
  site:
    edgeHostToken: <registration-token>
    paletteEndpoint: api.spectrocloud.com
    projectName: <project-name>

Before proceeding, ask if the user needs any advanced configurations:

• Custom edge host name (stylus.site.name)
• Static IP / network configuration
• Custom partition sizes
• Proxy settings
• Custom CA certificates
• Tags/labels for the edge host

Advanced configuration example:

#cloud-config
install:
  reboot: true
  partitions:
    oem:
      size: 5120      # MB
      fs: ext4
    system:
      size: 8192
    recovery-system:
      size: 10000
    passive:
      size: 8192

stylus:
  site:
    edgeHostToken: <registration-token>
    paletteEndpoint: api.spectrocloud.com
    projectName: <project-name>
    name: custom-edge-host-name        # Optional: custom name instead of auto-generated
    network:
      httpProxy: http://proxy:8080
      httpsProxy: http://proxy:8080
      noProxy: localhost,127.0.0.1,.local
    caCerts:
      - |
        -----BEGIN CERTIFICATE-----
        <CA cert content>
        -----END CERTIFICATE-----
    tags:
      environment: production
      location: datacenter-1
  installationMode: connected          # connected or airgap
  managementMode: central              # central or local

Create the user-data file:

cat << EOF > user-data
#cloud-config
install:
  reboot: true
stylus:
  site:
    edgeHostToken: $TOKEN
    paletteEndpoint: api.spectrocloud.com
    projectName: <project-name>
EOF

Step 4: Download and run installer

# Latest version (SaaS)
curl -LO https://github.com/spectrocloud/agent-mode/releases/latest/download/palette-agent-install.sh
chmod +x palette-agent-install.sh

# For FIPS compliance, use palette-agent-install-fips.sh

export USERDATA=./user-data
sudo --preserve-env ./palette-agent-install.sh

Host reboots automatically after installation.

For Dedicated/On-Prem Palette

Get your Palette's agent version first:

curl -s "https://<palette-endpoint>/v1/services/stylus/version" \
  -H "Content-Type: application/json" \
  -H "Apikey: <api-key>" | \
  jq -r '.spec.latestVersion.content | match("version: ([^\n]+)").captures[0].string'

Then download matching version:

curl -LO "https://github.com/spectrocloud/agent-mode/releases/download/v<version>/palette-agent-install.sh"

Validate Registration

1. Log into Palette console
2. Navigate to Clusters → Edge Hosts tab
3. Verify host appears with status Registered

Troubleshooting: If previously registered, delete the Edge host from Palette first - duplicate IDs cause registration failure.

Create Cluster Profile

1. Go to Profiles → Add Cluster Profile
2. Select type: Full
3. Select cloud type: Edge Native
4. Add BYOS Edge OS pack (version 2.1.0+)
5. Critical: Select Agent Mode preset in pack values
6. Add remaining layers (K8s, CNI, CSI, add-ons)

Agent Services & Logs

Check agent status

sudo systemctl status spectro-stylus-agent.service
sudo systemctl status spectro-stylus-operator.service

View logs

journalctl -u spectro-stylus-agent.service -f
journalctl -u spectro-stylus-operator.service -f

Key log files

• /var/log/stylus-upgrade.log
• /var/log/kube-init.log
• /var/log/kube-join.log

Uninstall Agent

No official uninstall documentation exists. Manual cleanup:

1. Delete from Palette

Remove the Edge host from Palette console first (Clusters → Edge Hosts → Delete)

2. Stop services

sudo systemctl stop spectro-stylus-agent.service
sudo systemctl stop spectro-stylus-operator.service
sudo systemctl disable spectro-stylus-agent.service
sudo systemctl disable spectro-stylus-operator.service

3. Remove Palette directories

sudo rm -rf /usr/local/spectrocloud/
sudo rm -rf /var/lib/spectro/
sudo rm -rf /opt/spectrocloud/

4. Clean up Kubernetes (if cluster was deployed)

# Reset kubeadm if used
sudo kubeadm reset -f

# Remove K8s directories
sudo rm -rf /etc/kubernetes/
sudo rm -rf /var/lib/kubelet/
sudo rm -rf /var/lib/etcd/
sudo rm -rf ~/.kube/

5. Remove systemd units

sudo rm -f /etc/systemd/system/spectro-*.service
sudo systemctl daemon-reload

6. Reboot

sudo reboot

Proxy Configuration

If behind a proxy, export before installation:

export http_proxy=http://proxy:port
export https_proxy=http://proxy:port
export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

Quick Reference

| Item | Value | |------|-------| | Install script | https://github.com/spectrocloud/agent-mode/releases/latest/download/palette-agent-install.sh | | FIPS script | ...palette-agent-install-fips.sh | | Agent service | spectro-stylus-agent.service | | Operator service | spectro-stylus-operator.service | | Config location | /var/lib/spectro/userdata | | Default API endpoint | api.spectrocloud.com |

Links

• Agent Mode Overview
• Install Agent
• Create Registration Token
• Edge Troubleshooting
• GitHub Releases