How to install MariaDB via Kuber­netes

MariaDB can run in a scalable and reliable way on Kuber­netes. In this guide, you’ll create a State­ful­Set, add per­sist­ent storage and configure access to the database service. This ensures MariaDB is per­man­ently in­teg­rated into your Kuber­netes cluster in a stable, con­trolled way.

Why should you use MariaDB with Kuber­netes?

Kuber­netes makes it easy to start, scale and monitor MariaDB. It dis­trib­utes workloads in­tel­li­gently and auto­mat­ic­ally restarts the database if something goes wrong. Whether you run in the cloud or on premises, Kuber­netes helps you use resources ef­fi­ciently and manage your in­fra­struc­ture more easily.

What do you need before in­stalling MariaDB on Kuber­netes?

Before you begin make sure you have:

• A running Kuber­netes cluster (e.g. Minikube, AKS, EKS or VKE)
• kubectl is set up on your local machine
• Terminal access with admin rights in the cluster
• Optional: a Stor­age­Class or locally con­figured HostPath for storing data

How to install MariaDB via Kuber­netes

Below you’ll learn how to deploy MariaDB in the cluster and store data so it’s not lost after restarts. For more details on Kuber­netes basics, see our Kuber­netes tutorial.

Step 1: Set up Per­sist­ent­Volume (PV) and PVC

MariaDB in Kuber­netes needs per­sist­ent storage so your data isn’t lost if the pod restarts or is re­deployed. We’ll configure a Per­sist­ent­Volume (PV) and a Per­sist­ent­Volume­Claim (PVC). The PV defines where the data is stored phys­ic­ally in the cluster – in this example /mnt/data/mariadb. Save the following YAML to a file named mariadb-pv.yaml:

apiVersion: v1
kind: PersistentVolume
metadata:
    name: mariadb-pv
spec:
    capacity:
        storage: 10Gi
    accessModes:
        - ReadWriteOnce
    persistentVolumeReclaimPolicy: Retain
    hostPath:
        path: /mnt/data/mariadb

The Retain policy makes sure the data remains even if the PVC is deleted. Create the Per­sist­ent­Volume by running:

kubectl apply -f mariadb-pv.yaml

You should receive con­firm­a­tion that the Per­sist­ent­Volume was created. Next the PVC reserves space from the PV for the MariaDB pod. Save the following to a file named mariadb-pvc.yaml:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
    name: mariadb-pvc
spec:
    accessModes:
        - ReadWriteOnce
    resources:
        requests:
            storage: 10Gi

Create the Per­sist­ent­Volume­Claim by running:

kubectl apply -f mariadb-pvc.yaml

You should receive con­firm­a­tion that the PVC was created. Verify the PVC is bound by running:

kubectl get pvc mariadb-pvc

If the status column shows Bound everything is correctly connected.

Step 2: Create ConfigMap with my.cnf

To fine-tune MariaDB, create a custom con­fig­ur­a­tion file using a ConfigMap. This will be mounted into the container later.

Save the following to a file named mariadb-config.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
    name: mariadb-config
    labels:
        app: mariadb
data:
    my.cnf: |
        [mysqld]
        bind-address=0.0.0.0
        default_storage_engine=InnoDB
        innodb_file_per_table=1
        max_connections=1000

These settings make MariaDB ac­cess­ible from outside the container (bind-address), enable modern storage features like InnoDB and allow up to 1,000 sim­ul­tan­eous con­nec­tions.

Create the ConfigMap by running:

kubectl apply -f mariadb-config.yaml

Step 3: Create State­ful­Set for MariaDB

A State­ful­Set ensures each pod keeps a con­sist­ent identity and storage. This means your database stays linked to its storage even after it restarts. Save the following to a file named mariadb-statefulset.yaml:

apiVersion: apps/v1
kind: StatefulSet
metadata:
    name: mariadb
spec:
    serviceName: "mariadb"
    replicas: 1
    selector:
        matchLabels:
            app: mariadb
    template:
        metadata:
            labels:
                app: mariadb
        spec:
            containers:
            - name: mariadb
                image: mariadb:latest
                ports:
                - containerPort: 3306
                    name: mariadb
                env:
                - name: MYSQL_ROOT_PASSWORD
                    value: "strong_password"
                volumeMounts:
                - name: mariadb-storage
                    mountPath: /var/lib/mysql
                - name: config-volume
                    mountPath: /etc/mysql/conf.d
            volumes:
            - name: config-volume
                configMap:
                    name: mariadb-config
    volumeClaimTemplates:
    - metadata:
            name: mariadb-storage
        spec:
            accessModes: ["ReadWriteOnce"]
            resources:
                requests:
                    storage: 10Gi

Create the State­ful­Set by running:

kubectl apply -f mariadb-statefulset.yaml

Verify it’s running with:

kubectl get statefulset mariadb

Wait until READY 1/1 is displayed, which means the MariaDB pod is up and running.

Step 4: Set up access via a Kuber­netes service

To let other apps in the cluster access MariaDB create a Kuber­netes Service. Save the following to a file named mariadb-service.yaml:

apiVersion: v1
kind: Service
metadata:
    name: mariadb
spec:
    ports:
    - port: 3306
        targetPort: 3306
    selector:
        app: mariadb

Through this service, the MariaDB-Kuber­netes pod is ac­cess­ible under a fixed DNS name (mariadb).

Create the Service by running:

kubectl apply -f mariadb-service.yaml

Check that it’s available with:

kubectl get svc mariadb

You should see an internal IP address and port 3306. This in­form­a­tion is important for the next step.

Step 5: Connect to the MariaDB Kuber­netes instance

You can test the service by starting a temporary pod that acts as a MySQL client. Run the following command:

kubectl run -it --rm --image=mariadb mariadb-client -h mariadb -u root -p strong_password

When prompted enter the root password you set earlier. At the SQL prompt run:

SHOW DATABASES;

You should see default databases like mysql, information_schema or performance_schema. Type exit to leave the SQL console. The temporary client pod will be deleted auto­mat­ic­ally.

Step 6: Scale State­ful­Set

One benefit of Kuber­netes is easy scaling. If you need more capacity, you can add more MariaDB pods by in­creas­ing the number of replicas.

Execute the following command to run three pods:

kubectl scale statefulset mariadb --replicas=3

This command instructs Kuber­netes to create two ad­di­tion­al pods alongside the existing one. Each pod has its own name (for example, mariadb-0, mariadb-1, mariadb-2) and its own storage.

Verify the scaling by running:

kubectl get statefulset mariadb

You should now see READY 3/3. Then, list the pods:

kubectl get pods -l app=mariadb

When extra capacity isn’t needed, you can scale back:

kubectl scale statefulset mariadb --replicas=1

After a short while only mariadb-0 will remain. The volumes from removed pods are kept until they are deleted manually.