Quick Links

Endpoint

A regional endpoint is necessary to interact with the MariaDB REST API endpoints. For more information, see the API specification file.

IONOS supports the following endpoints for various locations:

• Berlin, Germany: https://mariadb.de-txl.ionos.com/clusters.

• Frankfurt, Germany: https://mariadb.de-fra.ionos.com/clusters

• Logroño, Spain: https://mariadb.es-vit.ionos.com/clusters

• London, Great Britain: https://mariadb.gb-lhr.ionos.com/clusters

• Newark, United States: https://mariadb.us-ewr.ionos.com/clusters

• Las Vegas, United States: https://mariadb.us-las.ionos.com/clusters

• Lenexa, United States: https://mariadb.us-mci.ionos.com/clusters

• Paris, France: https://mariadb.fr-par.ionos.com/clusters

Request parameter headers

To make authenticated requests to the API, the following fields are mandatory in the request headers:

Examples

The documentation contains curl examples, as the tool is available on Windows 10, Linux, and macOS. You can also refer to the following blog posts on the IONOS website that describe how to execute curl in Linux and Windows systems if you encounter any problems.

The request creates a new MariaDB cluster.

Prerequisite

• Only contract administrators, owners, and users with Access and manage DBaaS privilege can create and manage MariaDB clusters. Ensure that you have the necessary privilege.

Request

Response

Your values will differ from those in the sample code. It may contain different IDs, timestamps etc.

You may have noticed that the metadata.state is BUSY and that the database is not yet reachable. This is because the cloud will create a completely new cluster and needs to provision new nodes for all the requested replicas. This process runs asynchronously in the background and might take up to 30 minutes.

200 Successful operation

This topic describes connecting to MariaDB from your managed Kubernetes cluster.

Prerequisites

Ensure that the following are available before connecting to the database:

• A datacenter with the following id: xyz-my-datacenter.

• A private LAN with id 3 using the network 10.1.1.0/24.

• A database connected to LAN 3 with the following IP address: 10.1.1.5/24.

• A Kubernetes cluster with the following id: xyz-my-cluster.

• ionosctl

Connect to the database from the cluster

In this example, we use DHCP to assign IP addresses to node pools. Therefore, the database must be in the same subnet as the DHCP server.

To enable connectivity, follow these steps:

1. Connect node pools to the private LAN, which is connected to the database:

ionosctl k8s nodepool create --cluster-id xyz-my-cluster --datacenter-id xyz-my-datacenter --lan-ids 3 --dhcp=true --name=my_nodepool

1. Create a pod to test the connectivity. Schedule the pod exclusively for the node pools connected to the additional LAN if you have several node pools.

# pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: connectivity-test
  labels:
    role: connectivity-test
spec:
  containers:
  - name: connectivity-test
    image: mysql
    stdin: true
    tty: true
    command:
      - "/bin/bash"

Alternatively, you can also use the following commands:

1. Create the pod: kubectl apply -f pod.yaml

2. Attach the pod and test connectivity:

kubectl attach -it connectivity-test
mysql -u <USERNAME> -p -h <DNS_NAME> --execute \"SHOW DATABASES;\"

You can retrieve a list of MariaDB clusters and also specify the maximum number of elements to be returned by specifying an integer for limit and defining the pagination using offset.

Additionally, you can also use a response filter (filter.name) to list only the MariaDB clusters that contain the specified name.

Request

curl -X 'GET' \
  'https://mariadb.de-txl.ionos.com/clusters?limit=100&offset=200' \
  -H 'accept: application/json'

Response

202 Successful operation

{
  "type": "collection",
  "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
  "items": [
    {
      "type": "cluster",
      "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
      "metadata": {
        "createdDate": "2020-12-10T13:37:50+01:00",
        "createdBy": "john.doe@example.com",
        "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "lastModifiedDate": "2020-12-11T13:37:50+01:00",
        "lastModifiedBy": "jane.doe@example.com",
        "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "state": "AVAILABLE"
      },
      "properties": {
        "displayName": "MariaDB cluster",
        "mariadbVersion": "10.6",
        "dnsName": "ma-yourcluster.mariadb.region.ionos.com",
        "instances": 2,
        "ram": 2,
        "cores": 4,
        "storageSize": 10,
        "connections": [
          {
            "datacenterId": "5a029f4a-72e5-11ec-90d6-0242ac120003",
            "lanId": "2",
            "cidr": "192.168.1.100/24"
          }
        ],
        "maintenanceWindow": {
          "time": "16:30:59",
          "dayOfTheWeek": "Monday"
        }
      }
    }
  ],
  "offset": 200,
  "limit": 100,
  "_links": {
    "prev": "<PREVIOUS-PAGE-URI>",
    "self": "<THIS-PAGE-URI>",
    "next": "<NEXT-PAGE-URI>"
  }
}

Follow the network specifications and resource considerations listed on this page to successfully set up a MariaDB cluster.

Network configuration

To set up a database inside an existing data center, you should have at least one server in a private LAN. You need to choose an IP address, under which the database leader should be made available.

There is currently no IP address management for databases. If you use your subnet, you may use any IP address in that corresponding subnet. You must choose the IP address of the subnet that IONOS assigns you if your servers use DHCP. The IP address of the subnet can be found in your NIC configuration.

