Multi-Cluster Deployments

import { Aside } from ‘@astrojs/starlight/components’;

This guide requires a Satusky account with multi-cluster enabled and at least two zones provisioned. Single-zone development accounts will see the CLI flags accepted but the deployment will only land on the single available cluster. Flags like `--multicluster` and `--zone` are accepted by the CLI at all tiers — the multi-cluster behavior is gated at the infrastructure level.

Multi-cluster deployments run your application simultaneously in two or more geographic zones. Satusky coordinates the deployment across clusters from a single CLI command, so you don’t need to manage multiple kubectl contexts or kubeconfigs.

When to Use Multi-Cluster

• High availability: survive a full zone outage without downtime
• Geographic redundancy: disaster recovery with a warm standby
• Reduced latency: serve traffic from the cluster closest to your users (active-active)

Multi-cluster doubles your resource consumption and cost. Start with a single cluster and migrate once you have a concrete HA requirement.

---

Prerequisites

• Active Satusky account with multi-cluster enabled
• A working single-cluster deployment (see Deploying Your First App)
• Two zones available — check with 1ctl cluster zones

---

Step 1: Check Available Zones and Clusters

Run this to see the zones your account can deploy to:

1ctl cluster zones

Actual output (single-zone account):

ZONE        LABEL                        CLUSTER
----        -----                        -------
my-kul-1b   MY — Kuala Lumpur (KUL-1B)   kul

On a multi-cluster account with both zones active, you would also see my-bki-1a (Kota Kinabalu). If your account only shows one zone, contact support to enable multi-cluster.

To see your cluster details including health status:

1ctl cluster list

Example output:

ID    NAME                 ZONE        ENDPOINT                      HEALTHY   DEFAULT   PRIORITY
--    ----                 ----        --------                      -------   -------   --------
kul   satusky-cluster      my-kul-1b   cluster-01.satusky.com:6443   ✓         ★         1
bki   satusky-cluster-02   my-bki-1a   cluster-02.satusky.com:6443   ✓                   2

Columns:

• DEFAULT (★) — the cluster used when no --zone is specified
• PRIORITY — used for backup scheduling; priority 1 is the primary

---

Step 2: Choose a Mode

Active-Passive (recommended starting point)

One cluster serves all traffic. The second cluster is a warm standby — running and up to date, ready to serve if the primary fails. Backups are auto-enabled.

Best for: Disaster recovery, compliance requirements for geographic redundancy, cost-conscious HA.

Active-Active

Both clusters serve traffic simultaneously, typically via a global load balancer or GeoDNS. Requests are distributed across zones.

Best for: Latency reduction for users in different regions, maximum throughput.

Requirement: Your application must be stateless or use a data layer that handles concurrent writes from both clusters (e.g., CockroachDB, YugabyteDB).

---

Step 3: Target a Specific Zone

To pin a deployment to one zone, use --zone:

1ctl deploy \
  --image registry.satusky.com/myorg/myapp:latest \
  --zone my-kul-1b

Valid zone values come from 1ctl cluster zones. The flag is accepted regardless of account tier; on a single-zone account it simply deploys to the only available zone.

---

Step 4: Deploy Active-Passive

1ctl deploy \
  --image registry.satusky.com/myorg/myapp:latest \
  --multicluster \
  --multicluster-mode active-passive \
  --backup-enabled \
  --backup-schedule daily \
  --backup-retention 168h \
  --backup-priority-cluster 1

What each flag does:

Flag	Description
--multicluster	Enables multi-cluster deployment across KL and BKI clusters (default: false)
--multicluster-mode active-passive	Primary cluster (priority 1, KL) handles all traffic; BKI is warm standby (default: active-passive)
--backup-enabled	Enables periodic state backups (auto-enabled for active-passive; default: true)
--backup-schedule daily	Backup frequency: hourly, daily, or weekly (default: daily)
--backup-retention 168h	How long to keep backups: 24h, 72h, 168h, 720h (default: 168h = 7 days)
--backup-priority-cluster 1	Which cluster runs backups: 1 = Primary/KL, 2 = Secondary/BKI (default: 1)

