MariaDB

Overview

MariaDB is a community-developed, MySQL-compatible relational database. This template deploys one MariaDB server on a persistent volume, reachable only from inside your GVC, with an optional phpMyAdmin web console and an optional scheduled dump to an S3 or GCS bucket. Every credential comes from a secret you create before installing. No password passes through Helm values, so none lands in the release or the stored workload spec, and the template creates no secret of its own.

This template deploys into an existing GVC that you already have. It does not create, provision, or manage a GVC.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-maria`	MariaDB server (stateful, 1 replica) on TCP `3306`	—
Volume set	`RELEASE_NAME-maria-vs`	`ext4` volume mounted at `/var/lib/mysql`, holding all data	—
Identity	`RELEASE_NAME-maria-identity`	Lets the database and backup workloads read your two secrets; carries the cloud account binding when backups are on	—
Policy	`RELEASE_NAME-maria-policy`	Grants the identity `reveal` on exactly the two credential secrets you created	—
Workload	`RELEASE_NAME-phpmyadmin`	phpMyAdmin console (serverless) on HTTP `80`; no identity, reads no secret	`phpMyAdmin.enabled: true`
Workload	`RELEASE_NAME-maria-backup`	Scheduled `mysqldump` to S3 or GCS (cron)	`backup.enabled: true`

Prerequisites

Two secrets must exist before you install. They are deliberately separate: an application that is handed the database credentials must not also receive the MariaDB root account. Secrets are org-level, so no --gvc flag is involved.

Create the application credentials secret

A dictionary secret holding exactly three keys: username, password and database. MariaDB creates this user and this database when the volume is first initialized, and this is the credential your applications put in their connection strings.

cpln secret create-dictionary --name CREDENTIALS_SECRET_NAME \
  --entry username=appuser \
  --entry password='YOUR-STRONG-PASSWORD' \
  --entry database=appdb

Set credentialsSecretName to this name.

Create the root password secret

An opaque secret with encoding plain, whose payload is the MariaDB root password.

printf '%s' "$(openssl rand -hex 32)" | cpln secret create-opaque --name ROOT_SECRET_NAME --encoding plain -f -

Set rootPasswordSecretName to this name.

A missing secret wedges the deployment silently. helm install still reports success, cpln logs returns nothing because the container never starts, and the only place the missing secret is named is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-maria --gvc GVC_NAME -o yaml

Create the secret and the workload recovers on its own after several minutes, or run cpln workload force-redeployment RELEASE_NAME-maria --gvc GVC_NAME to skip the wait.

Scheduled backups additionally need a bucket and a Control Plane cloud account — see Backing Up. Nothing else is required.

Installation

Create the two secrets above, then install the chart into your GVC, naming them:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/mariadb \
  --version 1.4.1 --gvc GVC_NAME \
  --set credentialsSecretName=CREDENTIALS_SECRET_NAME \
  --set rootPasswordSecretName=ROOT_SECRET_NAME

To install with another method, follow the instructions for your preferred tool:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Image

image: mariadb:11

Credentials

credentialsSecretName: my-mariadb-credentials   # dictionary secret: username, password, database — must EXIST BEFORE INSTALL
rootPasswordSecretName: my-mariadb-root-password # opaque secret (encoding: plain): the root password — must EXIST BEFORE INSTALL

Both values are secret names. The workload reads the contents through cpln://secret/... references, and the policy grants reveal on exactly these two secrets. An application given the dictionary secret has no path to root.

Resources

resources:
  minCpu: 100m
  minMemory: 128Mi
  maxCpu: 250m
  maxMemory: 264Mi

timeoutSeconds: 15

Storage

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)
  autoscaling:
    enabled: false # Set to true to enable autoscaling
    maxCapacity: 100 # Maximum capacity in GiB when autoscaling is enabled
    minFreePercentage: 10 # Minimum free percentage to trigger scaling when autoscaling is enabled
    scalingFactor: 1.2 # Scaling factor to determine how much to scale up when autoscaling is triggered

Internal Access

internalAccess: # Which workloads may reach MariaDB on port 3306
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # only used when type is workload-list
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

The database is never published to the internet by this template. Reach it from workloads inside the GVC, or from your machine with cpln port-forward (see Connecting).

phpMyAdmin

phpMyAdmin:
  enabled: false # true deploys a phpMyAdmin console alongside the database
  image: phpmyadmin:5.2.3-apache
  publicAccess:
    enabled: false # true publishes the console, and its login form, to the whole internet
  internalAccess:
    type: same-gvc # options: none, same-gvc, same-org, workload-list
    workloads: [] # only used when type is workload-list
      #- //gvc/GVC_NAME/workload/WORKLOAD_NAME
  resources:
    cpu: 100m
    memory: 128Mi

The console holds no credential of its own: it has no identity and no access to any secret. It presents a login form, and you sign in with either the application credentials or root plus the root password. phpMyAdmin.internalAccess governs who may reach the console; the database’s own internalAccess is a separate knob.

phpMyAdmin.publicAccess.enabled: true puts a database console on the public internet, where anyone who reaches it needs only a valid database password to read and write everything. Prefer leaving it off and reaching the console from inside the GVC.

Backup

backup:
  enabled: false
  image: ghcr.io/controlplane-com/backup-images/mysql-backup:1.0.0 # compatible with all MariaDB versions
  schedule: "0 2 * * *"   # daily at 2am UTC

  resources:
    cpu: 100m
    memory: 128Mi

  provider: aws # Options: aws or gcp

  aws:
    bucket: my-backup-bucket
    region: us-east-1
    cloudAccountName: my-backup-cloudaccount
    policyName: my-backup-policy
    prefix: mariadb/backups # folder name where your backups will be stored

  gcp:
    bucket: my-backup-bucket
    cloudAccountName: my-backup-cloudaccount
    prefix: mariadb/backups # folder name where your backups will be stored

The bucket, cloud account and IAM setup each provider needs is under Backing Up.

Connecting

What	Address	Notes
Database (from the GVC)	`RELEASE_NAME-maria.GVC_NAME.cpln.local:3306`	Subject to `internalAccess.type`.
Database (from your machine)	`127.0.0.1:3306` via `cpln port-forward`	Works regardless of `internalAccess.type`; see below.
phpMyAdmin (internal)	`http://RELEASE_NAME-phpmyadmin.GVC_NAME.cpln.local`	Only when `phpMyAdmin.enabled: true`.
phpMyAdmin (public)	`https://CANONICAL_ENDPOINT`	Only when `phpMyAdmin.publicAccess.enabled: true`. Read it from `status.canonicalEndpoint` in `cpln workload get RELEASE_NAME-phpmyadmin --gvc GVC_NAME -o yaml`.
Application credentials	`cpln secret reveal CREDENTIALS_SECRET_NAME -o yaml`	The `username`, `password` and `database` keys.
Root password	`cpln secret reveal ROOT_SECRET_NAME -o yaml`	The `payload`.

