Skip to content
Karakoram

Replica sets

A replica-set cluster is a managed PSMDB set named rs0. Choose 1, 3, 5 or 7 data-bearing members; even counts and counts above seven are rejected. Each member is a singleton Zerops runtime with its own persistent Local Storage volume. A one-member set is useful for development but cannot retain availability during member restart, replacement or host loss.

Before creating a cluster, install and authenticate, check the version catalog, and read the placement limitations. Three members do not guarantee three physical machines.

Create

Section titled “Create”

In Clusters → Create cluster, choose replicaSet, a provider-advertised version, engine replica count and CPU/RAM/disk bounds. Keep requireTLS and private exposure unless you have a specific access plan. Names must match ^[a-z][a-z0-9]{1,11}$: 2–12 lowercase letters/digits, beginning with a letter.

Terminal window
karactl providers get psmdb
karactl clusters create demo --topology replicaSet --members 3 \
  --version 8.0.32-14 --min-ram 1 --max-ram 1 \
  --min-disk 5 --max-disk 5 --tls-mode requireTLS --wait
karactl clusters status demo
karactl clusters members demo

Use the version currently advertised by your installation, not an arbitrary apt version. The CLI supplies its own resource defaults; explicit bounds above keep this example at 1 GiB RAM and 5 GiB persistent disk per member. The provider’s omitted-field defaults are also 1 GB RAM/5 GB disk, while CLI convenience defaults allow larger maxima. CPU is expressed in cores; RAM/disk fields are GiB in the public API.

Creation is asynchronous: services are imported, artifacts deployed, agents obtain protected config, the set is initiated and system users are established. --wait follows observed cluster-generation convergence. Ready TCP alone is not replica-set health.

Observe health

Section titled “Observe health”
Terminal window
karactl clusters get demo -o yaml
karactl clusters members demo
karactl clusters placement demo
karactl operations cluster demo
karactl events list --cluster demo

Inspect phase/message/conditions, observedGeneration, member health/state/role, agent connectivity/configVersion, binary version and lag. A caught-up secondary is different from a service merely marked ACTIVE by Zerops. The cluster overview and topology tabs expose these observations; monitoring adds time series.

Default status connection URIs omit passwords. Explicit connection reveal requires a separate permission; use application-specific users for workloads.

Add, remove and replace members

Section titled “Add, remove and replace members”
Terminal window
karactl clusters scale demo --members 5 --wait
karactl clusters scale demo --members 3 --wait
karactl clusters replace-member demo demom1 --wait

Use an actual member name from the inventory for replacement. Added members join non-voting with priority zero, initial-sync, then become voters after observed healthy replication and lag at most ten seconds. Scale-down removes high-index members safely, stepping down a primary when required and checking voting majorities. Replacement creates a new monotonic member identity rather than reusing the old hostname; names can therefore have gaps. At seven voters it does not create an eighth voter during replacement.

An unhealthy set can block disruptive work. Restore quorum/replication health rather than repeatedly submitting replacement or restart commands. A single-member replacement is necessarily a special availability transition, not a promise of zero downtime. Troubleshooting explains stuck deployment/config states.

Delete or suspend

Section titled “Delete or suspend”

Deletion options control two separate assets: database volumes and PBM backups.

Terminal window
# Suspend: remove runtimes, retain database volumes and recovery objects.
karactl clusters delete demo --keep-volumes --keep-backups --wait
karactl clusters resume demo --wait


# Destructive full deletion: volumes and owned backups are removed.
karactl clusters delete demo --wait

With keepVolumes, the cluster remains Suspended, retains secrets/volume identity and can resume by recreating its runtimes. Keeping volumes does not automatically keep backups: specify both flags if you want both. Without retained volumes, deletion is not resumable. With --keep-backups, backup records, snapshot provenance and protected physical-recovery credentials survive full deletion: use karactl backups list/get/delete with the original cluster name, or create a new compatible cluster with spec.dataSource referencing a retained successful snapshot. See retained-backup management and cloning. Retained backups do not recreate the deleted resource or volumes; preserve control-plane state and its encryption key for disaster recovery.

Normal scale-down/replacement removes the retired member’s volume; cluster deletion retention is not a per-member retention option. Cleanup of recovery objects runs before removing agents that PBM needs. See backups and restore and operations.