Skip to main content
Version: release-0.8

Try out KubeBlocks on Cloud

This guide walks you through the quickest way to get started with KubeBlocks on cloud, demonstrating how to create a demo environment (Playground) with one command.

Preparation​

When deploying KubeBlocks on the cloud, cloud resources are initialized with the help of the terraform script. kbcli downloads the script and stores it locally, then calls the terraform commands to initialize a fully-managed Kubernetes cluster and deploy KubeBlocks on this cluster.

Before you start to try KubeBlocks on AWS​

Make sure you have all the followings prepared.

Configure access key​

Option 1. Use aws configure.

Fill in an access key and run the command below to authenticate the requests.

aws configure
AWS Access Key ID [None]: YOUR_ACCESS_KEY_ID
AWS Secret Access Key [None]: YOUR_SECRET_ACCESS_KEY

You can refer to Quick configuration with aws configure for detailed information.

Option 2. Use environment variables.

export AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_ACCESS_KEY"

Initialize Playground​

kbcli playground init --cloud-provider aws --region us-west-2
  • cloud-provider specifies the cloud provider.
  • region specifies the region to deploy a Kubernetes cluster. You can find the region list on the official website.

During the initialization, kbcli clones the GitHub repository to the directory ~/.kbcli/playground, installs KubeBlocks, and creates a MySQL cluster. After executing the kbcli playground init command, kbcli automatically switches the current context of kubeconfig to the new Kubernetes cluster. Run the command below to view the created cluster.

# View kbcli version
kbcli version

# View the cluster list
kbcli cluster list
note

The initialization lasts about 20 minutes. If the installation fails after a long time, please check your network.

Try KubeBlocks with Playground​

Go through the following instructions to try basic features of KubeBlocks.

Describe a MySQL cluster​

Steps:

  1. View the database cluster list.

    kbcli cluster list

  2. View the details of a specified database cluster, such as STATUS, Endpoints, Topology, Images, and Events.

    kbcli cluster describe mycluster

Access a MySQL cluster​

Option 1. Connect database from container network.

Wait until the status of this cluster is Running, then run kbcli cluster connect to access a specified database cluster. For example,

kbcli cluster connect mycluster

Option 2. Connect database remotely.

Steps:

  1. Get Credentials.

    kbcli cluster connect --show-example --client=cli mycluster

  2. Run port-forward.

    kubectl port-forward service/mycluster-mysql 3306:3306
    >
    Forwarding from 127.0.0.1:3306 -> 3306
    Forwarding from [::1]:3306 -> 3306

  3. Open another terminal tab to connect the database cluster.

    mysql -h 127.0.0.1 -P 3306 -u root -p"******"
    >
    ...
    Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

    mysql> show databases;
    >
    +--------------------+
    | Database           |
    +--------------------+
    | information_schema |
    | mydb               |
    | mysql              |
    | performance_schema |
    | sys                |
    +--------------------+
    5 rows in set (0.02 sec)

Observe a MySQL cluster​

KubeBlocks has complete observability capabilities. This section demonstrates the monitoring function of KubeBlocks.

Steps:

  1. Open the grafana dashboard.

    kbcli dashboard open kubeblocks-grafana

    Result

    A monitoring page on Grafana website is loaded automatically after the command is executed.

  2. Click the Dashboard icon on the left bar and two monitoring panels show on the page. Dashboards

  3. Click General -> MySQL to monitor the status of the MySQL cluster created by Playground. MySQL_panel

High availability of MySQL​

This guide shows a simple failure simulation to show you the failure recovery capability of MySQL.

Delete the Standalone MySQL cluster​

Delete the Standalone MySQL cluster before trying out high availability.

kbcli cluster delete mycluster

Create a Raft MySQL cluster​

You can use kbcli to create a Raft MySQL cluster. The following is an example of creating a Raft MySQL cluster with default configurations.

kbcli cluster create --cluster-definition='apecloud-mysql' --set replicas=3

Simulate leader pod failure recovery​

In this example, delete the leader pod to simulate a failure.

Steps:

  1. Make sure the newly created cluster is Running.

    kbcli cluster list

  2. Find the leader pod name in Topology. In this example, the leader pod's name is maple05-mysql-1.

    kbcli cluster describe maple05
    >
    Name: maple05         Created Time: Jan 27,2023 17:33 UTC+0800
    NAMESPACE        CLUSTER-DEFINITION        VERSION                STATUS         TERMINATION-POLICY
    default          apecloud-mysql            ac-mysql-8.0.30        Running        WipeOut

    Endpoints:
    COMPONENT        MODE             INTERNAL                EXTERNAL
    mysql            ReadWrite        10.43.29.51:3306        <none>

    Topology:
    COMPONENT        INSTANCE               ROLE            STATUS         AZ            NODE                                                 CREATED-TIME
    mysql            maple05-mysql-1        leader          Running        <none>        k3d-kubeblocks-playground-server-0/172.20.0.3        Jan 30,2023 17:33 UTC+0800
    mysql            maple05-mysql-2        follower        Running        <none>        k3d-kubeblocks-playground-server-0/172.20.0.3        Jan 30,2023 17:33 UTC+0800
    mysql            maple05-mysql-0        follower        Running        <none>        k3d-kubeblocks-playground-server-0/172.20.0.3        Jan 30,2023 17:33 UTC+0800

    Resources Allocation:
    COMPONENT        DEDICATED        CPU(REQUEST/LIMIT)        MEMORY(REQUEST/LIMIT)        STORAGE-SIZE        STORAGE-CLASS
    mysql            false            <none>                    <none>                       <none>              <none>

    Images:
    COMPONENT        TYPE         IMAGE
    mysql            mysql        docker.io/apecloud/wesql-server:8.0.30-5.alpha2.20230105.gd6b8719

    Events(last 5 warnings, see more:kbcli cluster list-events -n default mycluster):
    TIME        TYPE        REASON        OBJECT        MESSAGE

  3. Delete the leader pod.

    kubectl delete pod maple05-mysql-1
    >
    pod "maple05-mysql-1" deleted

  4. Connect to the Raft MySQL cluster. It can be accessed within seconds.

    kbcli cluster connect maple05
    >
    Connect to instance maple05-mysql-2: out of maple05-mysql-2(leader), maple05-mysql-1(follower), maple05-mysql-0(follower)
    Welcome to the MySQL monitor.  Commands end with ; or \g.
    Your MySQL connection id is 33
    Server version: 8.0.30 WeSQL Server - GPL, Release 5, Revision d6b8719

    Copyright (c) 2000, 2022, Oracle and/or its affiliates.

    Oracle is a registered trademark of Oracle Corporation and/or its
    affiliates. Other names may be trademarks of their respective
    owners.

    Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

    mysql>

Destroy Playground​

  1. Before destroying Playground, it is recommended to delete the database clusters created by KubeBlocks.

    # View all clusters
    kbcli cluster list -A

    # Delete a cluster
    # A double-check is required or you can add --auto-approve to skip it
    kbcli cluster delete <name>

    # Uninstall KubeBlocks
    # A double-check is required or you can add --auto-approve to skip it
    kbcli kubeblocks uninstall --remove-pvcs --remove-pvs

  2. Destroy Playground.

    kbcli playground destroy
caution

kbcli playground destroy deletes the Kubernetes cluster on the cloud, but there might be residual resources on the cloud, such as volumes and snapshots. Please delete them in time to avoid unexpected costs.