Skip to main content

Managed Embedded Etcd


If you already have an existing vCluster that uses the default SQLite storage backend, vCluster.Pro is able to automatically migrate the SQLite database to etcd. Be careful though, as soon as the datastore is migrated, migrating back isn't possible anymore.

vCluster.Pro allows you to enable an embedded managed etcd server instead of using the default SQLite backend or a custom managed external backend. To enable embedded etcd, start the vCluster with the following configuration:

enabled: true

For k0s, k8s, eks, if you want to enable high availability, you need to first enable embeddedEtcd with syncer.replicas set to 1, and then do a second upgrade with syncer.replicas set to 3

When migrating from the default etcd to embedded etcd with k8s and eks, make sure to set embeddedEtcd.migrateFromEtcd to true. If it is not done, you may lose your data depending on the behavior of your storage class. Once you have migrated the data and verified it is working as expected, you can do a second upgrade with embeddedEtcd.migrateFromEtcd set to false

Embedded etcd is also a requirement to run vCluster with the default k3s distro in high-availability mode.

When enabled, vCluster will start managing an embedded etcd cluster within the syncer container. vCluster will automatically add or remove peers based on new replicas of the statefulset.


Even though k3s itself has a similar feature, vCluster does not reuse this, as k3s does not manage upscaling or downscaling the etcd cluster beyond certain replicas, e.g. downscaling the control plane from 2 to 1 replicas is not supported with k3s, but works with vCluster.Pro.

Upgrading existing k3s vClusters

vCluster will automatically upgrade any existing SQLite database to the embedded etcd as soon as the feature is enabled. There is no other configuration needed. vCluster.Pro will rename the sqlite database from /data/server/db/state.db to /data/server/db/state.db.migrated after successful migration.

Advantages of using a Managed Embedded Etcd over default SQLite

SQLite is based on Kine and does not scale well for production clusters that should host many objects within the vCluster. Within our tests, SQLite performed a lot worse (5x slower) for clusters with many objects due to high iops and limited caching. An external datastore is the much better option in this regard or using an embedded etcd server. For very small ephemeral vClusters, SQLite is sufficient though. Another advantage of the embedded etcd server is the easy to enable high availability mode, where you can just upscale any existing vCluster to multiple replicas if the vCluster is growing, which scales very well.