Files
cozystack/packages/apps/mariadb
scooby87 71ca2b1bae fix(mariadb): re-guard replication so single-replica passes the operator webhook (#3180)
## What this PR does

Fixes a regression where **single-replica MariaDB can no longer be
created**.

[PR #2279](https://github.com/cozystack/cozystack/pull/2279) made
`replication.enabled: true` unconditional in the MariaDB CR so the
operator would always create `<release>-primary` / `<release>-secondary`
Services (expected by the dashboard RBAC and the ApplicationDefinition).
But the vendored mariadb-operator's validating webhook
(`vmariadb-v1alpha1.kb.io`) **rejects `replication.enabled: true` when
`spec.replicas == 1`** — replication needs a primary + at least one
replica. As a result, single-replica installs never became Ready (the
HelmRelease failed at admission).

The webhook rule lives in the operator's Go code (not in the vendored
CRD — there is no CEL rule tying replication to replica count), so the
failing path is reproduced by an e2e test rather than a schema
assertion.

### Fix — re-guard replication, teach consumers about the bare service

The operator provisions a bare `<release>` Service in **both**
topologies; `-primary`/`-secondary` exist **only** when replication is
on (`replicas>1`). Instead of forcing replication for everyone, this PR
lets replication track the replica count and makes the service-name
consumers handle the single-replica bare service:

- **`mariadb.yaml`** — gate `replication` on `replicas>1`; restore
single-replica external access via `service.type: LoadBalancer`, and
keep `primaryService: LoadBalancer` for `replicas>1` only. (Effectively
reverts #2279's two hunks.)
- **`backup-cronjob.yaml`** — single-replica dumps target the bare
service (no `-secondary` exists without replication); `replicas>1` still
offloads to `-secondary`.
- **`dashboard-resourcemap.yaml`** — always grant RBAC on the bare
service, plus `-primary`/`-secondary` when `replicas>1`, matching what
the ApplicationDefinition lists.
- **`mariadb-rd`** — list the bare service in `services.include` so
single-replica installs are visible in the dashboard.
- **`hack/e2e-apps/mariadb.bats`** — new `Create single-replica MariaDB`
test that reproduces the webhook rejection and guards against
regression.

Verified: `helm template` at `replicas=1`/`2` renders the intended
CR/RBAC/backup host; `helm unittest` passes; `update-crd.sh` keeps the
RD stable; `select-e2e.sh` maps the change to the mariadb suite.

### Release note

```release-note
fix(mariadb): single-replica instances can be created again — replication is now enabled only for replicas>1 (matching the operator webhook), while the dashboard, RBAC, and backups correctly target the bare service for single-replica setups
```


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added an end-to-end test covering MariaDB deployments with a single
replica, including validation of the main service, endpoints,
StatefulSet replica count, and metrics components.

* **Bug Fixes**
* Updated MariaDB chart behavior to correctly handle single-replica vs
multi-replica configurations for external access, replication settings,
and backup host selection.
* Refined dashboard RBAC and secret inclusion so access applies to the
main MariaDB service in addition to replica-specific services.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-07-02 22:54:14 +03:00
..

Managed MariaDB Service

The Managed MariaDB Service offers a powerful and widely used relational database solution. This service allows you to create and manage a replicated MariaDB cluster seamlessly.

Deployment Details

This managed service is controlled by mariadb-operator, ensuring efficient management and seamless operation.

storageClass is annotated as immutable in the chart schema — see docs/storage-immutability.md for the contract and which consumers enforce it.

HowTos

How to switch master/slave replica

kubectl edit mariadb <instance>

update:

spec:
  replication:
    primary:
      podIndex: 1

check status:

NAME        READY   STATUS    PRIMARY POD   AGE
<instance>  True    Running   app-db1-1     41d

How to back up and restore a MariaDB application

The recommended path is the Cozystack BackupClass / Plan / RestoreJob flow with the operator-native strategy.backups.cozystack.io/MariaDB strategy. See examples/backups/mariadb for a numbered, end-to-end walkthrough (bucket, source, strategy, BackupClass, Plan, ad-hoc BackupJob, and both in-place + to-copy RestoreJob fixtures).

The chart's backup.* block (mariadb-dump + restic CronJob) is deprecated and remains supported for backward compatibility only. Existing tenants can keep using it unchanged; new deployments should use the operator-native flow above.

How to restore from a deprecated restic-based backup

find snapshot:

restic -r s3:s3.example.org/mariadb-backups/database_name snapshots

restore:

restic -r s3:s3.example.org/mariadb-backups/database_name restore latest --target /tmp/

more details:

Known issues

  • Replication can't be finished with various errors

  • Replication can't be finished in case if binlog purged

    Until mariadbbackup is not used to bootstrap a node by mariadb-operator (this feature is not implemented yet), follow these manual steps to fix it: https://github.com/mariadb-operator/mariadb-operator/issues/141#issuecomment-1804760231

  • Corrupted indices Sometimes some indices can be corrupted on master replica, you can recover them from slave:

    mysqldump -h <slave> -P 3306 -u<user> -p<password> --column-statistics=0 <database> <table> ~/tmp/fix-table.sql
    mysql -h <master> -P 3306 -u<user> -p<password> <database> < ~/tmp/fix-table.sql
    

Parameters

Common parameters

Name Description Type Value
replicas Number of MariaDB replicas. int 2
resources Explicit CPU and memory configuration for each MariaDB replica. When omitted, the preset defined in resourcesPreset is applied. object {}
resources.cpu CPU available to each replica. quantity ""
resources.memory Memory (RAM) available to each replica. quantity ""
resourcesPreset Default sizing preset used when resources is omitted. string t1.nano
size Persistent Volume Claim size available for application data. quantity 10Gi
storageClass StorageClass used to store the data. string ""
external Enable external access from outside the cluster. bool false
version MariaDB major.minor version to deploy string v11.8

Application-specific parameters

Name Description Type Value
users Users configuration map. map[string]object {}
users[name].password Password for the user. string ""
users[name].maxUserConnections Maximum number of connections. int 0
databases Databases configuration map. map[string]object {}
databases[name].roles Roles assigned to users. object {}
databases[name].roles.admin List of users with admin privileges. []string []
databases[name].roles.readonly List of users with read-only privileges. []string []

Backup parameters (DEPRECATED)

Name Description Type Value
backup DEPRECATED: Backup configuration. Prefer the BackupClass / Plan flow under examples/backups/mariadb/. object {}
backup.enabled DEPRECATED: Enable regular backups (default: false). bool false
backup.s3Region DEPRECATED: AWS S3 region where backups are stored. string us-east-1
backup.s3Bucket DEPRECATED: S3 bucket used for storing backups. string s3.example.org/mariadb-backups
backup.schedule DEPRECATED: Cron schedule for automated backups. string 0 2 * * *
backup.cleanupStrategy DEPRECATED: Retention strategy for cleaning up old backups. string --keep-last=3 --keep-daily=3 --keep-within-weekly=1m
backup.s3AccessKey DEPRECATED: Access key for S3 authentication. string <your-access-key>
backup.s3SecretKey DEPRECATED: Secret key for S3 authentication. string <your-secret-key>
backup.resticPassword DEPRECATED: Password for Restic backup encryption. string <password>

Parameter examples and reference

resources and resourcesPreset

resources sets explicit CPU and memory configurations for each replica. When left empty, the preset defined in resourcesPreset is applied.

resources:
  cpu: 4000m
  memory: 4Gi

resourcesPreset sets named CPU and memory configurations for each replica. This setting is ignored if the corresponding resources value is set.

Presets follow a cloud-style <series>.<size> naming convention. Five series cover the full CPU-to-memory ratio range (t1 1:0.5, c1 1:1, s1 1:2, u1 1:4, m1 1:8) and each series ships eight sizes (nano through 4xlarge). The legacy flat names (nano, micro, small, medium, large, xlarge, 2xlarge) remain accepted as deprecated aliases of their 1:1 instance-type equivalents.

See docs/operations/resource-presets.md for the full size matrix and the legacy-to-instance-type mapping.

users

users:
  user1:
    maxUserConnections: 1000
    password: hackme
  user2:
    maxUserConnections: 1000
    password: hackme

databases

databases:
  myapp1:
    roles:
      admin:
      - user1
      readonly:
      - user2