YMatrix

Version Release History
Platform Requirements

YMatrix

Quick Start

Standard Cluster Deployment

Data Modeling

Connecting to The database

Data Writing

Data Migration

Data Query

Maintenance and Monitoring

Performance Tuning

Troubleshooting

Reference Guide

SQL Reference

FAQ

scenario

Deployment under Kubernetes

This document describes how to install and deploy YMatrix on a Kubernetes cluster.

1 Before installation

1.1 Running environment

  • Kubernetes Cluster
    • Kubernetes Version >= 1.20
    • Turn on RBAC
    • Turn on DNS
    • Available StorageClass for database storage
    • Can access the Internet to download necessary software packages and images

1.2 Preparation Tools

You need clients kubectl and helm that have access to the Kubernetes cluster. At the same time, you need sufficient permissions to create a namespace in the Kubernetes cluster and deploy resources in the namespace. When installing the corresponding software components using helm, you can adjust the necessary parameters to fit your Kubernetes cluster.

1.3 Necessary knowledge

Learn how to use kubectl and helm.

2 Installation dependencies

2.1 (Optional) Install OpenEBS for available StorageClass openebs-hostpath

If you do not have StorageClass for YMatrix in your Kubernetes cluster, You can use the StorageClass openebs-hostpath as storage for the YMatrix database by deploying OpenEBS.

See OpenEBS helm installation documentation

implement

helm repo add openebs https://openebs.github.io/charts
helm repo update
helm upgrade --install openebs --namespace openebs openebs/openebs --create-namespace

In order to create openebs namespace and install the latest version of OpenEBS in that namespace.

2.2 Installing third-party dependency software package cert-manager

YMatrix relies on cert-manager to create and manage certificates and keys. You need to install cert-manager in your Kubernetes cluster to make matrixdb-operator work properly. Generally speaking, cert-manage only installs one instance per Kubernetes cluster. Please make sure that your cluster does not have cert-manager installed before performing the following installation steps.

If your cluster already has cert-manager installed, please confirm its version >= 1.6.0

See cert-manager helm installation documentation

implement

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

In order to create the cert-manager namespace and install the latest version of cert-manager in that namespace.

3 Install matrixdb-operator

matrixdb-operator is a tool used to deploy YMatrix on a Kubernetes cluster. You need to install it in the cluster to deploy YMatrix.

See our helm chart library

Note!

The matrixdb-operator and YMatrix versions have compatibility requirements, and you need to select the corresponding version of the tool for use. For detailed mapping relationships, please see version mapping relationship between YMatrix and YMatrix Operator

implement

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

In order to create a matrixdb-system namespace and install the latest version of matrixdb-operator in that namespace.

Note!

If the cluster domain name of your Kubernetes cluster is not the default value cluster.local, you need to configure the installation parameters of matrixdb-operator to make it use your cluster domain name.

Assuming that the domain name configured by your Kubernetes cluster is custom.domain, you need to add the following parameters to the helm upgrade command where the matrixdb-operator is installed

--set kubernetesClusterDomain=custom.domain

After the installation is complete, please execute

helm list --namespace matrixdb-system

The output result is as follows

NAME                     NAMESPACE                       REVISION        UPDATED                                     STATUS          CHART                          APP VERSION
matrixdb-operator        matrixdb-system                 1               2023-06-06 17:45:52.919849 +0800 CST        deployed        matrixdb-operator-0.12.1        0.12.1

to determine the version of matrixdb-operator you installed.

When deploying a database, you need to confirm that the matrixdb-operator version supported by the container image of the database you deployed is the same as the matrixdb-operator version installed.

4 Deploy a YMatrix database cluster

4.1 Prepare the YMatrix CRD definition file

A reference file db0.yaml is as follows

apiVersion: deploy.ymatrix.cn/v1
kind: MatrixDBCluster
metadata:
  name: db0 # The name of the YMatrix cluster
spec:
  image:
    repository: matrixdb/matrixdb-community # If you are using the Enterprise Edition, you need to modify this value to your own mirroring storage.
    tag: <DB-TAG-TO-SPECIFY> # You need to modify the tag value here to select a database mirroring that can run on the version of matrixdb-operator you installed.
  master:
    enableStandby: true
    memory: "500Mi"
    cpu: "0.5"
    storageClassName: openebs-hostpath # You can choose other StorageClasses supported by your Kubernetes cluster.
    storage: "1Gi"
    workerSelector: {}
  segments:
    count: 1
    enableMirror: false
    memory: "500Mi"
    cpu: "0.5"
    storageClassName: openebs-hostpath # You can choose other StorageClasses supported by your Kubernetes cluster.
    storage: "1Gi"
    workerSelector: {}
  gate:
    memory: "100Mi"
    cpu: "0.1"
    storageClassName: openebs-hostpath # You can choose other StorageClasses supported by your Kubernetes cluster.
    storage: "1Gi"
    workerSelector: {}

For specific parameter configuration, please refer to CRD file description.

4.2 Prepare to deploy YMatrix's namespace

Execute the following command to create a namespace matrixdb-ns for deploying YMatrix.

kubectl create namespace matrixdb-ns

4.3 Deploy YMatrix Database

