# spectrocloud-clusters

> Create and manage Spectro Cloud Palette Edge clusters. Covers edge-native deployments including agent mode, appliance mode, and 2-node HA. Both API and Terraform.

- Author: github-actions[bot]
- Repository: nctiggy/claude-skills
- Version: 20260115185028
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/nctiggy/claude-skills
- Web: https://mule.run/skillshub/@@nctiggy/claude-skills~spectrocloud-clusters:20260115185028

---

---
name: spectrocloud-clusters
description: Create and manage Spectro Cloud Palette Edge clusters. Covers edge-native deployments including agent mode, appliance mode, and 2-node HA. Both API and Terraform.
---

# Spectro Cloud Edge Clusters

Deploy and manage Kubernetes clusters on edge infrastructure using Palette.

## Before Creating Clusters

**Ask the user:**
1. Project name? (use `spectrocloud-common` skill for UID)
2. Cluster name?
3. Infrastructure profile? (use `spectrocloud-cluster-profiles` skill)
4. Add-on profile(s)? (optional)
5. Edge host UIDs? (must be registered)
6. Deployment mode? (agent, appliance, or 2-node HA)
7. Network mode? VIP (needs IP) or Overlay
8. SSH public key(s)?
9. NTP server(s)?

**Best Practice**: Use separate infrastructure + add-on profiles.

## Edge Deployment Modes

| Mode | Nodes | BYOOS | Use Case |
|------|-------|-------|----------|
| Agent | 1 or 3+ | `system.uri: "NA"` | Existing OS |
| Appliance | 1 or 3+ | Provider image URL | Immutable |
| 2-Node HA | Exactly 2 | Provider + K3s | HA edge |

**2-Node**: K3s only, appliance mode only, `TWO_NODE=true` in CanvOS.

## API: Create Cluster

```bash
curl -s -X POST "https://api.spectrocloud.com/v1/spectroclusters/edge-native?ProjectUid=$PROJECT_UID" \
  -H "ApiKey: $PALETTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"name": "my-cluster"},
    "spec": {
      "cloudType": "edge-native",
      "profiles": [{"uid": "<infra-uid>"}, {"uid": "<addon-uid>"}],
      "cloudConfig": {
        "sshKeys": ["ssh-rsa AAAA..."],
        "vip": "192.168.1.100",
        "ntpServers": ["time.google.com"]
      },
      "machinePools": [{
        "name": "control-plane-pool",
        "size": 1,
        "controlPlane": true,
        "controlPlaneAsWorker": true,
        "edgeHosts": [{"hostUid": "<edge-host-uid>"}]
      }]
    }
  }'
```

### Overlay Network (instead of VIP)
```json
"cloudConfig": {
  "sshKeys": ["..."],
  "ntpServers": ["time.google.com"],
  "overlayNetworkConfiguration": {"enable": true}
}
```

### 2-Node HA Configuration

**Correct API structure** (differs from standard cluster):
```json
{
  "spec": {
    "cloudConfig": {
      "isTwoNodeCluster": true,
      "sshKeys": ["ssh-rsa ..."],
      "vip": "192.168.1.100",
      "ntpServers": ["time.google.com"]
    },
    "machinePoolConfig": [{
      "cloudConfig": {
        "edgeHosts": [
          {"hostUid": "<node1-uid>", "twoNodeCandidatePriority": "primary"},
          {"hostUid": "<node2-uid>", "twoNodeCandidatePriority": "secondary"}
        ]
      },
      "poolConfig": {
        "name": "control-plane-pool",
        "size": 2,
        "isControlPlane": true,
        "useControlPlaneAsWorker": true
      }
    }]
  }
}
```

**Key 2-node fields:**
- `isTwoNodeCluster: true` in `cloudConfig` (not at spec level)
- `twoNodeCandidatePriority`: `"primary"` or `"secondary"` per host
- `useControlPlaneAsWorker: true` to run workloads on both nodes
- Uses `machinePoolConfig` (not `machinePools`) with nested `cloudConfig`/`poolConfig`

## API: Other Operations

### Get Cluster
```bash
curl -s "https://api.spectrocloud.com/v1/spectroclusters/$CLUSTER_UID" \
  -H "ApiKey: $PALETTE_API_KEY" -H "ProjectUid: $PROJECT_UID"
```

