部署 GreptimeDB 集群

在该指南中，你将学会如何使用 GreptimeDB Operator 在 Kubernetes 上部署 GreptimeDB 集群。

备注

以下输出可能会因 Helm chart 版本和具体环境的不同而有细微差别。

前置条件

• Docker >= v23.0.0
• kubectl >= v1.18.0
• Helm >= v3.0.0
• kind >= v0.20.0

创建一个测试 Kubernetes 集群

注意

不建议在生产环境或性能测试中使用 kind。如有这类需求建议使用公有云托管的 Kubernetes 服务，如 Amazon EKS、Google GKE 或 Azure AKS，或者自行搭建生产级 Kubernetes 集群。

目前有很多方法可以创建一个用于测试的 Kubernetes 集群。在本指南中，我们将使用 kind 来创建一个本地 Kubernetes 集群。如果你想使用已有的 Kubernetes 集群，可以跳过这一步。

这里是一个使用 kind v0.20.0 的示例：

kind create cluster

预期输出

Creating cluster "kind" ...
 ✓ Ensuring node image (kindest/node:v1.27.3) 🖼
 ✓ Preparing nodes 📦
 ✓ Writing configuration 📜
 ✓ Starting control-plane 🕹️
 ✓ Installing CNI 🔌
 ✓ Installing StorageClass 💾
Set kubectl context to "kind-kind"
You can now use your cluster with:

kubectl cluster-info --context kind-kind

Thanks for using kind! 😊

使用以下命令检查集群的状态：

kubectl cluster-info

预期输出

Kubernetes control plane is running at https://127.0.0.1:60495
CoreDNS is running at https://127.0.0.1:60495/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

备注

中国大陆用户如有网络访问问题，可使用 Greptime 提供的位于阿里云镜像仓库的 kindest/node:v1.27.3 镜像：

kind create cluster --image greptime-registry.cn-hangzhou.cr.aliyuncs.com/kindest/node:v1.27.3

添加 Greptime Helm 仓库

备注

中国大陆用户如有网络访问问题，可跳过这一步骤并直接参考下一步中使用阿里云 OCI 镜像仓库的方式。采用这一方式将无需手动添加 Helm 仓库。

我们提供了 GreptimeDB Operator 和 GreptimeDB 集群的官方 Helm 仓库。你可以通过运行以下命令来添加仓库：

helm repo add greptime https://greptimeteam.github.io/helm-charts/
helm repo update

检查 Greptime Helm 仓库中的 charts：

helm search repo greptime

预期输出

