MySQL

Overview

MySQL is the most widely used open-source relational database. This template deploys a single MySQL instance on a persistent volume, with an optional phpMyAdmin web console and an optional scheduled mysqldump to an S3 or GCS bucket. Database credentials are not template values. MySQL reads the application credentials and the root password from two secrets you create before installing, so no password passes through Helm or lands in the release.

This template deploys into an existing GVC that you already have. It does not create one.

What Gets Created

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

The template creates no secret of its own. Every credential lives in the prerequisite secrets described below.

Prerequisites

Two secrets must exist before you install. They are deliberately separate: an application or teammate given reveal on the database credentials must not also receive root. 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. MySQL creates this user and this database on first boot, 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 holding the MySQL root password.

printf '%s' 'YOUR-STRONG-ROOT-PASSWORD' | cpln secret create-opaque --name ROOT_SECRET_NAME --encoding plain -f -

Set rootPasswordSecretName to this name.

Create both secrets before installing. The template refuses to render when either name is blank, but a name that points at a secret which does not exist installs successfully and then wedges: the container never starts, cpln logs returns nothing, and the only place the missing secret is named is status.versions[].message:

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

Creating the missing secret repairs the deployment on its own after a few minutes, or run cpln workload force-redeployment RELEASE_NAME-mysql --gvc GVC_NAME to skip the wait.

Backups additionally need a bucket and a Control Plane Cloud Account — see Backing Up. Nothing else is required.

Installation

Install from the marketplace registry, passing the two secret names you created:

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

Or follow the instructions for your preferred method:

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: mysql:9 # any supported MySQL major works, including the backup feature (the backup image dumps whichever database is configured)

Credentials

# `dictionary` secret holding exactly three keys: `username`, `password`, `database`.
# This is the credential you put in your applications' connection strings.
credentialsSecretName: my-mysql-credentials

# `opaque` secret (encoding: plain) holding the MySQL root password. Deliberately
# separate, so sharing the application credentials above does not hand out root.
rootPasswordSecretName: my-mysql-root-password

Both secrets must exist before installing — see Prerequisites. The workload reads them through cpln://secret/... references, so the values appear in neither the Helm release nor the stored workload spec.

MySQL applies these credentials only on first startup, when the data directory is empty. Rotating either secret afterwards does not change the stored passwords — change them inside MySQL with ALTER USER, then update the secret to match (see Troubleshooting).

Resources

resources:
  minCpu: 100m
  maxCpu: 400m
  minMemory: 128Mi
  maxMemory: 512Mi

timeoutSeconds: 15

Internal Access

internalAccess: # Which workloads may reach MySQL 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

Type	Who can connect on port `3306`
`none`	No workload
`same-gvc`	Every workload in the same GVC
`same-org`	Every workload in the same org
`workload-list`	Only the workloads listed in `workloads`

The database is never published to the internet by this template. Reach it from inside the GVC, through cpln port-forward, or from outside through your own proxy.

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

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 standing credential: it has no identity, no reveal grant, and no password in its environment. It presents a login form, you supply either the application credentials or root plus the root password, and it connects to the database as whoever logged in. phpMyAdmin.internalAccess governs the console only — the database has its own internalAccess 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 or through cpln port-forward.

Backup

backup:
  enabled: false
  image: ghcr.io/controlplane-com/backup-images/mysql-backup:1.0.0 # compatible with all MySQL image 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: mysql/backups # folder name where your backups will be stored

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

Set backup.provider to aws or gcp and fill in the matching section. The bucket, Cloud Account and permissions setup is under Backing Up.

Connecting