On a single-zone development account, `--multicluster` is accepted without error, but the deployment lands on the single available cluster. You will not see a second zone entry until multi-cluster infrastructure is provisioned for your account.

---

Step 5: Deploy Active-Active

1ctl deploy \
  --image registry.satusky.com/myorg/myapp:latest \
  --multicluster \
  --multicluster-mode active-active \
  --backup-enabled \
  --backup-schedule hourly \
  --backup-retention 72h

For active-active with autoscaling on each cluster independently:

1ctl deploy \
  --image registry.satusky.com/myorg/myapp:latest \
  --multicluster \
  --multicluster-mode active-active \
  --hpa \
  --hpa-min-replicas 2 \
  --hpa-max-replicas 10 \
  --hpa-cpu-target 70 \
  --backup-enabled \
  --backup-schedule hourly \
  --backup-retention 72h

---

Step 6: Verify

1ctl deploy list

Actual output format (columns are DEPLOYMENT ID, HOSTNAMES, TYPE, STATUS, CREATED — there is no ZONE column in deploy list):

DEPLOYMENT ID                         HOSTNAMES                             TYPE        STATUS     CREATED
────────────────────────────────────  ────────────────────────────────────  ──────────  ─────────  ────────────
68a68f73-2cec-4dae-9e40-0e1ad032be9a  c7d2a022-07bf-41f3-b51c-5ebb27365fc4  production  completed  just now

To see zone and cluster detail for a specific deployment:

1ctl deploy get --deployment-id <id>

---

Data Considerations

This section describes architectural guidance — not CLI-testable behavior. These are recommendations for how to structure your application and database layer, not features enforced by the CLI.

The biggest challenge with multi-cluster is data consistency.

Stateless applications

No problem. Each cluster runs independent replicas. Use shared object storage for files. Older docs mention 1ctl storage, but that command group was not present in the current user-facing 1ctl --help verified for v0.8.3; verify your installed CLI exposes it before relying on those commands.

Databases

Databases are the hard part. Options:

1. Primary-replica replication: run the database only on the primary cluster, replicate reads to the secondary. Works for active-passive.

2. Multi-primary (distributed DB): use a database that natively supports multi-region writes (CockroachDB, YugabyteDB, Vitess). Required for active-active with consistent writes.

3. Application-level sharding: route writes to one region, reads to either. Requires application logic.

Satusky does not manage database replication across clusters — that is handled at the application layer.

---

Backup and Recovery

With --backup-enabled, Satusky takes periodic snapshots of your deployment state stored in object storage, usable to restore a cluster after a failure.

Backup schedule options:

• hourly — every hour
• daily — once per day (default)
• weekly — once per week

Retention options: 24h, 72h, 168h (7 days), 720h (30 days)

To switch the backup-performing cluster after a failover event:

1ctl deploy \
  --multicluster \
  --multicluster-mode active-passive \
  --backup-priority-cluster 2

Actual failover testing (cutting traffic from one zone to another, GeoDNS changes, verifying standby serves correctly) requires production infrastructure with both zones healthy and a global load balancer configured. This cannot be tested in a development environment.

---

Cost

Multi-cluster deployments consume resources in both zones. A deployment with 2 replicas in active-passive runs 4 pods total (2 per cluster). Plan your credit usage accordingly.

To check recent machine usage:

1ctl credits usage --days 7

If no machines have run in the last 7 days, you’ll see:

💡 No machine usage found for the last 7 days

To check your current balance and tier limits:

1ctl credits balance

Example output:

Credit Balance
──────────────
Organization ID: <your-org-id>
Balance: $388.16 MYR
Last Updated: 6 days ago

Tier Status
───────────
Current Tier: Pro

Resource Limits
───────────────
CPU: 8 cores
Memory: 16Gi
Pods: 50
PVCs: 20