NAME                                         CHART VERSION   APP VERSION     DESCRIPTION
greptime/greptimedb-cluster                     0.8.3           1.0.1           A Helm chart for deploying GreptimeDB cluster i...
greptime/greptimedb-enterprise-dashboard        0.1.0           0.1.0           The Helm chart for deploying GreptimeDB Enterpr...
greptime/greptimedb-infra-test                  0.1.0           0.1.0           The Helm chart for deploying GreptimeDB infra t...
greptime/greptimedb-operator                    0.5.9           0.5.5           The greptimedb-operator Helm chart for Kubernetes.
greptime/greptimedb-remote-compaction           0.1.1           0.1.0           Remote compaction components (scheduler, compac...
greptime/greptimedb-standalone                  0.4.2           1.0.1           A Helm chart for deploying standalone greptimedb

安装和验证 GreptimeDB Operator

现在我们准备使用 Helm 在 Kubernetes 集群上安装 GreptimeDB Operator。

安装 GreptimeDB Operator

GreptimeDB Operator 是一个用于管理 GreptimeDB 集群生命周期的 Kubernetes operator。

让我们在 greptimedb-admin 命名空间中安装最新版本的 GreptimeDB Operator：

helm install greptimedb-operator greptime/greptimedb-operator -n greptimedb-admin --create-namespace

预期输出

NAME: greptimedb-operator
LAST DEPLOYED: Sun Apr 26 20:43:58 2026
NAMESPACE: greptimedb-admin
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
***********************************************************************
 Welcome to use greptimedb-operator
 Chart version: 0.5.9
 GreptimeDB Operator version: 0.5.5
***********************************************************************

Installed components:
* greptimedb-operator

The greptimedb-operator is starting, use `kubectl get deployment greptimedb-operator -n greptimedb-admin` to check its status.

备注

中国大陆用户如有网络访问问题，可直接使用阿里云 OCI 镜像仓库的方式安装 GreptimeDB Operator：

helm install greptimedb-operator \
  oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-operator \
  --set image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \
  -n greptimedb-admin \
  --create-namespace

此时我们也将镜像仓库设置为 Greptime 官方的阿里云镜像仓库。

备注

我们还可以直接使用 kubectl 和 bundle.yaml 来安装最新版本的 GreptimeDB Operator：

kubectl apply -f \
  https://github.com/GreptimeTeam/greptimedb-operator/releases/latest/download/bundle.yaml \
  --server-side

这种方式仅适用于在测试环境快速部署 GreptimeDB Operator，不建议在生产环境中使用。

验证 GreptimeDB Operator 安装

检查 GreptimeDB Operator 的状态：

kubectl get pods -n greptimedb-admin -l app.kubernetes.io/instance=greptimedb-operator

预期输出

NAME                                   READY   STATUS    RESTARTS   AGE
greptimedb-operator-68d684c6cf-qr4q4   1/1     Running   0          4m8s

你也可以检查 CRD 的安装：

kubectl get crds | grep greptimedb

预期输出

greptimedbclusters.greptime.io      2026-04-26T12:43:58Z
greptimedbstandalones.greptime.io   2026-04-26T12:43:58Z

GreptimeDB Operator 将会使用 greptimedbclusters.greptime.io and greptimedbstandalones.greptime.io 这两个 CRD 来管理 GreptimeDB 集群和单机实例。

安装 etcd 集群

GreptimeDB 集群需要一个 etcd 集群来存储元数据。让我们使用 Bitnami 的 etcd Helm chart 来安装一个 etcd 集群。

helm install etcd \
  oci://registry-1.docker.io/bitnamicharts/etcd \
  --version 12.0.8 \
  --set replicaCount=3 \
  --set auth.rbac.create=false \
  --set auth.rbac.token.enabled=false \
  --create-namespace \
  --set global.security.allowInsecureImages=true \
  --set image.registry=docker.io \
  --set image.repository=greptime/etcd \
  --set image.tag=3.6.1-debian-12-r3 \
  -n etcd-cluster

预期输出

NAME: etcd
LAST DEPLOYED: Sun Apr 26 20:49:03 2026
NAMESPACE: etcd-cluster
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
CHART NAME: etcd
CHART VERSION: 12.0.8
APP VERSION: 3.6.1

** Please be patient while the chart is being deployed **

etcd can be accessed via port 2379 on the following DNS name from within your cluster:

    etcd.etcd-cluster.svc.cluster.local

To create a pod that you can use as a etcd client run the following command:

    kubectl run etcd-client --restart='Never' --image docker.io/greptime/etcd:3.6.1-debian-12-r3 --env ETCDCTL_ENDPOINTS="etcd.etcd-cluster.svc.cluster.local:2379" --namespace etcd-cluster --command -- sleep infinity

Then, you can set/get a key using the commands below:

    kubectl exec --namespace etcd-cluster -it etcd-client -- bash
    etcdctl  put /message Hello
    etcdctl  get /message

To connect to your etcd server from outside the cluster execute the following commands:

    kubectl port-forward --namespace etcd-cluster svc/etcd 2379:2379 &
    echo "etcd URL: http://127.0.0.1:2379"

WARNING: There are "resources" sections in the chart not set. Using "resourcesPreset" is not recommended for production. For production installations, please set the following values according to your workload needs:
- resources
- preUpgradeJob.resources
- disasterRecovery.cronjob.resources
  +info https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

Substituted images detected:
- docker.io/greptime/etcd:3.6.1-debian-12-r3

当 etcd 集群准备好后，你可以使用以下命令检查 Pod 的状态：

kubectl get pods -n etcd-cluster -l app.kubernetes.io/instance=etcd

预期输出

NAME     READY   STATUS    RESTARTS   AGE
etcd-0   1/1     Running   0          2m8s
etcd-1   1/1     Running   0          2m8s
etcd-2   1/1     Running   0          2m8s

备注

中国大陆用户如有网络访问问题，可直接使用阿里云 OCI 镜像仓库的方式安装 etcd 集群：

helm install etcd \
  oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/etcd \
  --set image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \
  --set global.security.allowInsecureImages=true \
  --set image.repository=bitnami/etcd \
  --set image.tag=3.6.1-debian-12-r3 \
  --set replicaCount=3 \
  --set auth.rbac.create=false \
  --set auth.rbac.token.enabled=false \
  --create-namespace \
  -n etcd-cluster

你可以通过运行以下命令来测试 etcd 集群：

kubectl -n etcd-cluster \
  exec etcd-0 -- etcdctl endpoint health \
  --endpoints=http://etcd-0.etcd-headless.etcd-cluster.svc.cluster.local:2379,http://etcd-1.etcd-headless.etcd-cluster.svc.cluster.local:2379,http://etcd-2.etcd-headless.etcd-cluster.svc.cluster.local:2379

预期输出

http://etcd-1.etcd-headless.etcd-cluster.svc.cluster.local:2379 is healthy: successfully committed proposal: took = 3.008575ms
http://etcd-0.etcd-headless.etcd-cluster.svc.cluster.local:2379 is healthy: successfully committed proposal: took = 3.136576ms
http://etcd-2.etcd-headless.etcd-cluster.svc.cluster.local:2379 is healthy: successfully committed proposal: took = 3.147702ms

配置 values.yaml

values.yaml 文件设置了 GreptimeDB 的一些参数和配置，是定义 helm chart 的关键。 例如一个最小规模 GreptimeDB 集群定义如下：

image:
  # 镜像仓库地址:
  # OSS GreptimeDB 使用 `greptime-registry.cn-hangzhou.cr.aliyuncs.com`,
  # Enterprise GreptimeDB 请咨询工作人员
  registry: <registry>
  # 镜像仓库：
  # OSS GreptimeDB 使用 `greptime/greptimedb`，
  # Enterprise GreptimeDB 请咨询工作人员
  repository: <repository>
  # 镜像标签：
  # OSS GreptimeDB 使用数据库版本，例如 `v1.0.2`
  # Enterprise GreptimeDB 请咨询工作人员
  tag: <tag>
  pullSecrets: []

initializer:
  registry: greptime-registry.cn-hangzhou.cr.aliyuncs.com
  repository: greptime/greptimedb-initializer
  tag: "v0.6.1"

frontend:
  replicas: 1

meta:
  replicas: 1
  backendStorage:
    etcd:
      endpoints: ["etcd.etcd-cluster.svc.cluster.local:2379"]

datanode:
  replicas: 1

flownode:
  replicas: 1

上述配置不适用于严肃的生产环境，请根据自己的需求调整配置。 可参考配置文档获取完整的 values.yaml 的配置项。

安装 GreptimeDB 集群

在上述步骤中我们已经准备好了 GreptimeDB Operator，etcd 集群以及 GreptimeDB 集群相应的配置， 现在部署一个最小 GreptimeDB 集群：

helm upgrade --install mycluster \
  greptime/greptimedb-cluster \
  --values /path/to/values.yaml \
  -n default

如果你使用了不同的集群名称和命名空间，请将 mycluster 和 default 替换为你的配置。

预期输出

Release "mycluster" does not exist. Installing it now.
NAME: mycluster
LAST DEPLOYED: Sun Apr 26 21:00:40 2026
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
***********************************************************************
 Welcome to use greptimedb-cluster
 Chart version: 0.8.3
 GreptimeDB Cluster version: 1.0.1
***********************************************************************

Installed components:
* greptimedb-meta
* greptimedb-datanode
* greptimedb-frontend
* greptimedb-flownode

The greptimedb-cluster is starting, use `kubectl get pods -n default` to check its status.

当启动集群安装之后，我们可以用如下命令检查 GreptimeDB 集群的状态。若你使用了不同的集群名和命名空间，可将 default 和 mycluster 替换为你的配置：

kubectl -n default get greptimedbclusters.greptime.io mycluster

预期输出

NAME        FRONTEND   DATANODE   META   FLOWNODE   PHASE     VERSION   AGE
mycluster   1          1          1      1          Running   v1.0.1    111s

上面的命令将会显示 GreptimeDB 集群的状态。当 PHASE 为 Running 时，表示 GreptimeDB 集群已经成功启动。

你还可以检查 GreptimeDB 集群的 Pod 状态：

kubectl -n default get pods

预期输出

NAME                                  READY   STATUS    RESTARTS   AGE
mycluster-datanode-0                  1/1     Running   0          2m51s
mycluster-flownode-0                  1/1     Running   0          2m26s
mycluster-frontend-5894994974-w2cls   1/1     Running   0          2m32s
mycluster-meta-58cd4cff6c-ddbxq       1/1     Running   0          2m58s

正如你所看到的，我们默认创建了一个最小的 GreptimeDB 集群，包括 1 个 frontend、1 个 datanode、1 个 flownode 和 1 个 metasrv。关于一个完整的 GreptimeDB 集群的组成，你可以参考 architecture。

探索 GreptimeDB 集群

访问 GreptimeDB 集群

你可以通过使用 kubectl port-forward 命令转发 frontend 服务来访问 GreptimeDB 集群：

kubectl -n default port-forward svc/mycluster-frontend 4000:4000 4001:4001 4002:4002 4003:4003 

预期输出

Forwarding from 127.0.0.1:4000 -> 4000
Forwarding from [::1]:4000 -> 4000
Forwarding from 127.0.0.1:4001 -> 4001
Forwarding from [::1]:4001 -> 4001
Forwarding from 127.0.0.1:4002 -> 4002
Forwarding from [::1]:4002 -> 4002
Forwarding from 127.0.0.1:4003 -> 4003
Forwarding from [::1]:4003 -> 4003

请注意，当你使用了其他集群名和命名空间时，你可以使用如下命令，并将 ${cluster} 和 ${namespace} 替换为你的配置：

kubectl -n ${namespace} port-forward svc/${cluster}-frontend 4000:4000 4001:4001 4002:4002 4003:4003 

注意

如果你想将服务暴露给公网访问，可以使用带有 --address 选项的 kubectl port-forward 命令：

kubectl -n default port-forward --address 0.0.0.0 svc/mycluster-frontend 4000:4000 4001:4001 4002:4002 4003:4003

在将服务暴露给公网访问之前，请确保你已经配置了适当的安全设置。

打开浏览器并访问 http://localhost:4000/dashboard 来访问 GreptimeDB Dashboard。

如果你想使用其他工具如 mysql 或 psql 来连接 GreptimeDB 集群，你可以参考 快速入门。

删除集群

危险

清理操作将会删除 GreptimeDB 集群的元数据和数据。请确保在继续操作之前已经备份了数据。

停止端口转发

可以使用以下命令停止 GreptimeDB 集群的端口转发：

pkill -f kubectl port-forward

卸载 GreptimeDB 集群

可以使用以下命令卸载 GreptimeDB 集群：

helm -n default uninstall mycluster

删除 PVCs

为了安全起见，PVCs 默认不会被删除。如果你想删除 PV 数据，你可以使用以下命令：

kubectl -n default delete pvc -l app.greptime.io/component=mycluster-datanode

清理 etcd 数据

你可以使用以下命令清理 etcd 集群：

kubectl -n etcd-cluster exec etcd-0 -- etcdctl del "" --from-key=true

删除 Kubernetes 集群

如果你使用 kind 创建 Kubernetes 集群，你可以使用以下命令销毁集群：

kind delete cluster