What	Address	Notes
Database (internal)	`RELEASE_NAME-mysql.GVC_NAME.cpln.local:3306`	Subject to `internalAccess.type`. Never public.
phpMyAdmin (internal)	`http://RELEASE_NAME-mysql-phpmyadmin.GVC_NAME.cpln.local`	Only when `phpMyAdmin.enabled: true`.
phpMyAdmin (public)	`status.canonicalEndpoint` in `cpln workload get RELEASE_NAME-mysql-phpmyadmin --gvc GVC_NAME -o yaml`	Only when `phpMyAdmin.publicAccess.enabled: true`.
Application credentials	`cpln secret reveal CREDENTIALS_SECRET_NAME -o yaml`	`username`, `password`, `database` — what your applications use.
Root password	`cpln secret reveal ROOT_SECRET_NAME -o yaml`	Keep this one to administrators.

To reach the database from your own machine, forward the port through Control Plane, then connect with a local mysql client using the application credentials:

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

mysql --host=127.0.0.1 --port=3306 --user=appuser --password appdb

To verify the server from inside its own container — no password needed, the container already holds it as MYSQL_ROOT_PASSWORD:

cpln workload exec RELEASE_NAME-mysql --gvc GVC_NAME -- sh -c 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mysql --user=root --execute="SELECT VERSION()"'

Operations

Backing Up

With backup.enabled: true, the RELEASE_NAME-mysql-backup cron workload connects as root and runs mysqldump --databases DATABASE --single-transaction --set-gtid-purged=OFF against the database named in your credentials secret, gzips the result and uploads it as mysql-<UTC timestamp>.sql.gz under prefix in your bucket. Nothing is kept locally and nothing is ever deleted from the bucket — retention is whatever your bucket’s lifecycle rules say. The bucket and the Cloud Account must exist before you enable it.

