Skip to main content
Version: main 🚧

External database

Limited vCluster Tenancy Configuration Support

This feature is only available for the following:

Running the control plane as a container and the following worker node types:
  • Host Nodes
  • Private Nodes
Enterprise-Only Feature

This feature is an Enterprise feature. See our pricing plans or contact our sales team for more information.

Introduction​

This guide explains how to configure an external database as the backing store for a virtual cluster. A backing store is a persistent storage solution that maintains the state and data of the virtual cluster. Using an external database can provide better performance, scalability, and data persistence compared to the default embedded storage.

Configure this feature to use an external database such as MySQL or PostgreSQL for your virtual cluster's backing store.

External database configuration
controlPlane:
  backingStore:
    database:
      external:
        enabled: true
        dataSource: CONNECTION_STRING
        connector: CONNECTOR_STRING

Prerequisites​

Before configuring an external database for your virtual cluster, ensure you have the following prerequisites based on your chosen method:

Data source (direct connection)​

  • A running MySQL or PostgreSQL database server
  • admin credentials and connection string for the database
  • Network connectivity from the virtual cluster to the database server

Connector (platform-managed)​

Platform Setup Required

The connector method requires the vCluster Platform to be installed and properly configured. This must be completed by an administrator before using external databases.

  1. vCluster Platform installation: The platform must be installed and accessible in your Kubernetes cluster
  2. Database connector secret: A platform administrator must create a database connector secret
  3. Platform API key: Your virtual cluster must be connected to the platform
info

The connector option provides automatic database provisioning, credential management, and cleanup when the virtual cluster is deleted. The dataSource option gives you direct control but requires manual database and user management.

Connector and data source​

There are two mutually exclusive options for using an external backing store.

dataSource: assign a connection string to dataSource that the virtual cluster uses for its control plane backing store.

connector: assign a name of a connector secret that exists in an instance of the platform in the installed namespace. The platform uses the secret to automatically provision a separate database within the database server for the virtual cluster. It also creates a non-privileged user that can only interact with the virtual cluster's database. The virtual cluster receives a connection string built from the user and database.

ConnectorDataSource
MySQL SupportYesYes
PostgreSQL SupportYesYes
Share Across virtual clustersYesNo
Automatic DB CleanupYesNo
Credential stored in secretYesNo

Datasource configuration​

Replace CONNECTION_STRING with the connection string for your database. Examples:

  • PostgreSQL: postgres://username:password@hostname:5432/vcluster-db
  • MySQL: mysql://root:password@tcp(192.168.86.9:30360)/vcluster

Connector configuration​

After completing the prerequisites, reference the connector secret in your virtual cluster configuration:

Connector configuration
controlPlane:
  backingStore:
    database:
      external:
        enabled: true
        connector: my-database-connector  # Name of the connector secret created above
note

The virtual cluster must be connected to the platform to use the connector. This enables centralized management and monitoring of virtual clusters.

Config reference​

external required object ​

External defines that an external database should be used as the backend for the virtual cluster

enabled required boolean false ​

Enabled defines if the database should be used.

dataSource required string ​

DataSource is the kine dataSource to use for the database. This depends on the database format. This is optional for the external database. Examples:

  • mysql: mysql://username:password@tcp(hostname:3306)/k3s
  • postgres: postgres://username:password@hostname:5432/k3s

identityProvider required string ​

IdentityProvider is the kine identity provider to use when generating temporary authentication tokens for enhanced security. This is optional for the external database. Examples:

  • aws: RDS IAM Authentication

keyFile required string ​

KeyFile is the key file to use for the database. This is optional.

certFile required string ​

CertFile is the cert file to use for the database. This is optional.

caFile required string ​

CaFile is the ca file to use for the database. This is optional.

extraArgs required string[] [] ​

ExtraArgs are additional arguments to pass to Kine.

connector required string ​

Connector specifies a secret located in a connected vCluster Platform that contains database server connection information to be used by Platform to create a database and database user for the vCluster. and non-privileged user. A kine endpoint should be created using the database and user on Platform registration. This is optional.