# 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:
- Creating a Kubernetes Cluster
- Deploying PolarDB-X Operator
- Deploying PolarDB-X Cluster
- Connecting to PolarDB-X Cluster
- Destroying PolarDB-X Cluster
- 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.7.0/polardbx-operator-1.6.2.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.
First, you need to obtain the latest image tags for each PolarDB-X component with the following command:
curl -s "https://polardbx-opensource.oss-cn-hangzhou.aliyuncs.com/scripts/get-version.sh" | sh
The output will be as follows (taking PolarDB-X V2.4.0 as an example):
CN polardbx/polardbx-sql:v2.4.0_5.4.19
DN polardbx/polardbx-engine:v2.4.0_8.4.19
CDC polardbx/polardbx-cdc:v2.4.0_5.4.19
Then prepare a yaml file named quick-start.yaml as follows and modify the image tags according to the output:
apiVersion: polardbx.aliyun.com/v1
kind: PolarDBXCluster
metadata:
name: quick-start
spec:
topology:
nodes:
gms:
template:
image: polardbx/polardbx-engine:v2.4.0_8.4.19
resources:
requests:
cpu: 100m
memory: 500Mi
limits:
cpu: 1
memory: 1Gi
cn:
replicas: 1
template:
image: polardbx/polardbx-sql:v2.4.0_5.4.19
resources:
requests:
cpu: 100m
memory: 1Gi
limits:
cpu: 1
memory: 2Gi
dn:
replicas: 1
template:
image: polardbx/polardbx-engine:v2.4.0_8.4.19
resources:
requests:
cpu: 100m
memory: 500Mi
limits:
cpu: 1
memory: 1Gi
cdc:
replicas: 1
template:
image: polardbx/polardbx-cdc:v2.4.0_5.4.19
resources:
requests:
cpu: 100m
memory: 500Mi
limits:
cpu: 1
memory: 1Gi
Run the following command to create the cluster:
kubectl apply -f quick-start.yaml
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.
First, you need to obtain the latest image tags for each PolarDB-X component with the following command:
curl -s "https://polardbx-opensource.oss-cn-hangzhou.aliyuncs.com/scripts/get-version.sh" | sh
The output will be as follows (taking PolarDB-X V2.4.0 as an example):
CN polardbx/polardbx-sql:v2.4.0_5.4.19
DN polardbx/polardbx-engine:v2.4.0_8.4.19
CDC polardbx/polardbx-cdc:v2.4.0_5.4.19
Then prepare a yaml file named quick-start.yaml as follows and modify the image tags according to the output:
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:v2.4.0_8.4.19
resources:
limits:
cpu: 2
memory: 4Gi
- name: log
replicas: 1
role: Voter
template:
spec:
image: polardbx/polardbx-engine:v2.4.0_8.4.19
resources:
limits:
cpu: 1
memory: 2Gi
Execute the following command to create such a cluster:
kubectl apply -f quick-start.yaml
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