Confirm the server is up and accepting the root password it was initialized with:

cpln workload exec RELEASE_NAME-maria --gvc GVC_NAME -- sh -c 'mariadb-admin ping -u root -p"$MYSQL_ROOT_PASSWORD"'

To use a client on your own machine, open a tunnel and connect to 127.0.0.1:

cpln port-forward RELEASE_NAME-maria 3306:3306 --gvc GVC_NAME

mariadb --host=127.0.0.1 --port=3306 --user=appuser -p appdb

Operations

Backing Up

When backup.enabled: true, a cron workload runs mysqldump --databases against the database named in your credentials secret on backup.schedule, authenticating as root, and uploads the gzipped result to BUCKET/PREFIX/mysql-<timestamp>.sql.gz. Both credentials come from the same two secrets the database uses; the bucket, region and prefix are plain configuration. Complete the steps for your provider before enabling it.

AWS S3
GCS

Create an S3 bucket. Set backup.aws.bucket to its name and backup.aws.region to its region.
Create a Control Plane cloud account for the AWS account that holds the bucket. Set backup.aws.cloudAccountName to its name.
Create an IAM policy with the JSON below, replacing YOUR_BUCKET_NAME, and set backup.aws.policyName to its name. The template attaches it to the workload’s identity.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:GetObjectVersion",
                "s3:DeleteObjectVersion",
                "s3:GetBucketLocation",
                "s3:AbortMultipartUpload",
                "s3:ListBucketMultipartUploads",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}

Set backup.provider: aws and backup.enabled: true.

Create a GCS bucket. Set backup.gcp.bucket to its name.
Create a Control Plane cloud account for the GCP project that holds the bucket, granting its service account the Storage Admin role. Set backup.gcp.cloudAccountName to its name. The template binds roles/storage.objectAdmin on exactly that bucket.
Set backup.provider: gcp and backup.enabled: true.

Restoring a Backup

The dump was taken with mysqldump --databases, so it recreates the database itself (CREATE DATABASE IF NOT EXISTS plus USE) and is loaded as root without naming a database. Download it, tunnel to the server, and feed it to a local mariadb (or mysql) client. The root password is the payload of your rootPasswordSecretName secret.

