在 Kubernetes 集群上部署 MatrixDB

本文档介绍如何在一个 Kubernetes 集群上安装部署 MatrixDB。

1 在安装之前

1.1 运行环境

  • Kubernetes集群
    • Kubernetes版本 >= 1.20
    • 开启 RBAC
    • 开启 DNS
    • 可用的 StorageClass 用于数据库存储
    • 可以访问互联网以便下载必要的软件包和镜像

1.2 准备工具

您需要能够访问 Kubernetes 集群的客户端 kubectlhelm。 同时,您需要足够的权限在 Kubernetes 集群中创建 namespace 并在 namespace 中部署资源。 当使用 helm 安装相应的软件组件时,可以调整必要的参数以适配您的 Kubernetes 集群。

1.3 必要的知识

了解 kubectlhelm 的使用方法。

2 安装依赖

2.1 (可选)安装 OpenEBS 以获得可用的 StorageClass openebs-hostpath

如果您的 Kubernetes 集群中没有合适于 MatrixDB 的 StorageClass, 您可以通过部署 OpenEBS 来获得 StorageClass openebs-hostpath 用以作为MatrixDB数据库的存储。

参见 OpenEBS helm 安装文档

执行

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

参见 cert-manager helm 安装文档

执行

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。

参见 我们的 helm chart 库

注意

matrixdb-operator 和 MatrixDB 的版本有兼容性的要求。

对于目前发布的 MatrixDB v4.5.0 版本,请使用 matrixdb-operator v0.8.x 版本部署。

执行

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-ns

4.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 -l

gpconfig 的使用方法参见:gpconfig 的说明文档

5.1.3 重新启动数据库

在修改参数完成后,执行下面的命令来重新启动数据库集群以使配置生效。

gpstop -a -r -M fast

5.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 导入数据

参见:使用 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 -i

7.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