Database Connector

info

This feature is available from 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.

note

This feature currently only supports MySQL database servers. It has been extensively tested for AWS RDS MySQL compatibility.

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 MySQL server 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

The template for a shared database connector secret is:

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 is a connector secret for the shared database feature. It is configured for an internal instance of MySQL that is exposed with a ClusterIP service named mysql in the vcluster-platform namespace (assume this is the namespace the platform is installed in). This could instead be any other endpoint, such as an AWS RDS MySQL endpoint.

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 could be in any namespace
  password: <password>
  port: "3306"
  user: root