### Get Kubeconfig
```bash
curl -s "https://api.spectrocloud.com/v1/spectroclusters/$CLUSTER_UID/assets/kubeconfig" \
  -H "ApiKey: $PALETTE_API_KEY" -H "ProjectUid: $PROJECT_UID" > kubeconfig.yaml
```

### Delete Cluster
```bash
curl -s -X DELETE "https://api.spectrocloud.com/v1/spectroclusters/$CLUSTER_UID" \
  -H "ApiKey: $PALETTE_API_KEY" -H "ProjectUid: $PROJECT_UID"
```

### List Edge Hosts
```bash
curl -s "https://api.spectrocloud.com/v1/edgehosts" \
  -H "ApiKey: $PALETTE_API_KEY" -H "ProjectUid: $PROJECT_UID" | \
  jq '[.items[] | {name: .metadata.name, uid: .metadata.uid, state: .status.state}]'
```

## Cluster Lifecycle

### Update Profile
Create new profile version first (see `spectrocloud-cluster-profiles`), then:
```bash
curl -s -X PUT "https://api.spectrocloud.com/v1/spectroclusters/$CLUSTER_UID/profiles" \
  -H "ApiKey: $PALETTE_API_KEY" -H "ProjectUid: $PROJECT_UID" \
  -H "Content-Type: application/json" \
  -d '{"profiles": [{"uid": "<new-version-uid>"}]}'
```

### Add Edge Host
```bash
curl -s -X PATCH "https://api.spectrocloud.com/v1/spectroclusters/$CLUSTER_UID/machinePools/worker-pool" \
  -H "ApiKey: $PALETTE_API_KEY" -H "ProjectUid: $PROJECT_UID" \
  -H "Content-Type: application/json" \
  -d '{"edgeHosts": [{"hostUid": "<new-host-uid>"}]}'
```

## Profile Variables

Override profile variables at cluster creation:
```json
"profiles": [{"uid": "<uid>", "variables": [
  {"name": "K8sPodCIDR", "value": "100.64.0.0/18"},
  {"name": "K8sServiceCIDR", "value": "100.64.64.0/18"}
]}]
```

## Additional Resources

- `references/api-examples.md` - Full API examples (multi-node, 2-node)
- `references/terraform-examples.md` - Full Terraform patterns

## Edge Host Token Creation

**IMPORTANT**: Edge host tokens are TENANT-scoped, not project-scoped. Do NOT include ProjectUid header.

```bash
# Create edge host token (NO ProjectUid header!)
curl -s -X POST "https://api.spectrocloud.com/v1/edgehosts/tokens" \
  -H "ApiKey: $PALETTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"name": "my-token"}}'

# Token value is in spec.token (NOT status.token)
TOKEN=$(echo $RESPONSE | jq -r '.spec.token')
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Enable two-node cluster to configure candidate priority" | Set `is_two_node_cluster = true` in Terraform cloud_config block |
| "Two-node candidate priority demands one primary and one secondary" | Add `two_node_role = "primary"` and `"secondary"` to each edge_host block (Terraform) |
| Terraform attribute not found | API vs Terraform naming differs - check with `terraform providers schema -json` |
| Cluster stuck provisioning | Check edge host logs: `journalctl -u spectro-stylus-agent.service -f` |
| Cluster stuck Provisioning, no nodes appearing | VMs likely in install loop - check boot order is disk-first (`scsi0;ide2`), power cycle VMs |
| 2-node cluster needs VIP | 2-node clusters cannot use overlay-only networking - must specify a VIP |
| Can't find latest K8s version | API paginates at 50 - use offset parameter to get all versions |
| "ProjectUidIsNotEmpty" on token creation | Edge host tokens are tenant-scoped - remove ProjectUid header |
| Profiles created but cluster creation fails | Check Terraform provider has `project_name` set (see `spectrocloud-cluster-profiles` skill) |

## Quick Reference

| Operation | Endpoint |
|-----------|----------|
| Create | `POST /v1/spectroclusters/edge-native` |
| Get | `GET /v1/spectroclusters/{uid}` |
| Delete | `DELETE /v1/spectroclusters/{uid}` |
| Kubeconfig | `GET /v1/spectroclusters/{uid}/assets/kubeconfig` |
| Edge Hosts | `GET /v1/edgehosts` |
| Update Profile | `PUT /v1/spectroclusters/{uid}/profiles` |

## Links

- [Edge Clusters](https://docs.spectrocloud.com/clusters/edge/)
- [Terraform Provider](https://registry.terraform.io/providers/spectrocloud/spectrocloud/latest/docs)