This procedure follows the dump format the backup image produces and the client the official MariaDB image documents; it has not been exercised against a live install of this template. Test it on a scratch release before relying on it.

# AWS S3 (for GCS: gsutil cp gs://BUCKET_NAME/PREFIX/mysql-TIMESTAMP.sql.gz .)
aws s3 cp s3://BUCKET_NAME/PREFIX/mysql-TIMESTAMP.sql.gz .

cpln port-forward RELEASE_NAME-maria 3306:3306 --gvc GVC_NAME

gunzip -c mysql-TIMESTAMP.sql.gz | mariadb --host=127.0.0.1 --port=3306 --user=root -p

The dump replaces the tables it contains and leaves any other database on the server untouched.

Upgrading from Earlier Versions

From 1.4.0. Version 1.4.1 removes the AWS managed policy aws::ReadOnlyAccess from the backup identity. It granted read access to every bucket in your AWS account and contained no write actions, so it never carried the backup itself — but it was silently supplying any read action your own bucket-scoped policy omitted. Before upgrading an install that uses backup.provider: aws, make sure your IAM policy carries the full action list under Backing Up. If it already does, nothing changes. Installs without AWS backups are unaffected. From 1.3.2 or earlier. Version 1.4.0 moved every credential out of Helm values and closed the phpMyAdmin console by default. Earlier versions shipped working default passwords in values.yaml, behind a console that was always enabled and always public.

	1.3.2 and earlier	1.4.0 and later
Database credentials	`config.user`, `config.password`, `config.db` values	`credentialsSecretName` — a dictionary secret you create
Root password	`config.rootPassword` value	`rootPasswordSecretName` — an opaque secret you create
Chart-created credentials secret	Held every credential	Not created
phpMyAdmin	`enablePhpMyAdmin: true`, always public	`phpMyAdmin.enabled: false`, with its own `publicAccess` and `internalAccess`
phpMyAdmin image	`phpmyadmin/phpmyadmin:latest`	`phpmyadmin:5.2.3-apache`, pinned

An upgrade that still carries config or enablePhpMyAdmin is rejected at render, before anything is applied, and your running release is left untouched — see Troubleshooting for the exact messages. To upgrade:

Create the two secrets with the credentials the database already uses

Credentials are read only when the volume is first initialized, so an upgrade does not rewrite them. Put the username, password, database name and root password your database was created with into the two secrets described in Prerequisites. Different values here do not change the database; they only leave the workload unable to authenticate.

Remove the old keys from your values

Delete the entire config block and enablePhpMyAdmin. Set credentialsSecretName and rootPasswordSecretName to the two secret names, and set phpMyAdmin.enabled: true if you still want the console.

Upgrade, then rotate any default password

The upgrade restarts the single replica; data on the volume set is untouched. If your database still uses a 1.3.x default password, treat it as compromised and rotate it as described in Troubleshooting.

Scaling and Availability

This is a single MariaDB server on one volume. Keep the replica count at one: additional replicas would not form a cluster, and the chart pins minScale and maxScale to 1. Resize with resources.* and volumeset.* instead. The data directory lives on the volume set, so a restart or redeploy reattaches the same data; cpln helm uninstall deletes the volume set and the database with it.

Troubleshooting

The database never becomes ready and cpln logs returns nothing

Symptom: helm install succeeded, cpln logs returns no lines, and cpln workload get-deployments RELEASE_NAME-maria --gvc GVC_NAME -o yaml shows a message under status.versions[].message such as:

The secret CREDENTIALS_SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

Cause: One of the two prerequisite secrets does not exist under the name set in credentialsSecretName or rootPasswordSecretName. The container never starts, so there is no log output.Fix: Create the named secret as shown in Prerequisites. The workload recovers on its own after several minutes, or run cpln workload force-redeployment RELEASE_NAME-maria --gvc GVC_NAME.

helm upgrade fails with 'the config block was removed in 1.4.0'

Symptom: The upgrade stops at render with:

mariadb: the `config` block was removed in 1.4.0 — database credentials are no longer values. Create a `dictionary` secret with `username`, `password` and `database`, an `opaque` secret with the root password, and set `credentialsSecretName` and `rootPasswordSecretName` to their names. See Prerequisites in the README.

Cause: Your values still contain the config block from 1.3.2 or earlier. The chart refuses it rather than silently ignoring a password you believe you set.Fix: Follow Upgrading from Earlier Versions. The running release is unaffected until the upgrade succeeds.

helm upgrade fails with 'enablePhpMyAdmin was renamed in 1.4.0'

Symptom:

