Database Connector

info

This feature is available from the Platform version v4.1.0 and was introduced in vCluster version v0.21.0

		Enterprise
Available in these plans	Free	Dev	Prod	Scale
Database Connector
EKS Pod Identity for External Database Connections

The database connector feature allows an admin to configure a database server to manage backing stores for multiple virtual clusters. For each virtual cluster, the feature automatically creates an independent database and non-privileged user. Read more about the use of external databases in the External Database documentation.

Compatibility matrix

The database connector works with PostgreSQL and MySQL compatible DBMS. While especially the managed database offerings from hyperscalers sometimes do not expose full admin privileges, ship with a non-default feature set, or use special configuration, it is not possible to guarantee compatibility with all of them. The following table outlines the current support status:

Database type	Environment	Supported	Tested versions
PostgreSQL	Self-hosted / upstream	v14   v15+	v14, v15, v16, v17, v18
	AWS Aurora PostgreSQL	v14   v15+	v14, v15, v16, v17
	AWS RDS PostgreSQL	v14   v15+	v14, v15, v16, v17, v18
	Azure Database for PostgreSQL flexible server	v14   v15+	v14, v15, v16, v17, v18
	Google Cloud SQL PostgreSQL		v14, v15, v16, v17, v18
MySQL	Self-hosted / upstream		v5, v8, v9
	AWS Aurora MySQL		v5, v8, v9
	AWS RDS MySQL		v5, v8, v9
	Azure Database for MySQL flexible server	️1	v5, v8, v9
	Google Cloud SQL MySQL		v5, v8, v9
MariaDB	AWS RDS MariaDB	v10 v11 ️1	v10, v11

¹ Needs explicit configuration to allow unencrypted transport: require_secure_transport set to OFF.

info

While other, not mentioned, PostgreSQL/MySQL compatible databases may work, they have not been tested.

How cloud database offerings are tested

The following sections describe how each hyperscaler database offering is tested, including any notable deviations from a default deployment.

AWS

Aurora PostgreSQL

Tested with major versions v14, v15, v16, and v17.

• Instance class: db.t3.medium
• High availability: Single-instance Aurora cluster (no read replicas)

Aurora MySQL

Tested with major versions v5, v8, and v9.

• Instance class: db.t3.medium
• High availability: Single-instance Aurora cluster (no read replicas)

RDS PostgreSQL

Tested with major versions v14, v15, v16, v17, and v18.

• Instance class: db.t3.micro
• Storage: 20 GB (General Purpose SSD)
• High availability: No, Single-AZ

RDS MySQL

Tested with major versions v5, v8, and v9.

• Instance class: db.t3.micro
• Storage: 20 GB (General Purpose SSD)
• High availability: No, Single-AZ

RDS MariaDB

Tested with major versions v10 and v11.

• Instance class: db.t3.micro
• Storage: 20 GB (General Purpose SSD)
• High availability: No, Single-AZ
• Secure transport: For MariaDB v11+, require_secure_transport is enabled by default. A custom DB parameter group is used to set require_secure_transport=OFF (deviation from default). For v10, no changes are needed.

Azure

Azure Database for PostgreSQL flexible server

Tested with major versions v14, v15, v16, v17, and v18.

• SKU / tier: Burstable, Standard_B1ms
• High availability: No (single server)

Azure Database for MySQL flexible server

Tested with major versions v5, v8, and v9.

• SKU / tier: Burstable, Standard_B1ms
• High availability: No (single server)
• Secure transport: require_secure_transport set to OFF (deviation from default).

GCP

Google Cloud SQL PostgreSQL

Not supported as Google Cloud SQL PostgreSQL does not expose a user with full admin privileges and thus, altering database owners is not supported.

Google Cloud SQL MySQL

Tested with major versions v5, v8, and v9.

• Edition / tier: Enterprise, db-f1-micro
• High availability: No (single-zone)
• User setup: A dedicated database user is created with a % host wildcard to allow connections from any host.

Prerequisites

• Administrator access to a Kubernetes cluster: See Accessing Clusters with kubectl for more information. Your current kube-context must have administrative privileges, which you can verify with kubectl auth can-i create clusterrole -A

  info

  To obtain a kube-context with admin access, ensure you have the necessary credentials and permissions for your Kubernetes cluster. This typically involves using kubectl config commands or authenticating through your cloud provider's CLI tools.

• helm installed: Helm v3.10 is required for deploying the platform. Refer to the Helm Installation Guide if you need to install it.

• kubectl installed: Kubernetes command-line tool for interacting with the cluster. See Install and Set Up kubectl for installation instructions.

• A running PostgreSQL or MySQL compatible DBMS and admin credentials to the server

Configuration

Create platform admin connector secret

A connector secret is a secret that can be used with a platform feature or integration.

For the platform to start using a database server, a secret must be created that contains admin credentials for the server. The secret must:

• Contain the loft.sh/connector-type label with the shared-database value
• Reside in the same namespace as the platform
• Contain the fields:
  • endpoint
  • password
  • port
  • user

To create a database connector secret in the UI, navigate to the sidebar and select Databases -> Connect Database Secrets.

Alternatively, a Secret YAML manifest can be applied to the platform's host cluster.

Shared database secret template

apiVersion: v1
kind: Secret
metadata:
  name: <name> # this is a normal metadata name. A descriptive name is recommended. This will be used in a tenet vCluster's config to reference the connector secret
  namespace: <vcluster-platform-namespace> # this is the namespace that vCluster Platform is installed in. "vcluster-platform" and "loft" are common values.
  labels:
    loft.sh/connector-type: "shared-database"
stringData:
  endpoint: <endpoint> # this could be a service endoint or an external hostname endpoint
  password: <password>
  port: <port> # 3306 is a common port for database servers
  user: <user>

Use the following kubectl command to create the secret:

Create a shared database connector secret

kubectl create secret generic default-secret-name \
  --namespace=vcluster-platform \
  --from-literal=endpoint="your-database-endpoint" \
  --from-literal=password="your-database-password" \
  --from-literal=port="3306" \
  --from-literal=user="your-database-user" \
  -o yaml --dry-run=client > secret.yaml

Use virtual cluster with shared database

A new virtual cluster can now reference the created connector secret by setting the controlPlane.backingStore.database.external.connector field in the virtual cluster config to the name of the connector secret.

warning

Modifying a database secret to point to a different database server is not recommended and may lead to data loss.

Example configuration

The following example shows a connector secret for the shared database feature. It connects to an internal MySQL instance exposed by a service named mysql in the vcluster-platform namespace (where the platform is assumed to be installed). You can also use any other MySQL-compatible endpoint, such as an AWS RDS instance.

Shared database secret example

apiVersion: v1
kind: Secret
metadata:
  name: default-data-source
  namespace: vcluster-platform # This must match the namespace that vCluster Platform is in.
  labels:
    loft.sh/connector-type: "shared-database"
stringData:
  endpoint: mysql.vcluster-platform # This service can be in any namespace.
  password: <password>
  port: "3306"
  user: root
  type: mysql # This can be mysql or postgres. If left blank, the mysql database type is assumed.