# Deploy via K8S

This article describes how to create a Kubernetes cluster, deploy PolarDB-X Operator, and use the Operator to deploy a complete PolarDB-X cluster.

Note: The deployment instructions in this article are for testing purposes only and should not be used directly in a production environment.

The article mainly covers the following:

  1. Creating a Kubernetes Cluster
  2. Deploying PolarDB-X Operator
  3. Deploying PolarDB-X Cluster
  4. Connecting to PolarDB-X Cluster
  5. Destroying PolarDB-X Cluster
  6. Uninstalling PolarDB-X Operator

Create a Kubernetes Cluster

This section mainly explains how to use minikube to create a Kubernetes test cluster. You can also use Alibaba Cloud's Container Service ACK to create a Kubernetes cluster and follow the tutorial to deploy PolarDB-X Operator and PolarDB-X cluster.

Using minikube to Create a Kubernetes Cluster

minikube is a tool maintained by the community for quickly creating Kubernetes test clusters, suitable for testing and learning Kubernetes. The Kubernetes cluster created by minikube can run in containers or virtual machines. In this section, we'll use CentOS 8.2 as an example to create Kubernetes.

Note: If deploying minikube on other operating systems such as macOS or Windows, some steps may be slightly different.

Before deploying, make sure minikube and Docker are installed and meet the following requirements:

  • Machine specifications are not less than 4c8g.
  • minikube >= 1.18.0.
  • docker >= 1.19.3.

minikube requires deployment with a non-root account. If you are accessing the machine with the root account, create a new account.

$ useradd -ms /bin/bash polardbx
$ usermod -aG docker polardbx

If you use another account, please add it to the docker group like the one above to ensure it has direct access to Docker.

Switch to the 'polardbx' account using su,

$ su polardbx

```bash
$ su polardbx

Execute the following command to start a Minikube

minikube start --cpus 4 --memory 7960 --image-mirror-country cn --registry-mirror=https://docker.mirrors.ustc.edu.cn

Note: Here, we use Alibaba Cloud's Minikube image source and USTC's Docker image source to accelerate image pulling.

You will see output similar to the following:

😄  minikube v1.23.2 on Centos 8.2.2004 (amd64)
✨  Using the docker driver based on existing profile
❗  Your cgroup does not allow setting memory.
    ▪ More information: https://docs.docker.com/engine/install/linux-postinstall/#your-kernel-does-not-support-cgroup-swap-limit-capabilities
❗  Your cgroup does not allow setting memory.
    ▪ More information: https://docs.docker.com/engine/install/linux-postinstall/#your-kernel-does-not-support-cgroup-swap-limit-capabilities
👍  Starting control plane node minikube in cluster minikube
🚜  Pulling base image ...
🤷  docker "minikube" container is missing, will recreate.
🔥  Creating docker container (CPUs=4, Memory=7960MB) ...
    > kubeadm.sha256: 64 B / 64 B [--------------------------] 100.00% ? p/s 0s
    > kubelet.sha256: 64 B / 64 B [--------------------------] 100.00% ? p/s 0s
    > kubectl.sha256: 64 B / 64 B [--------------------------] 100.00% ? p/s 0s
    > kubeadm: 43.71 MiB / 43.71 MiB [---------------] 100.00% 1.01 MiB p/s 44s
    > kubectl: 44.73 MiB / 44.73 MiB [-------------] 100.00% 910.41 KiB p/s 51s
    > kubelet: 146.25 MiB / 146.25 MiB [-------------] 100.00% 2.71 MiB p/s 54s

    ▪ Generating certificates and keys ...
    ▪ Booting up control plane ...
    ▪ Configuring RBAC rules ...
🔎  Verifying Kubernetes components...
    ▪ Using image registry.cn-hangzhou.aliyuncs.com/google_containers/storage-provisioner:v5 (global image repository)
🌟  Enabled addons: storage-provisioner, default-storageclass
💡  kubectl not found. If you need it, try: 'minikube kubectl -- get pods -A'
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

At this point, Minikube is running normally. Minikube will automatically configure the kubectl configuration file. If kubectl was installed before, you can now use kubectl to access the cluster:

$ kubectl cluster-info
kubectl cluster-info
Kubernetes control plane is running at https://192.168.49.2:8443
CoreDNS is running at https://192.168.49.2:8443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

For those who haven't installed kubectl, Minikube also provides a sub-command to use kubectl:

$ minikube kubectl -- cluster-info
Kubernetes control plane is running at https://192.168.49.2:8443
CoreDNS is running at https://192.168.49.2:8443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Note: The minikube kubectl sub-command needs "--" before kubectl's parameters. For example, in bash shell, you can use alias kubectl="minikube kubectl --" to set a shortcut command. The following operations will use the kubectl command.

Now we can start deploying the PolarDB-X Operator!

After testing, execute minikube delete to destroy the cluster.

Deploy PolarDB-X Operator

Before starting, make sure you meet the following prerequisites:

  • Have a running Kubernetes cluster and ensure that
    • The cluster version is >= 1.18.0
    • There are at least 2 CPUs available
    • There is at least 4GB of available memory
    • There is at least 30GB of available disk space
  • Have installed kubectl to access the Kubernetes cluster
  • Have installed Helm 3

First, create a namespace named polardbx-operator-system,

$ kubectl create namespace polardbx-operator-system

Execute the following command to install the PolarDB-X Operator.

$ helm install --namespace polardbx-operator-system polardbx-operator https://github.com/polardb/polardbx-operator/releases/download/v1.5.0/polardbx-operator-1.5.0.tgz

You can also install from the PolarDB-X Helm Chart repository:

helm repo add polardbx https://polardbx-charts.oss-cn-beijing.aliyuncs.com
helm install --namespace polardbx-operator-system polardbx-operator polardbx/polardbx-operator

Expect to see output like this:

NAME: polardbx-operator
LAST DEPLOYED: Sun Oct 17 15:17:29 2021
NAMESPACE: polardbx-operator-system
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
polardbx-operator is installed. Please check the status of components:

    kubectl get pods --namespace polardbx-operator-system

Now have fun with your first PolarDB-X cluster.

Here's the manifest for quick start:

```yaml
apiVersion: polardbx.aliyun.com/v1
kind: PolarDBXCluster
metadata:
  name: quick-start
  annotations:
    polardbx/topology-mode-guide: quick-start

