YMatrix 文档

Kubernetes 下的部署

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

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 集群中没有合适于 YMatrix 的 StorageClass，您可以通过部署 OpenEBS 来获得 StorageClass openebs-hostpath 用以作为 YMatrix 数据库的存储。

参见 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

YMatrix 依赖于 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 集群上部署 YMatrix 的工具。您需要在集群中安装它以部署 YMatrix。

参见我们的 helm chart 库

注意!

matrixdb-operator 和 YMatrix 的版本有兼容性的要求，需要选取对应版本的工具进行使用。
详细映射关系请见YMatrix 与 YMatrix 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.13.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-08-08 17:45:52.919849 +0800 CST        deployed        matrixdb-operator-0.13.0        0.13.0

以确定您安装的 matrixdb-operator 的版本。

在部署数据库时，您需要确认您部署的数据库的容器镜像支持的 matrixdb-operator 版本和安装的 matrixdb-operator 版本一致。

4 部署一个 YMatrix 数据库集群

4.1 准备 YMatrix CRD 定义文件

一个参考的文件 db0.yaml 如下

apiVersion: deploy.ymatrix.cn/v1
kind: MatrixDBCluster
metadata:
  name: db0 # YMatrix 集群的名称
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 准备部署 YMatrix 的 namespace

执行以下命令以创建一个用于部署 YMatrix 的 namespace matrixdb-ns。

kubectl create namespace matrixdb-ns

4.3 部署 YMatrix 数据库

经过上面的准备

YMatrix CRD 的定义文件，假设这个文件的名字是 db0.yaml。
用于部署 YMatrix 的 namespace ，假设这个 namespace 的名字是 matrixdb-ns。

执行以下命令以部署 db0.yaml 中定义的数据库。

kubectl apply -f db0.yaml --namespace matrixdb-ns

在命令成功执行返回后，可以执行

kubectl get mxdb --namespace matrixdb-ns

以查看部署的 YMatrix 集群 db0 的运行情况。

5 集群配置的调整

在使用部署的集群之前，您或许需要调整 YMatrix 的参数以优化其性能。

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 重新启动数据库

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

mxstop -a -r -M fast

5.1.4 退出

最后执行 exit 退出 Master 所在 pod 的 shell。

6 使用集群

6.1 集群的默认配置

部署的 YMatrix 的默认管理员用户名和密码如下。请在使用前更改管理员密码。

用户名	密码
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 连接到 YMatrix 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 怎样获得 YMatrix 数据库镜像？

YMatrix 的社区版的镜像部署在 DockerHub 上，可以直接获取。如需使用 YMatrix 的企业版的镜像，请联系我们获取相应的下载链接。以便能使用 docker 或者 nerdctl 导入到您自己的容器镜像存储中。

假设您已经下载了镜像 matrixdb-v5.0.0.enterprise-v0.12.0.tar.gz。

执行下面的命令将其导入本地的镜像存储，并推送到您的 Kubernetes 集群使用的镜像存储中：

# 使用 docker load 导入镜像文件
gunzip -c matrixdb-v5.0.0.enterprise-v0.12.0.tar.gz | docker load
# 这里省略了输出
... 
Loaded image: matrixdb/matrixdb-enterprise:v5.0.0.enterprise-v0.12.0

# retag 镜像
docker tag matrixdb/matrixdb-enterprise:v5.0.0.enterprise-v0.12.0 \
           <your-image-repo>/matrixdb-enterprise:v5.0.0.enterprise-v0.12.0

# 把新的 tag 推送到您的镜像存储
docker push <your-image-repo>/matrixdb-enterprise:v5.0.0.enterprise-v0.12.0

# 之后您在部署数据库时可以在 CRD 文件中使用以上的自定义 repo 和 tag