Database Connector

info

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

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	✅
	Azure Database for PostgreSQL flexible servers	✅	13
	AWS Aurora	✅
	AWS RDS	✅

info

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

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.