Check the running status of PolarDB-X Operator components and wait for them to be in the Running state:

$ kubectl get pods --namespace polardbx-operator-system
NAME                                           READY   STATUS    RESTARTS   AGE
polardbx-controller-manager-6c858fc5b9-zrhx9   1/1     Running   0          66s
polardbx-hpfs-d44zd                            1/1     Running   0          66s
polardbx-tools-updater-459lc                   1/1     Running   0          66s

Congratulations! PolarDB-X Operator has been installed. Now you can start deploying a PolarDB-X cluster!

Deploy PolarDB-X Cluster

PolarDB-X currently includes Enterprise Edition and Standard Edition. You can create a cluster according to your needs.

Deploy PolarDB-X Enterprise Edition Cluster

PolarDB-X Enterprise Edition is a distributed architecture cluster that supports larger data volumes and is designed for business scenarios with enterprise-level ultra-high concurrency, large-scale data complex queries, and accelerated analysis. Now let's quickly deploy a PolarDB-X Enterprise Edition cluster, which includes 1 GMS node, 1 CN node, 1 DN node, and 1 CDC node. Execute the following command to create such a cluster:

echo "apiVersion: polardbx.aliyun.com/v1
kind: PolarDBXCluster
metadata:
  name: quick-start
  annotations:
    polardbx/topology-mode-guide: quick-start" | kubectl apply -f -

You will see the following output:

polardbxcluster.polardbx.aliyun.com/quick-start created

Use the following command to check the creation status:

$ kubectl get polardbxcluster -w
NAME          GMS   CN    DN    CDC   PHASE      DISK   AGE
quick-start   0/1   0/1   0/1   0/1   Creating          35s
quick-start   1/1   0/1   1/1   0/1   Creating          93s
quick-start   1/1   0/1   1/1   1/1   Creating          4m43s
quick-start   1/1   1/1   1/1   1/1   Running    2.4 GiB   4m44s

When PHASE is displayed as Running, the PolarDB-X cluster has been successfully deployed! Congratulations, you can now start connecting and experiencing the PolarDB-X distributed database!

