| sidebar_label | Platform External Database |
|---|---|
| sidebar_position | 1 |
| title | Platform External Database |
| description | Deploy vCluster Platform with an external database for high availability and multiple replicas. |
import VersionBadge from '@site/src/components/VersionBadge';
An external database deployment runs multiple vCluster Platform replicas in a single Kubernetes cluster, all backed by an external database through Kine, which provides an etcd-compatible API backed by relational databases. Leader election ensures that only one replica writes to the database at a time, while the remaining replicas serve read traffic and stand ready to take over if the leader fails. This eliminates the platform as a single point of failure within the region.
The default single-replica platform deployment works for most environments. Consider an external database deployment when you need one or more of the following:
- Control plane resilience: If the platform pod or its node goes down, another replica takes over leadership automatically. Connected clusters continue operating through the surviving replicas.
- Strict RBAC environments: Run the platform on a control plane cluster with limited permissions, similar to Least Privilege Mode for agents. An external database lets the platform replicas use a shared backend without requiring broad cluster-level access.
- Protection against node failures: Spreading replicas across nodes (using pod anti-affinity or topology spread constraints) ensures that a single node failure does not take down the platform.
| External database | Multi-region platform | Regional Cluster Endpoints | |
|---|---|---|---|
| What is replicated | Multiple platform replicas in a single cluster | The platform itself (full replicas in each region) | Only the agent endpoints (platform stays in one region) |
| Shared database | Yes — all replicas share a single Kine-backed database | Yes — all regions share a single Kine-backed database | No — single platform database |
| Failover | Automatic via leader election within the cluster | Automatic via DNS health checks | No platform failover |
| Use case | Platform HA within a single region | Platform HA, low-latency platform API access | Low-latency kubectl access to clusters |
- External database operations: An external database deployment requires provisioning and managing a database (RDS or equivalent), adding operational overhead compared to the default embedded PostgreSQL.
- Cost control unavailable: The cost control feature requires the embedded single-region database and is not compatible with the external Kine backend.
:::warning Converting an existing single-replica platform installation to an external database deployment is not supported. An external database deployment must be configured as a fresh installation following the steps below. :::