在 Kubernetes 集群上部署 MatrixDB
本文档介绍如何在一个 Kubernetes 集群上安装部署 MatrixDB。
1 在安装之前
1.1 运行环境
- Kubernetes集群
- Kubernetes版本 >= 1.20
- 开启 RBAC
- 开启 DNS
- 可用的 StorageClass 用于数据库存储
- 可以访问互联网以便下载必要的软件包和镜像
1.2 准备工具
您需要能够访问 Kubernetes 集群的客户端 kubectl 和 helm。
同时，您需要足够的权限在 Kubernetes 集群中创建 namespace 并在 namespace 中部署资源。
当使用 helm 安装相应的软件组件时，可以调整必要的参数以适配您的 Kubernetes 集群。
1.3 必要的知识
了解 kubectl 和 helm 的使用方法。
2 安装依赖
2.1 （可选）安装 OpenEBS 以获得可用的 StorageClass openebs-hostpath
如果您的 Kubernetes 集群中没有合适于 MatrixDB 的 StorageClass，
您可以通过部署 OpenEBS 来获得 StorageClass openebs-hostpath 用以作为MatrixDB数据库的存储。
执行
helm repo add openebs https://openebs.github.io/charts
helm repo update
helm upgrade --install openebs --namespace openebs openebs/openebs --create-namespace以便创建 openebs namespace 并在该 namespace 中安装 OpenEBS 的最新版本。
2.2 安装第三方依赖的软件包 cert-manager
MatrixDB 依赖于 cert-manager 来创建和管理证书和密钥。
您需要在 Kubernetes 集群中安装 cert-manager 以使 matrixdb-operator 正常运行。
一般而言，cert-manage 在每个 Kubernetes 集群中只安装一个实例。
请确认您的集群在没有安装 cert-manager 的情况下再进行下面的安装步骤。
如果您的集群已经安装了 cert-manager，请确认其版本 >= 1.6.0
执行
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm upgrade --install \
cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--set installCRDs=true以便创建 cert-manager namespace 并在该 namespace 中安装 cert-manager 的最新版本。
3 安装 matrixdb-operator
matrixdb-operator 是用来在 Kubernetes 集群上部署 MatrixDB 的工具。
您需要在集群中安装它以部署 MatrixDB。
注意!
matrixdb-operator和 MatrixDB 的版本有兼容性的要求，需要选取对应版本的工具进行使用。
详细映射关系请见MatrixDB 与 MatrixDB Operator 的版本映射关系
执行
helm repo add ymatrix https://ymatrix-data.github.io/charts
helm repo update
helm upgrade --install \
matrixdb-operator ymatrix/matrixdb-operator \
--namespace matrixdb-system \
--create-namespace \
--version 0.8.0以便创建 matrixdb-system namespace 并在该 namespace 中安装 matrixdb-operator 的最新版本。
注意!
如果您的 Kubernetes 集群的集群域名不是默认值
cluster.local，您需要配置 matrixdb-operator 的安装参数以使其使用您的集群域名。假设您的 Kubernetes 集群配置的域名是
custom.domain，则您需要在安装 matrixdb-operator 的helm upgrade命令加上以下参数--set kubernetesClusterDomain=custom.domain
在安装完成后，请执行
helm list --namespace matrixdb-system其输出结果如下
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
matrixdb-operator matrixdb-system 1 2022-04-15 17:45:52.919849 +0800 CST deployed matrixdb-operator-0.8.0 0.8.0以确定您安装的 matrixdb-operator 的版本。
在部署数据库时，您需要确认您部署的数据库的容器镜像支持的 matrixdb-operator 版本和安装的 matrixdb-operator 版本一致。
4 部署一个 MatrixDB 数据库集群
4.1 准备 MatrixDB CRD 定义文件
一个参考的文件 db0.yaml 如下
apiVersion: deploy.ymatrix.cn/v1
kind: MatrixDBCluster
metadata:
name: db0 # MatrixDB 集群的名称
spec:
image:
repository: matrixdb/matrixdb-community # 如果您使用企业版，您需要修改这个值至您自己的镜像存储
tag: <DB-TAG-TO-SPECIFY> # 您需要修改这里的tag值以选择能在您安装的 matrixdb-operator 的版本上运行的数据库镜像
master:
enableStandby: true
memory: "500Mi"
cpu: "0.5"
storageClassName: openebs-hostpath # 您可以选择其他您的 Kubernetes 集群支持的 StorageClass
storage: "1Gi"
workerSelector: {}
segments:
count: 1
enableMirror: false
memory: "500Mi"
cpu: "0.5"
storageClassName: openebs-hostpath # 同 spec.master.storageClassName
storage: "1Gi"
workerSelector: {}
gate:
memory: "100Mi"
cpu: "0.1"
storageClassName: openebs-hostpath # 同 spec.master.storageClassName
storage: "1Gi"
workerSelector: {}关于具体的参数配置，请参阅 CRD 文件说明文档。
4.2 准备部署 MatrixDB 的 namespace
执行以下命令以创建一个用于部署 MatrixDB 的 namespace matrixdb-ns。
kubectl create namespace matrixdb-ns4.3 部署 MatrixDB 数据库
经过上面的准备
- MatrixDB CRD 的定义文件，假设这个文件的名字是
db0.yaml。 - 用于部署 MatrixDB 的 namespace ，假设这个 namespace 的名字是
matrixdb-ns。
执行以下命令以部署 db0.yaml 中定义的数据库。
kubectl apply -f db0.yaml --namespace matrixdb-ns在命令成功执行返回后，可以执行
kubectl get mxdb --namespace matrixdb-ns以查看部署的 MatrixDB 集群 db0 的运行情况。
5 集群配置的调整
在使用部署的集群之前，您或许需要调整 MatrixDB 的参数以优化其性能。
5.1 使用 gpconfig 配置集群参数
5.1.1 进入 master 节点
gpconfig 需要在 master 节点中运行，master 节点的主机名格式是 <cluster-name>-0-0。
在上面部署的集群中，master 节点的主机名为 db0-0-0。
执行
kubectl exec -it db0-0-0 --namespace matrixdb-ns -- sudo -u mxadmin -i以在 master 所在的 pod 中打开一个 shell。
5.1.2 使用 gpconfig 进行配置
在打开的 shell 中，可以执行 gpconfig 来查看和修改需要配置的参数。
比如，执行下面的命令来查看所有可以修改的参数。
gpconfig -lgpconfig 的使用方法参见：gpconfig 的说明文档
5.1.3 重新启动数据库
在修改参数完成后，执行下面的命令来重新启动数据库集群以使配置生效。
gpstop -a -r -M fast5.1.4 退出
最后执行 exit 退出 master 所在 pod 的 shell。
6 使用集群
6.1 集群的默认配置
部署的 MatrixDB 的默认管理员用户名和密码如下。请在使用前更改管理员密码。
| 用户名 | 密码 |
|---|---|
| mxadmin | changeme |
6.2 查看已经部署的 service
在使用集群时，您需要确定您连接到的数据库 service。
执行以下命令来查看之前部署的数据库的 service。
kubectl get svc --namespace matrixdb-ns其输出大致如下：
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
db0 ClusterIP None <none> 22/TCP 7d22h
db0-cylinder ClusterIP 172.20.148.232 <none> 4637/TCP 7d22h
db0-gate ClusterIP None <none> 4617/TCP 7d22h
db0-pg ClusterIP 172.20.216.189 <none> 5432/TCP 7d22h
db0-ui ClusterIP 172.20.157.163 <none> 8240/TCP 7d22h其中 db0-pg 是使用数据库服务需要连接的 service。db0-ui 是使用数据库UI需要使用的 service。
6.3 使用 PostgreSQL 12 客户端 psql 连接数据库（请替换样例 IP 地址至您实际的 IP 地址）
6.3.1 直接访问 db0-pg 服务
在能访问 cluster IP 的环境中，执行
psql -h 172.20.216.189 -p 5432 -U mxadmin以连接到数据库。（请按照提示输入 mxadmin 的密码）
6.3.2 使用 port-forward
使用 kubectl port-forward 可以用来临时访问该服务
6.4 连接到 MatrixDB UI（请替换样例 IP 地址至您实际的 IP 地址）
6.4.1 直接访问 db0-ui 服务
在能访问 cluster IP 的环境中，用浏览器打开 http://172.20.157.163:8240
按照提示的输入mxadmin用户的密码以登录 UI
6.4.2 使用 proxy
使用 kubectl proxy 创建的 proxy 可以用来临时访问该服务
6.4.3 在 UI 中使用 Kafka 导入数据
6.5 将数据库应用连接到集群
使用方法同 psql。
7 管理集群
7.1 获得 master 的 shell
目前的 matrixdb-operator 将数据库集群部署为多个 StatefulSet。
比如一个集群 db0 的部署如下
$ kubectl get statefulset
NAME READY AGE
db0-0 2/2 9d
db0-1 2/2 9d
db0-2 2/2 9d
db0-gate 1/1 9d其中，db0-{StatefulSet序号} 的 StatefulSet 是都是数据库集群的组成部分。
StatefulSet 序号为 0 的 StatefulSet 部署的是 master segment。
其对应的 db0-0-{Replication序号} 的 pod 部署了 master segment 的 master（Replication 序号为 0） 和 standby（Replication 序号为 1）。
StatefulSet 序号不是 0 的 StatefulSet 部署的是 data segment。
其对应的 db0-{StatefulSet序号}-{Replication序号} 的 pod 部署了 data segment 的 primary （Replication 序号为 0）和 mirror（Replication 序号为 1）。
主要的 gp* 和 mx* 管理工具均需要在 master 上运行。
可以运行以下的命令来获得运行 master 的 pod 的 shell （以 mxadmin 用户运行）。
kubectl exec -n matrixdb-ns -it db0-0-0 -- sudo -u mxadmin -i7.2 数据PV
存储在数据库中的数据，会最终存储在 PV 中。
这些 PV 是由 matrixdb-operator 创建的 PVC 向 Kubernetes 集群申请创建的。
$ kubectl get pvc
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
db0-data-db0-0-0 Bound pvc-7d7fdf0c-0922-4d2a-9cdd-f72ce9cd8441 1Gi RWO gp2 9d
db0-data-db0-0-1 Bound pvc-966dbad2-f7b0-4af4-b7b1-62073492833d 1Gi RWO gp2 9d
db0-data-db0-1-0 Bound pvc-eaa0bd6f-d9bc-4578-aeec-4375a86d6c21 1Gi RWO gp2 9d
db0-data-db0-1-1 Bound pvc-fac53281-9ffd-423e-ba71-0e3d381b3cc8 1Gi RWO gp2 9d
db0-data-db0-2-0 Bound pvc-a0ddc01a-6cc7-4640-8b8e-1471ccc5a8ab 1Gi RWO gp2 9d
db0-data-db0-2-1 Bound pvc-b5ee24f9-d7e6-4448-8c54-ebdb60488bcb 1Gi RWO gp2 9d
db0-data-db0-gate-0 Bound pvc-ad685e25-8f18-4d30-9227-a3868bb19f90 1Gi RWO gp2 9d这些 PV 都挂载在对应 pod 的 /mxdata 目录下。这些 PVC 和 PV 的生命周期管理需要数据库管理员手动管理。
8 常见问题
8.1 怎样获得 MatrixDB 数据库镜像？
MatrixDB 的社区版的镜像部署在 DockerHub 上，可以直接获取。
如需使用 MatrixDB 的企业版的镜像，请联系我们获取相应的下载链接。
以便能使用 docker 或者 nerdctl 导入到您自己的容器镜像存储中。
假设您已经下载了镜像 matrixdb-v4.5.0.enterprise-v0.8.0.tar.gz。
执行下面的命令将其导入本地的镜像存储，并推送到您的 Kubernetes 集群使用的镜像存储中：
# 使用 docker load 导入镜像文件
gunzip -c matrixdb-v4.5.0.enterprise-v0.8.0.tar.gz | docker load
# 这里省略了输出
...
Loaded image: matrixdb/matrixdb-enterprise:v4.5.0.enterprise-v0.8.0
# retag 镜像
docker tag matrixdb/matrixdb-enterprise:v4.5.0.enterprise-v0.8.0 \
<your-image-repo>/matrixdb-enterprise:v4.5.0.enterprise-v0.8.0
# 把新的 tag 推送到您的镜像存储
docker push <your-image-repo>/matrixdb-enterprise:v4.5.0.enterprise-v0.8.0
# 之后您在部署数据库时可以在 CRD 文件中使用以上的自定义 repo 和 tag