Deploy PolarDB-X Standard Edition Cluster

PolarDB-X Standard Edition adopts a three-replica architecture of one leader, one follower, and one logger. Based on X-PAXOS replication, data strong consistency is ensured. It is designed for online business scenarios with ultra-high concurrency, complex queries, and lightweight analysis. Now let's quickly deploy a PolarDB-X Standard Edition cluster, which includes 1 DN node consisting of three replicas. Execute the following command to create such a cluster:

echo "apiVersion: polardbx.aliyun.com/v1
kind: XStore
metadata:
  name: quick-start
spec:
  config:
    controller:
      RPCProtocolVersion: 1
  topology:
    nodeSets:
    - name: cand
      replicas: 2
      role: Candidate
      template:
        spec:
          image: polardbx/polardbx-engine-2.0:latest
          resources:
            limits:
              cpu: "2"
              memory: 4Gi
    - name: log
      replicas: 1
      role: Voter
      template:
        spec:
          image: polardbx/polardbx-engine-2.0:latest
          resources:
            limits:
              cpu: "1"
              memory: 2Gi" | kubectl apply -f -

You will see the following output:

xstore.polardbx.aliyun.com/quick-start created

Use the following command to check the creation status:

$ kubectl get xstore -w
NAME          LEADER                    READY   PHASE     DISK      VERSION   AGE
quick-start   quick-start-4dbh-cand-0   3/3     Running   3.6 GiB   8.0.18    11m

When PHASE is displayed as Running, the PolarDB-X Standard Edition cluster has been successfully deployed! Congratulations, you can now start connecting and experiencing the PolarDB-X database!

Connect to PolarDB-X Cluster

PolarDB-X supports the MySQL transfer protocol and most of the syntax, so you can use the mysql command-line tool to connect to PolarDB-X for database operations.

Before starting, make sure you have installed the mysql command-line tool.

Forward PolarDB-X Port

When creating a PolarDB-X cluster, PolarDB-X Operator will create a service for accessing the cluster, which is, by default, of ClusterIP type. Use the following command to view the service used for access:

$ kubectl get svc quick-start

Expect output like this:

NAME          TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)             AGE
quick-start   ClusterIP   10.110.214.223   <none>        3306/TCP,8081/TCP   5m25s

We use the port-forward command provided by kubectl to forward the service's 3306 port to the local machine and keep the forwarding process alive.

$ kubectl port-forward svc/quick-start 3306

Connect to PolarDB-X Cluster

The Operator will create a default account for the PolarDB-X cluster and store the password in a secret.

Use the following command to view the default account and password:

$ eval pxc=quick-start;eval user=$(kubectl get secret $pxc -o jsonpath={.data} | jq 'keys[0]'); echo "User: $user"; kubectl get secret $pxc -o jsonpath="{.data['$user']}" | base64 -d - | xargs echo "Password:"

User: polardbx_root
Password: rhjnc8p4

Keep the port-forward running, open a new terminal, and execute the following command to connect to the cluster:

$ mysql -h127.0.0.1 -P3306 -upolardbx_root -prhjnc8p4

Expect output like this:

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 6
Server version: 5.6.29 Tddl Server (ALIBABA)

Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.

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>

Congratulations! You have successfully deployed and connected to a PolarDB-X cluster. Now you can start experiencing the capabilities of a distributed database!

Destroy PolarDB-X Cluster

After completing the test, you can destroy the PolarDB-X cluster with the following command:

$ kubectl delete polardbxcluster quick-start

Check again to ensure deletion is complete:

$ kubectl get polardbxcluster quick-start

Uninstall PolarDB-X Operator

Use the following command to uninstall the PolarDB-X Operator:

$ helm uninstall --namespace polardbx-operator-system polardbx-operator

When you uninstall Helm, the corresponding custom resources (CRDs) for PolarDB-X are not automatically removed. To check and remove these resources, you can use the following commands:

$ kubectl get crds | grep polardbx.aliyun.com
polardbxclusters.polardbx.aliyun.com   2021-10-17T07:17:27Z
xstores.polardbx.aliyun.com            2021-10-17T07:17:27Z

$ kubectl delete crds polardbxclusters.polardbx.aliyun.com xstores.polardbx.aliyun.com

results matching ""

    No results matching ""