Skip to main content
Version: Preview

Create and connect to a MySQL cluster

This tutorial shows how to create and connect to a MySQL cluster.

Create a MySQL cluster​

Before you start​

  • Install kbcli.

  • Install KubeBlocks.

  • Make sure the MySQL Addon is enabled. The MySQL Addon is installed and enabled by KubeBlocks by default. If you disable it when installing KubeBlocks, enable it first.

    kubectl get addons.extensions.kubeblocks.io mysql
    >
    NAME    TYPE   VERSION   PROVIDER   STATUS    AGE
    mysql   Helm                        Enabled   27h

  • View all the database types and versions available for creating a cluster.

    Make sure the mysql cluster definition is installed.

    kubectl get clusterdefinition mysql
    >
    NAME             TOPOLOGIES   SERVICEREFS   STATUS      AGE
    mysql                                       Available   85m

    View all available versions for creating a cluster.

    kubectl get clusterversions -l clusterdefinition.kubeblocks.io/name=mysql
    >
    NAME           CLUSTER-DEFINITION   STATUS      AGE
    mysql-5.7.44   mysql                Available   27h
    mysql-8.0.33   mysql                Available   27h
    mysql-8.4.2    mysql                Available   27h

  • To keep things isolated, create a separate namespace called demo throughout this tutorial.

    kubectl create namespace demo

Create a cluster​

KubeBlocks supports creating two types of MySQL clusters: Standalone and Replication Cluster. Standalone only supports one replica and can be used in scenarios with lower requirements for availability. For scenarios with high availability requirements, it is recommended to create a Replication Cluster, which creates a cluster with two replicas. To ensure high availability, all replicas are distributed on different nodes by default.

  1. Create a MySQL cluster.

    KubeBlocks implements a Cluster CRD to define a cluster. Here is an example of creating a Replication Cluster.

    If you only have one node for deploying a Replication Cluster, configure the cluster affinity by setting spec.schedulingPolicy or spec.componentSpecs.schedulingPolicy. For details, you can refer to the API docs. But for a production environment, it is not recommended to deploy all replicas on one node, which may decrease the cluster availability.

    cat <<EOF | kubectl apply -f -
    apiVersion: apps.kubeblocks.io/v1
    kind: Cluster
    metadata:
      name: mycluster
      namespace: demo
    spec:
      terminationPolicy: Delete
      componentSpecs:
        - name: mysql
          componentDef: "mysql-8.0" 
          serviceVersion: 8.0.35
          disableExporter: false
          replicas: 2
          resources:
            limits:
              cpu: '0.5'
              memory: 0.5Gi
            requests:
              cpu: '0.5'
              memory: 0.5Gi
          volumeClaimTemplates:
            - name: data
              spec:
                storageClassName: ""
                accessModes:
                  - ReadWriteOnce
                resources:
                  requests:
                    storage: 20Gi
    EOF
    FieldDefinition
    spec.terminationPolicyIt is the policy of cluster termination. Valid values are DoNotTerminate, Delete, WipeOut. For the detailed definition, you can refer to Termination Policy.
    spec.componentSpecsIt is the list of ClusterComponentSpec objects that define the individual Components that make up a Cluster. This field allows customized configuration of each component within a cluster.
    spec.componentSpecs.componentDefIt specifies the ComponentDefinition custom resource (CR) that defines the Component's characteristics and behavior. It supports three different ways to specify the ComponentDefinition: the regular expression (recommended), the full name (recommended), and the name prefix.
    spec.componentSpecs.serviceVersionIt specifies the version of the Service expected to be provisioned by this Component. Valid options are [8.0.30,8.0.31,8.0.32,8.0.33,8.0.34,8.0.35,8.0.36,8.0.37,8.0.38,8.0.39].
    spec.componentSpecs.disableExporterIt determines whether metrics exporter information is annotated on the Component's headless Service. Valid options are [true, false].
    spec.componentSpecs.replicasIt specifies the number of replicas of the component.
    spec.componentSpecs.resourcesIt specifies the resources required by the Component.
    spec.componentSpecs.volumeClaimTemplatesIt specifies a list of PersistentVolumeClaim templates that define the storage requirements for the Component.
    spec.componentSpecs.volumeClaimTemplates.nameIt refers to the name of a volumeMount defined in componentDefinition.spec.runtime.containers[*].volumeMounts.
    spec.componentSpecs.volumeClaimTemplates.spec.storageClassNameIt is the name of the StorageClass required by the claim. If not specified, the StorageClass annotated with storageclass.kubernetes.io/is-default-class=true will be used by default.
    spec.componentSpecs.volumeClaimTemplates.spec.resources.storageYou can set the storage size as needed.

    For more API fields and descriptions, refer to the API Reference.

    Run the following commands to see the created MySQL cluster object:

    kubectl get cluster mycluster -n demo -o yaml

  2. Verify whether this cluster is created successfully.

    kubectl get cluster mycluster -n demo
    >
    NAME        CLUSTER-DEFINITION   VERSION           TERMINATION-POLICY   STATUS    AGE
    mycluster   mysql                mysql-8.0.30      Delete               Running   6m53s

Connect to a MySQL Cluster​

You can use kubectl exec to exec into a Pod and connect to a database.

KubeBlocks operator creates a new Secret called mycluster-conn-credential to store the connection credential of the MySQL cluster. This secret contains the following keys:

  • username: the root username of the MySQL cluster.
  • password: the password of the root user.
  • port: the port of the MySQL cluster.
  • host: the host of the MySQL cluster.
  • endpoint: the endpoint of the MySQL cluster and it is the same as host:port.

  1. Run the command below to get the username and password for the kubectl exec command.

    kubectl get secrets mycluster-conn-credential -n demo -o jsonpath='{.data.username}' | base64 -d
    >
    root
    kubectl get secrets mycluster-conn-credential -n demo -o jsonpath='{.data.password}' | base64 -d
    >
    b8wvrwlm

  2. Exec into the Pod mycluster-mysql-0 and connect to the database using username and password.

    kubectl exec -ti mycluster-mysql-0 -n demo -- bash

    mysql -u root -p b8wvrwlm

For the detailed database connection guide, refer to Connect database.