Resource considerations

CPU, RAM, storage, and number of database clusters are counted against quotas. For more information, see Resource allocation.

Database performance depends on the storage type. Currently, IONOS supports only SSD Premium storage type, by default.

The binary log files are stored alongside the database. The amount of files can grow and shrink depending on your workload. For a reasonable performance, we recommend that you set the SSD's storage size to at least 100 GB.

Database backups

All database clusters are backed up automatically. For more information, see Automatic backups.

You can retrieve all backups of a specific MariaDB cluster using its clusterId. Specify a limit to limit the maximum number of elements returned and define pagination using offset.

Request

curl -X 'GET' \
  'https://mariadb.de-txl.ionos.com/clusters/{clusterId}/backups' \
  -H 'accept: application/json'

Response

200 Successful operation

{
  "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
  "items": [
    {
      "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
      "properties": {
        "clusterId": "498ae72f-411f-11eb-9d07-046c59cc737e",
        "earliestRecoveryTargetTime": "2021-10-23T01:21:10Z",
        "size": 2052,
        "baseBackups": [
          {
            "created": "2020-12-10T13:37:50+01:00",
            "size": 543
          }
        ]
      }
    }
  ],
  "offset": 200,
  "limit": 100,
  "total": 200,
  "_links": {
    "prev": "<PREVIOUS-PAGE-URI>",
    "self": "<THIS-PAGE-URI>",
    "next": "<NEXT-PAGE-URI>"
  }
}

The database will be deployed in about five minutes after the creation of your first MariaDB cluster. For more information about creating a MariaDB cluster, see Create a MariaDB Cluster.

You can manually verify whether the create request is successful because the notification mechanism is not yet available. However, you can poll the API to see when the state switches to AVAILABLE. You can use the following command:

while [[ $(curl -sXGET "https://mariadb.de-txl.ionos.com/clusters/${UUID}" -H "Authorization: Bearer ${TOKEN}" | jq -r .metadata.state) != "AVAILABLE" ]]; do
  sleep 5
  clear
  echo -e "Cluster status:\n"
  kg mariadbcluster "${UUID}" -ojsonpath='{.status.conditions}' | yq -P
  echo -e "\ncluster is not available yet, waiting 5 seconds..."
done

Initialize the database and connect it to the cluster

You can connect to your MariaDB cluster soon after its creation. For example, you can connect using the ssh command as follows and the credentials that you set in the POST request:

ssh -i .ignore.id_rsa "root@${CUSTOMER_PUBLIC_IP}"

You can use the following command to set the environment:

DATABASE_IP="CUSTOMER_PUBLIC_IP"
read -p "DNS Name: " DNS_NAME

Alternatively, you can use the following commands to connect to the database:

Manage access

You can create additional users, roles, databases, and other objects via the SQL. These operations are highly dependent on your database architecture.

The PUBLIC role is a special role in which all database users inherit the permissions. This is also important if you want to have a user without write permissions, since by default PUBLIC is only allowed to write to the public schema.

For more information about managing databases, refer to the MariaDB Documentation.

Create Users

The CREATE USER statement can be used to create one or more user accounts in the MariaDB database. Only users with the global CREATE USER privilege or the INSERT privilege for the MySQL database can create users. For more information, refer to the MariaDB Documentation.

CREATE USER user@abc IDENTIFIED BY 'password';
GRANT SELECT ON table.t2 to 'user'@'%';

You can delete a MariaDB cluster using its UUID. The response body will provide details about the cluster's UUID once a MariaDB cluster has been created or when obtaining a list of clusters.

Request

Response

202 Successful operation

The request restores a MariaDB cluster from a backup.

Prerequisites

The backup must:

• belong to the MariaDB cluster to be restored.

• be in the AVAILABLE state.

Request

Response

You will receive a 202 Successful operation when the request is complete.

You can retrieve a list of backups for all MariaDB clusters in your contract. You can specify an integer for limit to return the maximum number of elements and define the pagination using offset.

Request

Response

200 Successful operation

You can retrieve a specific backup of a MariaDB cluster using its ID. You can find the ID when you the list of all MariaDB cluster backups. You can specify an integer for limit to return the maximum number of elements and define the pagination using offset.

Request

Response

200 Successful operation

The request creates a new MariaDB cluster, which involves restoring a backup of an existing MariaDB cluster and configuring it to function as a new cluster. Ensure you have a backup of your MariaDB cluster containing all the necessary data and configuration files for appropriate functioning.

Prerequisite

• Only contract administrators, owners, and users with Access and manage DBaaS privilege can create and manage MariaDB clusters. Ensure that you have the necessary privilege.

Request

Response

Your values will differ from those in the sample code. It may contain different IDs, timestamps etc.

The created cluster is returned with metadata.state set to BUSY, which indicates that the cluster is not yet reachable. This is because the cloud will create a completely new cluster and needs to provision new nodes for all the requested replicas.

200 Successful operation

You can retrieve a MariaDB cluster using its UUID. It is found in the response body when a MariaDB cluster is created or when you retrieve a list of MariaDB clusters using GET.

Request

To query a single cluster, you need the id from your create response.

Response

202 Successful operation