Sign in

stack8s - Cluster Management CLI Docs

stack8s is a control plane for hosting Enterprise Grade Kubernetes — and the AI, data, and HPC
workloads on top of it — across infrastructure you own or operate, from one
place. It delivers a fully managed Kubernetes experience (we run the managed
control planes, the networking, and the multi-region plumbing) on your own
capacity, with nothing for you to build or operate underneath.

stack8s turns your global footprint — across any cloud, colo, or on-prem
sites you operate — into a single, managed global Kubernetes platform: the
layer above a cluster, not another way to hand one out. Its standout
capability is multi-region: one cluster can span many of your
locations at once under a single control plane and a single API, with pods
networked across regions automatically. Instead of a separate cluster per
site, you (or your customers) run one global cluster and place each
workload in the region closest to the users and data it serves.

What that means for you:

  • A global product from one footprint. Your regions become a single
    Kubernetes platform your customers reach through one API — spanning locations,
    scaling and upgrading each independently, with zero cluster-ops on your side.
  • The managed layer above the metal. Around the cluster, stack8s runs host
    lifecycle (provision / drain / decommission), placement, IP & DNS, multi-level
    tenancy and metering, and an AI/ML marketplace on top — a managed product, not
    just a cluster hand-off.
  • Substrate-neutral by design. Your primary capacity is the anchor, and the
    same control plane can reach capacity across regions and providers — so a
    customer's home stays where you put it even when a workload needs to burst
    beyond a single site or cloud.

This guide is a hands-on test-drive of the core. From a single API key you'll
provision a real Kubernetes cluster on your capacity — a single-region one
first, then a global multi-region one — drive it with kubectl, run the
day-2 operations (scale, upgrade, roll), and tear it down. A handful of
commands end to end.

1. What you need

  • The stack8s binary. Download the build for your platform, verify its
    checksum, and put it on your PATH.

    Linux (x86-64):

    BASE=https://pub-82b8408b380340489ff8d407c6acb832.r2.dev/stack8s-cli/v0.1.0-rc.3
curl -fsSL -O "$BASE/stack8s-linux-amd64"
curl -fsSL -O "$BASE/SHA256SUMS"
sha256sum --ignore-missing -c SHA256SUMS             # expect: stack8s-linux-amd64: OK
chmod +x stack8s-linux-amd64 && sudo mv stack8s-linux-amd64 /usr/local/bin/stack8s

    (Linux ARM64: swap stack8s-linux-amd64 → stack8s-linux-arm64.)

    macOS (Apple Silicon):

    BASE=https://pub-82b8408b380340489ff8d407c6acb832.r2.dev/stack8s-cli/v0.1.0-rc.3
curl -fsSL -O "$BASE/stack8s-darwin-arm64"
curl -fsSL -O "$BASE/SHA256SUMS"
shasum -a 256 --ignore-missing -c SHA256SUMS         # expect: stack8s-darwin-arm64: OK
chmod +x stack8s-darwin-arm64 && sudo mv stack8s-darwin-arm64 /usr/local/bin/stack8s

    (macOS Intel: use stack8s-darwin-amd64. If Gatekeeper blocks the binary:
    xattr -d com.apple.quarantine /usr/local/bin/stack8s.)

    Verify it runs (should print v0.1.0-rc.3):

    stack8s --version

  • Your API key. We provisioned one for your account. The key alone
    identifies your tenant and your capacity; you never put an account, project,
    or fleet on the command line. Treat the key like a password — keep it
    private, and rotate with us if it's ever exposed.

Set these two values once and the rest of the guide is copy-paste:

export STACK8S_API_ENDPOINT="api.edge.dev.stack8s.io:8444"
export STACK8S_API_KEY="stk_live_YOUR_API_KEY"

Replace stk_live_YOUR_API_KEY with the key we sent you. The endpoint is
TLS-only and requires your API key — there is no unauthenticated access.

2. Verify connectivity

List your clusters. On a new account this returns an empty list — which
confirms your key works and the endpoint is reachable:

stack8s cluster list

[]

If you instead see cannot reach platform-api …, check your network can
reach api.edge.dev.stack8s.io:8444. If you see an authentication error,
re-check STACK8S_API_KEY.

3. Create a cluster

Pick a region — one of the locations where you have capacity (use the
region codes provisioned for your account). Choose a cluster name and create
it:

stack8s cluster create demo --region REGION_A --wait-timeout 25m

stack8s waits until the cluster is READY and prints it:

{
  "cluster_id": "…",
  "name": "demo",
  "region": "REGION_A",
  "phase": "READY",
  "spec": { "kubernetes_version": "v1.35.0", "tcp_replicas": 1 }
}