AWS S3

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 holding 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/*"
            ]
        }
    ]
}

GCS

Create a GCS bucket. Set backup.gcp.bucket to its name.
Create a Control Plane Cloud Account for the GCP project holding 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.

One-off dump

For an ad-hoc dump without the backup job, run mysqldump inside the database container and stream it out. The container already holds the root password and the database name as environment variables, and the stream is base64-encoded on both sides because cpln workload exec does not pass binary data through intact:

cpln workload exec RELEASE_NAME-mysql --gvc GVC_NAME --container mysql --quiet -- sh -c 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mysqldump --user=root --databases "$MYSQL_DATABASE" --single-transaction --set-gtid-purged=OFF | gzip | base64' | base64 -d > mysql-backup.sql.gz

The file has the same format as the scheduled backups, so the restore below applies to both.

Restoring a Backup

The database is not reachable from the internet, so the dump is loaded from inside the database container. The mysql:9 image ships mysql, gunzip and base64, and the container holds the root password as MYSQL_ROOT_PASSWORD, so you never type it.

Download the dump

From a machine with access to the bucket:

aws s3 cp "s3://BUCKET_NAME/PREFIX/mysql-TIMESTAMP.sql.gz" ./mysql-backup.sql.gz

gsutil cp "gs://BUCKET_NAME/PREFIX/mysql-TIMESTAMP.sql.gz" ./mysql-backup.sql.gz

Stream it into the running server

base64 < mysql-backup.sql.gz | cpln workload exec RELEASE_NAME-mysql --gvc GVC_NAME --container mysql --stdin -- sh -c 'base64 -d | gunzip | MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mysql --user=root'

--stdin is required — without it the piped file is silently discarded and nothing is restored. No database name is passed because the dump was taken with --databases, so it carries its own CREATE DATABASE IF NOT EXISTS and USE statements. Each table in the dump is dropped and recreated; tables that exist on the server but not in the dump are left alone.

Verify

cpln workload exec RELEASE_NAME-mysql --gvc GVC_NAME -- sh -c 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mysql --user=root --execute="SELECT TABLE_NAME, TABLE_ROWS FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE()" "$MYSQL_DATABASE"'

This procedure is verified against the chart’s configuration, the dump options the backup image uses and the tools present in the mysql:9 image. It has not been exercised against a live install of this template version.

Upgrading from 1.5.0

Version 1.5.1 removes the aws::ReadOnlyAccess managed policy from the backup identity. That policy granted read access to every bucket in your AWS account and contains no write actions, so it never carried the backup itself — but it was silently supplying any read action your own bucket-scoped policy happened to omit. Update your IAM policy to the full ten-action list under Backing Up before upgrading. If it already matches, no action is needed. The identity now carries cpln-connector and your bucket-scoped policy only. Nothing else changes.

Upgrading from 1.4.3 or Earlier

Template versions up to 1.4.3 took the database credentials as plain Helm values with working defaults, and deployed phpMyAdmin enabled and reachable from the entire internet. Version 1.5.0 removed both.

	1.4.3 and earlier	1.5.0 and later
Application 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
phpMyAdmin	`enablePhpMyAdmin: true`, public, hardcoded to `0.0.0.0/0`	`phpMyAdmin.enabled: false`, with its own `publicAccess` (off) and `internalAccess` knobs
phpMyAdmin image	`phpmyadmin/phpmyadmin:latest`	`phpmyadmin:5.2.3-apache`
phpMyAdmin credentials	An identity plus the root password in its environment	None — no identity, no secret access
Credential secret	`RELEASE_NAME-mysql-config` held every credential	Not created — credentials live only in your secrets

Carrying old values forward stops the upgrade. Both removed keys are rejected at render, so cpln helm upgrade fails and your existing release is left untouched and running rather than quietly restarting with a different password. See Troubleshooting for the exact error text.

Read the credentials the database already uses

Credentials are written into the data directory the first time the volume is initialized, so an existing database keeps whatever it was created with. Recover them from your current values file, or from the secret the old version created:

cpln secret reveal RELEASE_NAME-mysql-config -o yaml

The keys are user, password, database and rootPassword.

Create the two prerequisite secrets with those same values

Follow Prerequisites, using the existing username, password, database name and root password. Different values here do not change the database — they just leave the workload unable to authenticate.

Remove the old keys from your values

Delete the entire config block and enablePhpMyAdmin, then set credentialsSecretName and rootPasswordSecretName to the two secret names. If you were using the console, add phpMyAdmin.enabled: true — it is off by default now, and internal-only unless you also set phpMyAdmin.publicAccess.enabled: true.

Upgrade, then rotate the passwords

Any password that came from a 1.4.x default was published in the public template repository — treat it as compromised. Rotate inside MySQL, then update the two secrets to match so the workload can still authenticate after a restart:

cpln workload exec RELEASE_NAME-mysql --gvc GVC_NAME -- sh -c 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mysql --user=root'

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

The image creates root for both localhost and %, so rotating root means changing both. Use your own username in place of appuser.

Scaling and Availability

This is a single instance on a single volume. The chart pins the workload to exactly one replica (minScale and maxScale of 1), and there is no replication or clustering mode — do not raise the replica count. Scale vertically with resources, and let the volume grow with volumeset.autoscaling. Data lives on the volume set and survives restarts, redeploys and cpln helm upgrade. cpln helm uninstall deletes the volume set and the database with it; take a backup first.

Troubleshooting

The workload never becomes ready and cpln logs returns nothing

Symptom: cpln helm install succeeded, RELEASE_NAME-mysql never reaches ready, and cpln logs returns zero lines. cpln workload get RELEASE_NAME-mysql --gvc GVC_NAME shows a tag of the form cpln/secret:SECRET_NAME: secret-does-not-exist.Cause: one of the two prerequisite secrets does not exist, so the container cannot start. The missing secret is named in status.versions[].message:

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

Fix: create the secret exactly as in Prerequisites. The deployment recovers on its own after a few minutes, or force it:

cpln workload force-redeployment RELEASE_NAME-mysql --gvc GVC_NAME

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

Symptom: cpln helm upgrade stops before touching any resource with one of:

Error: execution error at (mysql/templates/workload-mysql.yaml:1:4): mysql: the `config` block was
removed in 1.5.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.

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

Cause: your values file still carries keys removed in 1.5.0. The failure is deliberate — it keeps the running release intact instead of restarting it with a different password.Fix: follow Upgrading from 1.4.3 or Earlier.

Access denied after changing a secret

Symptom: after updating CREDENTIALS_SECRET_NAME or ROOT_SECRET_NAME (and redeploying), connections fail with:

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

Cause: MySQL reads the secrets only when the data directory is first initialized. The stored passwords are still the original ones, and the secret no longer matches them. If the root secret changed, the readiness probe (which authenticates as root) fails too and the workload stops reporting ready.Fix: put the old value back in the secret, then rotate inside MySQL and update the secret afterwards:

cpln workload exec RELEASE_NAME-mysql --gvc GVC_NAME -- sh -c 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mysql --user=root'

ALTER USER 'appuser'@'%' IDENTIFIED BY 'NEW-STRONG-PASSWORD';

For root, change both 'root'@'localhost' and 'root'@'%'. To start over with a fresh database instead, cpln helm uninstall (which deletes the volume set and all data) and reinstall.

The backup job runs but nothing appears in the bucket

Symptom: RELEASE_NAME-mysql-backup runs on schedule and its logs end with an upload error such as:

An error occurred (AccessDenied) when calling the PutObject operation: Access Denied

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-mysql-backup"}' --limit 50 --since 24h

Cause: the identity cannot write to the bucket — the IAM policy named in backup.aws.policyName is missing actions (common after upgrading from 1.5.0), or the Cloud Account does not cover the account or project holding the bucket.Fix: make the IAM policy match the ten-action list under Backing Up and confirm backup.aws.bucket / backup.gcp.bucket and the Cloud Account name are correct. The next scheduled run picks up the change.

Important Notes

Create both prerequisite secrets before installing. A reference to a secret that does not exist wedges the workload instead of failing the install.
Credentials are applied only when the volume is first initialized. Rotating a secret afterwards does not change the stored passwords — use ALTER USER inside MySQL and update the secret to match.
Do not scale past one replica. This is a single instance on a single volume, not a replicated cluster.
cpln helm uninstall deletes the volume set and the database with it. Take a backup first.
Access changes take a few minutes to apply after an internalAccess or publicAccess change — a connection attempt made immediately afterwards is not evidence the knob is broken.
Upgrading from 1.4.3 or earlier is a breaking change — the removed keys stop the upgrade rather than resetting a password. See Upgrading from 1.4.3 or Earlier.

External References

MySQL Documentation

Official MySQL reference manual

MySQL Docker Image

Official image reference, including the first-boot environment variables

phpMyAdmin Documentation

phpMyAdmin user documentation

Backup Image Source

Source code for the MySQL backup container image

MySQL Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image

Credentials

Resources

Internal Access

Storage

phpMyAdmin

Backup

Connecting

Operations

Backing Up

AWS S3

GCS

One-off dump

Restoring a Backup

Upgrading from 1.5.0

Upgrading from 1.4.3 or Earlier

Scaling and Availability

Troubleshooting

Important Notes

External References

MySQL Documentation

MySQL Docker Image

phpMyAdmin Documentation

Backup Image Source

MySQL Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image

​Credentials

​Resources

​Internal Access

​Storage

​phpMyAdmin

​Backup

​Connecting

​Operations

​Backing Up

​AWS S3

​GCS

​One-off dump

​Restoring a Backup

​Upgrading from 1.5.0

​Upgrading from 1.4.3 or Earlier

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

MySQL Documentation

MySQL Docker Image

phpMyAdmin Documentation

Backup Image Source

MySQL Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image

Credentials

Resources

Internal Access

Storage

phpMyAdmin

Backup

Connecting

Operations

Backing Up

AWS S3

GCS

One-off dump

Restoring a Backup

Upgrading from 1.5.0

Upgrading from 1.4.3 or Earlier

Scaling and Availability

Troubleshooting

Important Notes

External References