mariadb: `enablePhpMyAdmin` was renamed in 1.4.0 — use `phpMyAdmin.enabled` instead. Note phpMyAdmin now defaults to OFF, and to internal-only access when enabled (`phpMyAdmin.publicAccess.enabled`).

Cause: Your values still set enablePhpMyAdmin.Fix: Replace it with phpMyAdmin.enabled: true, and add phpMyAdmin.publicAccess.enabled: true only if you genuinely want the console on the internet.

Access denied after changing a password in the secret

Symptom: You updated the dictionary or root secret, redeployed, and clients (or the readiness probe) now fail with:

ERROR 1045 (28000): Access denied for user 'root'@'...' (using password: YES)

Cause: MariaDB reads MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE and MYSQL_ROOT_PASSWORD only while initializing an empty data directory. Changing the secret afterwards does not change the stored passwords, but the readiness probe authenticates as root with the value from the secret, so a mismatch makes the workload unhealthy.Fix: Change the password inside MariaDB first, for every host the account exists under (SELECT User, Host FROM mysql.user;):

ALTER USER 'root'@'localhost' IDENTIFIED BY 'NEW-STRONG-ROOT-PASSWORD';
ALTER USER 'root'@'%' IDENTIFIED BY 'NEW-STRONG-ROOT-PASSWORD';

Then update the secret to the same value and run cpln workload force-redeployment RELEASE_NAME-maria --gvc GVC_NAME so the new value is read — a running replica keeps the value it started with until it is redeployed. Rotate the application user the same way with its own ALTER USER.

An internalAccess or publicAccess change does not seem to apply

Symptom: A client that should now be allowed is still refused (or one that should be blocked still connects) immediately after helm upgrade.Cause: Firewall changes take a few minutes to propagate. Also check you changed the right block: internalAccess governs the database on 3306, while phpMyAdmin.internalAccess and phpMyAdmin.publicAccess govern only the console.Fix: Wait a few minutes and retry before concluding the knob is broken. Changing a console knob re-applies only the console workload; the database is not restarted.

The backup job fails with AccessDenied on S3 after upgrading to 1.4.1

Symptom: Backups that worked on 1.4.0 now log an S3 AccessDenied error in cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-maria-backup"}' --limit 50 --since 10m.Cause: 1.4.1 dropped the account-wide aws::ReadOnlyAccess managed policy from the backup identity, and your bucket-scoped IAM policy is missing an action it used to supply.Fix: Update your IAM policy to the full action list under Backing Up.

Important Notes

Create both secrets before installing. The deployment wedges silently without them; status.versions[].message is the only place the missing secret is named.
Credentials are applied only when the volume is first initialized. Rotate a password with ALTER USER inside MariaDB, then update the secret and force a redeployment — in that order.
Do not scale past one replica. This is a single-instance server; see Scaling and Availability.
phpMyAdmin.publicAccess.enabled: true puts a database console on the internet. Leave it off unless you have a reason, and never without strong passwords.
Access changes take a few minutes to propagate. Retry before concluding an internalAccess or publicAccess change failed.
cpln helm uninstall deletes the volume set and the database with it. Your two secrets are not touched; they are yours, not the chart’s.
Upgrading from 1.3.2 or earlier is a breaking change. Create the secrets and drop config and enablePhpMyAdmin first; see Upgrading from Earlier Versions.

External References

MariaDB Knowledge Base

Official MariaDB server and client documentation

MariaDB Docker Image

Environment variables and initialization behaviour of the official image

phpMyAdmin Documentation

phpMyAdmin user documentation

Backup Image Source

Source for the backup container image this template runs

MariaDB Template

Chart source, default values, and version history

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image

Credentials

Resources

Storage

Internal Access

phpMyAdmin

Backup

Connecting

Operations

Backing Up

Restoring a Backup

Upgrading from Earlier Versions

Scaling and Availability

Troubleshooting

Important Notes

External References

MariaDB Knowledge Base

MariaDB Docker Image

phpMyAdmin Documentation

Backup Image Source

MariaDB Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image

​Credentials

​Resources

​Storage

​Internal Access

​phpMyAdmin

​Backup

​Connecting

​Operations

​Backing Up

​Restoring a Backup

​Upgrading from Earlier Versions

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

MariaDB Knowledge Base

MariaDB Docker Image

phpMyAdmin Documentation

Backup Image Source

MariaDB Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image

Credentials

Resources

Storage

Internal Access

phpMyAdmin

Backup

Connecting

Operations

Backing Up

Restoring a Backup

Upgrading from Earlier Versions

Scaling and Availability

Troubleshooting

Important Notes

External References