Notes:

  • Provisioning uses real capacity, so allow several minutes. --wait-timeout
    bounds how long the command blocks; provisioning continues server-side even
    if it elapses.
  • Add --no-wait to return immediately with the cluster accepted, then poll
    with stack8s cluster get demo.
  • Retries are safe — the command is idempotent per invocation.

4. Use the cluster

Fetch the cluster's admin kubeconfig and point kubectl at it:

stack8s cluster kubeconfig demo > demo.kubeconfig
kubectl --kubeconfig demo.kubeconfig get nodes

NAME    STATUS   ROLES    AGE   VERSION
n-…     Ready    <none>   3m    v1.35.5

The kubeconfig file is written with 0600 permissions — it is an admin
credential, so treat it accordingly.

5. Inspect

stack8s cluster list        # all your clusters
stack8s cluster get demo    # one cluster's status

6. Day-2 operations

Everything below is an async operation: stack8s blocks until it reaches a
terminal state and prints the result. Add --no-wait to any of them to return
immediately with an operation id, then poll stack8s cluster get demo. All are
idempotent per invocation, so retries are safe.

Scale a worker pool

Grow a pool to a target node count (scale-up; the target must exceed the
current count). With no --worker-pool, it targets the single default pool:

stack8s cluster scale demo --nodes 3

Upgrade the control plane

Move the control plane to a newer Kubernetes version. Supported versions are
v1.35.0 and v1.36.2:

stack8s cluster upgrade demo --kubernetes-version v1.36.2

Roll the workers

Drain and reprovision the worker nodes — either in place, or onto a new
Kubernetes version (which must not exceed the control-plane version). Control
the disruption budget with --max-unavailable / --max-surge:

# reprovision the default pool at a new version
stack8s cluster roll demo --kubernetes-version v1.36.2

# or reprovision in place (omit the version), one node at a time, keeping capacity
stack8s cluster roll demo --max-surge 1

Manage worker-pool topology (declarative)

worker-pools reconcile takes the full desired set of pools and adds /
resizes / removes to match. Preview with --dry-run first; removing or
shrinking a live pool needs --allow-destructive:

# preview adding a second pool (same region) alongside the default
stack8s cluster worker-pools reconcile demo \
  --worker-pool name=default/region=REGION_A/nodes=1 \
  --worker-pool name=batch/region=REGION_A/nodes=2 \
  --dry-run

# apply it (drop --dry-run)
stack8s cluster worker-pools reconcile demo \
  --worker-pool name=default/region=REGION_A/nodes=1 \
  --worker-pool name=batch/region=REGION_A/nodes=2

Multi-region (global) clusters

This is the headline. Span as many regions as you like in a single cluster —
one --worker-pool per region, each with its own node count. The control plane
lives in the cluster's home --region; the workers come up in their own regions
and are networked together automatically. To kubectl, it's one cluster.

Here's a global cluster — control plane in one region, workers across several:

stack8s cluster create global --region REGION_A \
  --worker-pool name=pool-a/region=REGION_A/nodes=2 \
  --worker-pool name=pool-b/region=REGION_B/nodes=1 \
  --worker-pool name=pool-c/region=REGION_C/nodes=1 \
  --worker-pool name=pool-d/region=REGION_D/nodes=1 \
  --worker-pool name=pool-e/region=REGION_E/nodes=1 \
  --wait-timeout 30m

kubectl get nodes on the result shows a worker in every region, all in one
cluster:

NAME    STATUS   VERSION   REGION (topology.kubernetes.io/region)
n-…     Ready    v1.35.5   REGION_A
n-…     Ready    v1.35.5   REGION_A
n-…     Ready    v1.35.5   REGION_B
n-…     Ready    v1.35.5   REGION_C
n-…     Ready    v1.35.5   REGION_D
n-…     Ready    v1.35.5   REGION_E

Regions are the site codes available on your account — use any where you
have capacity. If a region is temporarily out of stock, the create tells you
so — just pick another.

Day-2 works per region too. Grow one pool, or roll just another to a new
version, by naming it:

stack8s cluster scale global --worker-pool pool-c --nodes 3
stack8s cluster roll  global --worker-pool pool-e --kubernetes-version v1.36.2

Add a region later with worker-pools reconcile (list the full desired set,
including the pools you already have), or drop one with --allow-destructive.

Run stack8s cluster --help, or --help on any subcommand, for every flag.

7. Tear down

Delete the cluster when you're done — this releases the underlying capacity:

stack8s cluster delete demo

Confirm it's gone:

stack8s cluster list

[]

Troubleshooting

  • cannot reach platform-api at … — a network/endpoint issue. Confirm you
    can reach api.edge.dev.stack8s.io:8444 and that STACK8S_API_ENDPOINT is
    set correctly.
  • authentication failed … — set or re-check STACK8S_API_KEY.
  • not permitted … / not found — the name or region isn't valid for
    your account; stack8s cluster list shows what you have.
  • Add --verbose to any command to see the underlying error detail.