After the above preparation

  • YMatrix CRD definition file, assuming the name of this file is db0.yaml.
  • Namespace used to deploy YMatrix, assuming the namespace is matrixdb-ns.

Execute the following command to deploy the database defined in db0.yaml.

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

After the command is successfully executed and returned, it can be executed

kubectl get mxdb --namespace matrixdb-ns

To view the operation of the deployed YMatrix cluster db0.

5 Cluster configuration adjustment

Before using the deployed cluster, you may need to adjust the parameters of YMatrix to optimize its performance.

5.1 Use gpconfig to configure cluster parameters

5.1.1 Enter the Master node

gpconfig needs to be run in the Master node, and the hostname format of the Master node is <cluster-name>-0-0. In the cluster deployed above, the host name of the Master node is db0-0-0.

implement

kubectl exec -it db0-0-0 --namespace matrixdb-ns -- sudo -u mxadmin -i

To open a shell in the pod where the Master is located.

5.1.2 Configuring with gpconfig

In an open shell, you can execute gpconfig to view and modify the parameters that need to be configured. For example, execute the following command to view all the parameters that can be modified.

gpconfig -l

How to use gpconfig is shown in: gpconfig's documentation

5.1.3 Restart the database

After the modification parameters are completed, execute the following command to restart the database cluster to make the configuration take effect.

mxstop -a -r -M fast

5.1.4 Exit

Finally, execute exit to exit the shell of the pod where the Master is located.

6 Using clusters

6.1 Default Configuration for Clusters

The default administrator username and password for the deployed YMatrix are as follows. Please change the administrator password before use.

| Username | Password | |--------------------------| | mxadmin | changeme |

6.2 View deployed Services

When using a cluster, you need to determine the database service you are connecting to.

Execute the following command to view the Service of the previously deployed database.

kubectl get svc --namespace matrixdb-ns

The output is roughly as follows:

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

Where db0-pg is the service you need to connect to using the database service. db0-ui is the service you need to use when using the database UI.

6.3 Use PostgreSQL 12 client to connect to the database (please replace the sample IP address to your actual IP address)

6.3.1 Direct access to db0-pg service

In an environment with access to cluster IP, execute

psql -h 172.20.216.189 -p 5432 -U mxadmin

to connect to the database. (Please follow the prompts to enter the password of mxadmin)

6.3.2 Using port-forward

Use kubectl port-forward to temporarily access the service

6.4 Connect to YMatrix UI (please replace the sample IP address to your actual IP address)

6.4.1 Direct access to db0-ui service

In an environment where you can access the cluster IP, open http://172.20.157.163:8240 with your browser

Follow the prompts to enter the password of the mxadmin user to log in to the UI

6.4.2 Using proxy

proxy created with kubectl proxy can be used to temporarily access the service

6.4.3 Importing data using Kafka in the UI

See: Importing data using Kafka

6.5 Connecting database applications to cluster

The usage method is the same as psql.

7 Manage clusters

7.1 Get the master's shell

The current matrixdb-operator deploys the database cluster into multiple StatefulSets. For example, the deployment of a cluster db0 is as follows

$ 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

Among them, the StatefulSet of db0-{StatefulSet serial number} is all part of the database cluster.

StatefulSet The StatefulSet with the serial number 0 deploys the master segment. The corresponding pod of db0-0-{Replication serial number} deploys master segment master (Replication serial number is 0) and standby (Replication serial number is 1).

StatefulSet whose serial number is not 0 is deployed with a data segment. The corresponding pod of db0-{StatefulSet serial number}-{Replication serial number} deploys primary of data segment (Replication serial number is 0) and mirror (Replication serial number is 1).

Both the main gp* and mx* management tools need to be run on master.

You can run the following command to get the shell of the pod running master (run as mxadmin user).

kubectl exec -n matrixdb-ns -it db0-0-0 -- sudo -u mxadmin -i

7.2 Data PV

The data stored in the database will eventually be stored in the PV. These PVs are created by the matrixdb-operator PVC requested to the Kubernetes cluster.

$ 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

These PVs are mounted in the /mxdata directory of the corresponding pod. The life cycle management of these PVCs and PVs require manual management by the database administrator.

8 FAQs

8.1 How to obtain YMatrix database mirroring?

The community version of YMatrix image is deployed on DockerHub and can be obtained directly. If you need a mirror of YMatrix's Enterprise Edition, please contact us for the corresponding download link. so that you can import into your own container image storage using docker or nerdctl.

Suppose you have downloaded the image matrixdb-v5.0.0.enterprise-v0.12.0.tar.gz.

Execute the following command to import it into the local mirror storage and push it to the mirror storage used by your Kubernetes cluster:

# Use docker load to import image files
gunzip -c matrixdb-v5.0.0.enterprise-v0.12.0.tar.gz | docker load
# The output is omitted here
... 
Loaded image: matrixdb/matrixdb-enterprise:v5.0.0.enterprise-v0.12.0

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

# Push new tags to your image storage
docker push <your-image-repo>/matrixdb-enterprise:v5.0.0.enterprise-v0.12.0

# After that, when you deploy the database, you can use the above custom repo and tag in the CRD file.