From 0fa6b7c06c4a55007333b68a61791135e5c118a1 Mon Sep 17 00:00:00 2001 From: Weny Xu Date: Wed, 18 Sep 2024 15:03:07 +0800 Subject: [PATCH 1/8] chore: remove redundant section --- .../deployments/deploy-on-kubernetes/overview.md | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/docs/user-guide/deployments/deploy-on-kubernetes/overview.md b/docs/user-guide/deployments/deploy-on-kubernetes/overview.md index e507b8d73..b6ba3de49 100644 --- a/docs/user-guide/deployments/deploy-on-kubernetes/overview.md +++ b/docs/user-guide/deployments/deploy-on-kubernetes/overview.md @@ -12,19 +12,6 @@ This guide provides a walkthrough on how to deploy a GreptimeDB cluster on Kuber - [Helm v3](https://helm.sh/docs/intro/install/): A package manager for Kubernetes. -- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl): A command-line tool for interacting with Kubernetes clusters. - -## Add Helm repository - -Use the command below to add the GreptimeDB Helm chart repository. - -```shell -helm repo add greptime https://greptimeteam.github.io/helm-charts/ -helm repo update -``` - -You can find the maintained [Helm charts](https://github.com/GreptimeTeam/helm-charts) in the GitHub repository. - ## Components The deployment on Kubernetes involves the following components: @@ -37,6 +24,6 @@ The deployment on Kubernetes involves the following components: To deploy GreptimeDB on Kubernetes, follow these steps: -- [GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md): This section guides you on installing the GreptimeDB Operator. +- [Deploy GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md): This section guides you on installing the GreptimeDB Operator. - [Deploy GreptimeDB Cluster](deploy-greptimedb-cluster.md): This section provides instructions on how to deploy etcd cluster and GreptimeDB cluster on Kubernetes. - [Destroy Cluster](destroy-cluster.md): This section describes how to uninstall the GreptimeDB Operator and the GreptimeDB cluster. From ffd445fbeb9f420be64b0ac97683a16873a8bd67 Mon Sep 17 00:00:00 2001 From: Weny Xu Date: Thu, 19 Sep 2024 17:09:44 +0800 Subject: [PATCH 2/8] refactor: refactor GreptimeDB k8s deployment part --- .../deploy-greptimedb-cluster.md | 158 ++++++++++++------ 1 file changed, 110 insertions(+), 48 deletions(-) diff --git a/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md b/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md index b79b1882c..cad640405 100644 --- a/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md +++ b/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md @@ -1,32 +1,44 @@ # Deploy GreptimeDB Cluster -Before the deployment, -make sure you have already installed [GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md) on your Kubernetes cluster. +This guide will walk you through deploying a GreptimeDB cluster on a Kubernetes (K8s) environment. Make sure the [GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md) is installed on your cluster before proceeding. We’ll cover everything from setting up an etcd cluster (optional) to configuring options and connecting to the database. -## Using Helm for deployment +## Prerequisites +- [Helm](https://helm.sh/docs/intro/install/) (Use the Version appropriate for your Kubernetes API version) +- [GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md) (Assumes the local host has a matching installation of the GreptimeDB Operator) -### Create an etcd cluster +## Create an etcd cluster (Optional) -First, establish an etcd cluster to support GreptimeDB by executing the following command: +To install the ectd cluster, run the following `helm install` command. This command also creates a dedicated namespace `etcd-cluster` for the installation. ```shell -helm upgrade \ - --install etcd oci://registry-1.docker.io/bitnamicharts/etcd \ +helm install etcd oci://registry-1.docker.io/bitnamicharts/etcd \ --set replicaCount=3 \ - --set auth.rbac.create=false \ + --set auth.rbac.create=false \**** --set auth.rbac.token.enabled=false \ --create-namespace \ -n etcd-cluster ``` -After the installation, -you can get the etcd cluster endpoints `etcd.etcd.svc.cluster.local:2379` from the installation logs. -The endpoints are required for deploying the GreptimeDB cluster in the subsequent step. +### Verify the etcd cluster installation +Once installed, verify the status of the etcd cluster by listing the pods in the `etcd-cluster` namespace: -### Create a GreptimeDB cluster +```bash +kubectl get pods -n etcd-cluster +``` + +You should see output similar to this: +```bash +NAME READY STATUS RESTARTS AGE +etcd-0 1/1 Running 0 80s +etcd-1 1/1 Running 0 80s +etcd-2 1/1 Running 0 80s +``` + +## Deploy a minimum GreptimeDB cluster -Deploy the GreptimeDB cluster, ensuring it connects to the previously established etcd cluster: - +Next, deploy a minimum GreptimeDB cluster. The deployment will depend on an etcd cluster for coordination. If you already have one running, you can use its endpoint. If you followed the steps above, use `etcd.etcd-cluster.svc.cluster.local:2379` as the etcd endpoint. + +Run this command to install the GreptimeDB cluster: ```shell helm install greptimedb greptime/greptimedb-cluster \ --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ @@ -34,11 +46,60 @@ helm install greptimedb greptime/greptimedb-cluster \ -n greptimedb-cluster ``` -### Setting Resource requests and limits +### Verify the GreptimeDB cluster installation +Check that all pods are running properly in the `greptimedb-cluster` namespace: + +```bash +kubectl get pods -n greptimedb-cluster +``` + +You should see output similar to this: +```bash +NAME READY STATUS RESTARTS AGE +my-greptimedb-datanode-0 1/1 Running 0 30s +my-greptimedb-datanode-2 1/1 Running 0 30s +my-greptimedb-datanode-1 1/1 Running 0 30s +my-greptimedb-frontend-7476dcf45f-tw7mx 1/1 Running 0 16s +my-greptimedb-meta-689cb867cd-cwsr5 1/1 Running 0 31s +``` + +## Advanced Configuration Options -The GreptimeDB Helm charts enable you to specify resource requests and limits for each component within your deployment. +### Use Object Storage as backend storage +To store data on Object Storage (here is example to store on Amazon S3), add the following configuration to your Helm command: + +```bash +helm install \ + --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ + --set objectStorage.s3.bucket="your-bucket" \ + --set objectStorage.s3.region="region-of-bucket" \ + --set objectStorage.s3.root="root-directory-of-data" \ + --set objectStorage.credentials.accessKeyId="your-access-key-id" \ + --set objectStorage.credentials.secretAccessKey="your-secret-access-key" \ + greptime/greptimedb-cluster \ + -n greptimedb-cluster +``` -Here's how you can configure these settings: +### Using RemoteWAL and enable the Region Failover +If you want to enable RemoteWAL and region failover, follow this configuration. You’ll need a Kafka cluster running, and you can use its endpoint like `kafka.kafka-cluster.svc.cluster.local:9092`: + +```bash +helm install \ + --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ + --set meta.enableRegionFailover=true \ + --set objectStorage.s3.bucket="your-bucket" \ + --set objectStorage.s3.region="region-of-bucket" \ + --set objectStorage.s3.root="root-directory-of-data" \ + --set objectStorage.credentials.accessKeyId="your-access-key-id" \ + --set objectStorage.credentials.secretAccessKey="your-secret-access-key" \ + --set remoteWal.enable=true \ + --set remoteWal.kafka.brokerEndpoints=kafka.kafka-cluster.svc.cluster.local:9092 \ + greptime/greptimedb-cluster \ + -n greptimedb-cluster +``` + +### Resource requests and limits +To control resource allocation (CPU and memory), modify the Helm installation command as follows: ```shell helm install greptimedb greptime/greptimedb-cluster \ @@ -53,47 +114,48 @@ helm install greptimedb greptime/greptimedb-cluster \ -n greptimedb-cluster ``` -For a comprehensive list of configurable values via Helm, -please refer to the [value configuration](https://github.com/GreptimeTeam/helm-charts/blob/main/charts/greptimedb-cluster/README.md#values). +### Complex Configurations with values.yaml - +```bash +curl -sLo values.yaml https://raw.githubusercontent.com/GreptimeTeam/helm-charts/main/charts/greptimedb-cluster/values.yaml +``` -## Using kubectl for deployment - -Alternatively, you can manually create a GreptimeDB cluster using `kubectl`. -Start by creating a configuration file named `greptimedb-cluster.yaml` with the following content: - -```yml -apiVersion: greptime.io/v1alpha1 -kind: GreptimeDBCluster -metadata: - name: greptimedb - namespace: greptimedb-cluster -spec: - base: - main: - image: greptime/greptimedb - frontend: - replicas: 1 - meta: - replicas: 1 - etcdEndpoints: - - "etcd.etcd-cluster.svc.cluster.local:2379" - datanode: - replicas: 3 +Edit the file to include your custom settings. Here’s an example: + +```yaml +meta: + configData: |- + selector = "round_robin" +datanode: + configData: |- + [[region_engine]] + [region_engine.mito] + global_write_buffer_size = "4GB" +frontend: + configData: |- + [meta_client] + ddl_timeout = "60s" ``` -Apply this configuration to instantiate the GreptimeDB cluster: +Then, deploy using the modified values file: -```shell -kubectl apply -f greptimedb-cluster.yaml +```bash +helm install greptimedb greptime/greptimedb-cluster --values values.yaml ``` +For a comprehensive list of configurable values via Helm, +please refer to the [configuration](../configuration.md), [value configuration](https://github.com/GreptimeTeam/helm-charts/blob/main/charts/greptimedb-cluster/README.md#values). + + + ## Connect to the cluster -After the installation, you can use `kubectl port-forward` to forward the service ports of the GreptimeDB cluster: +After the installation is complete, use `kubectl port-forward` to expose the service ports so that you can connect to the cluster locally: + ```shell # You can use the MySQL or PostgreSQL client to connect the cluster, for example: 'mysql -h 127.0.0.1 -P 4002'. From 28c87e57cd0ba03dbffae8e174b8b298f3cc5a3c Mon Sep 17 00:00:00 2001 From: Weny Xu Date: Fri, 20 Sep 2024 17:51:18 +0800 Subject: [PATCH 3/8] chore: apply suggestions from CR --- .../deploy-greptimedb-cluster.md | 68 +++++++++++-------- 1 file changed, 41 insertions(+), 27 deletions(-) diff --git a/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md b/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md index cad640405..91ec6733c 100644 --- a/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md +++ b/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md @@ -1,19 +1,19 @@ # Deploy GreptimeDB Cluster -This guide will walk you through deploying a GreptimeDB cluster on a Kubernetes (K8s) environment. Make sure the [GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md) is installed on your cluster before proceeding. We’ll cover everything from setting up an etcd cluster (optional) to configuring options and connecting to the database. +This guide will walk you through deploying a GreptimeDB cluster on a Kubernetes environment. Make sure the [GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md) is installed on your cluster before proceeding. We’ll cover everything from setting up an etcd cluster (optional) to configuring options and connecting to the database. ## Prerequisites - [Helm](https://helm.sh/docs/intro/install/) (Use the Version appropriate for your Kubernetes API version) - [GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md) (Assumes the local host has a matching installation of the GreptimeDB Operator) -## Create an etcd cluster (Optional) +## Create an etcd cluster -To install the ectd cluster, run the following `helm install` command. This command also creates a dedicated namespace `etcd-cluster` for the installation. +To install the ectd cluster, run the following `helm install` command. This command also creates a dedicated namespace `etcd-cluster` for the installation. ```shell helm install etcd oci://registry-1.docker.io/bitnamicharts/etcd \ --set replicaCount=3 \ - --set auth.rbac.create=false \**** + --set auth.rbac.create=false \ --set auth.rbac.token.enabled=false \ --create-namespace \ -n etcd-cluster @@ -56,11 +56,11 @@ kubectl get pods -n greptimedb-cluster You should see output similar to this: ```bash NAME READY STATUS RESTARTS AGE -my-greptimedb-datanode-0 1/1 Running 0 30s -my-greptimedb-datanode-2 1/1 Running 0 30s -my-greptimedb-datanode-1 1/1 Running 0 30s -my-greptimedb-frontend-7476dcf45f-tw7mx 1/1 Running 0 16s -my-greptimedb-meta-689cb867cd-cwsr5 1/1 Running 0 31s +greptimedb-datanode-0 1/1 Running 0 30s +greptimedb-datanode-2 1/1 Running 0 30s +greptimedb-datanode-1 1/1 Running 0 30s +greptimedb-frontend-7476dcf45f-tw7mx 1/1 Running 0 16s +greptimedb-meta-689cb867cd-cwsr5 1/1 Running 0 31s ``` ## Advanced Configuration Options @@ -71,11 +71,11 @@ To store data on Object Storage (here is example to store on Amazon S3), add the ```bash helm install \ --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ - --set objectStorage.s3.bucket="your-bucket" \ - --set objectStorage.s3.region="region-of-bucket" \ - --set objectStorage.s3.root="root-directory-of-data" \ - --set objectStorage.credentials.accessKeyId="your-access-key-id" \ - --set objectStorage.credentials.secretAccessKey="your-secret-access-key" \ + --set objectStorage.s3.bucket= \ + --set objectStorage.s3.region= \ + --set objectStorage.s3.root= \ + --set objectStorage.credentials.accessKeyId= \ + --set objectStorage.credentials.secretAccessKey= \ greptime/greptimedb-cluster \ -n greptimedb-cluster ``` @@ -87,17 +87,33 @@ If you want to enable RemoteWAL and region failover, follow this configuration. helm install \ --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ --set meta.enableRegionFailover=true \ - --set objectStorage.s3.bucket="your-bucket" \ - --set objectStorage.s3.region="region-of-bucket" \ - --set objectStorage.s3.root="root-directory-of-data" \ - --set objectStorage.credentials.accessKeyId="your-access-key-id" \ - --set objectStorage.credentials.secretAccessKey="your-secret-access-key" \ + --set objectStorage.s3.bucket= \ + --set objectStorage.s3.region= \ + --set objectStorage.s3.root= \ + --set objectStorage.credentials.accessKeyId= \ + --set objectStorage.credentials.secretAccessKey= \ --set remoteWal.enable=true \ - --set remoteWal.kafka.brokerEndpoints=kafka.kafka-cluster.svc.cluster.local:9092 \ + --set remoteWal.kafka.brokerEndpoints[0]=kafka.kafka-cluster.svc.cluster.local:9092 \ greptime/greptimedb-cluster \ -n greptimedb-cluster ``` +### Static authentication +To enable static authentication for GreptimeDB cluster, you can configure user credentials during installation by specifying them with the auth settings. Here's an example of how to do this: + +```bash +helm install greptimedb \ + --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ + --set auth.enabled=true \ + --set auth.users[0].username=admin \ + --set auth.users[0].password=admin \ + greptime/greptimedb-cluster \ + -n greptimedb-cluster +``` + + + + ### Resource requests and limits To control resource allocation (CPU and memory), modify the Helm installation command as follows: @@ -114,15 +130,17 @@ helm install greptimedb greptime/greptimedb-cluster \ -n greptimedb-cluster ``` -### Complex Configurations with values.yaml +### Complex configurations with values.yaml -For more intricate configurations, first download the default values.yaml file and modify it locally. +For more intricate configurations, first download the default `values.yaml` file and modify it locally. ```bash curl -sLo values.yaml https://raw.githubusercontent.com/GreptimeTeam/helm-charts/main/charts/greptimedb-cluster/values.yaml ``` -Edit the file to include your custom settings. Here’s an example: +You can configure each component by specifying custom settings in the `configData` fields. For more details, refer to the [configuration](../configuration.md) documentation. + +Below is an example of how to modify the settings in the `values.yaml` file. This example demonstrates how to configure specific components within GreptimeDB. It sets the metasrv's selector type to `round_robin`, adjusts the datanode’s Mito engine by setting `global_write_buffer_size` to `4GB`, and configures the frontend's meta client `ddl_timeout` to `60s`: ```yaml meta: @@ -148,10 +166,6 @@ helm install greptimedb greptime/greptimedb-cluster --values values.yaml For a comprehensive list of configurable values via Helm, please refer to the [configuration](../configuration.md), [value configuration](https://github.com/GreptimeTeam/helm-charts/blob/main/charts/greptimedb-cluster/README.md#values). - - ## Connect to the cluster After the installation is complete, use `kubectl port-forward` to expose the service ports so that you can connect to the cluster locally: From 61e5aed5c61bc78a97e436c3b0ff8021812a4c5a Mon Sep 17 00:00:00 2001 From: Weny Xu Date: Fri, 20 Sep 2024 18:49:20 +0800 Subject: [PATCH 4/8] fix: fix commands --- .../deploy-greptimedb-cluster.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md b/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md index 91ec6733c..9f703cf70 100644 --- a/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md +++ b/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md @@ -69,7 +69,7 @@ greptimedb-meta-689cb867cd-cwsr5 1/1 Running 0 31s To store data on Object Storage (here is example to store on Amazon S3), add the following configuration to your Helm command: ```bash -helm install \ +helm install greptimedb \ --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ --set objectStorage.s3.bucket= \ --set objectStorage.s3.region= \ @@ -77,6 +77,7 @@ helm install \ --set objectStorage.credentials.accessKeyId= \ --set objectStorage.credentials.secretAccessKey= \ greptime/greptimedb-cluster \ + --create-namespace \ -n greptimedb-cluster ``` @@ -84,9 +85,9 @@ helm install \ If you want to enable RemoteWAL and region failover, follow this configuration. You’ll need a Kafka cluster running, and you can use its endpoint like `kafka.kafka-cluster.svc.cluster.local:9092`: ```bash -helm install \ +helm install greptimedb \ --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ - --set meta.enableRegionFailover=true \ + --set meta.enableRegionFailover=true \ --set objectStorage.s3.bucket= \ --set objectStorage.s3.region= \ --set objectStorage.s3.root= \ @@ -95,6 +96,7 @@ helm install \ --set remoteWal.enable=true \ --set remoteWal.kafka.brokerEndpoints[0]=kafka.kafka-cluster.svc.cluster.local:9092 \ greptime/greptimedb-cluster \ + --create-namespace \ -n greptimedb-cluster ``` @@ -108,17 +110,15 @@ helm install greptimedb \ --set auth.users[0].username=admin \ --set auth.users[0].password=admin \ greptime/greptimedb-cluster \ + --create-namespace \ -n greptimedb-cluster ``` - - - ### Resource requests and limits To control resource allocation (CPU and memory), modify the Helm installation command as follows: ```shell -helm install greptimedb greptime/greptimedb-cluster \ +helm install greptimedb \ --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ --set meta.podTemplate.main.resources.requests.cpu= \ --set meta.podTemplate.main.resources.requests.memory= \ @@ -126,6 +126,7 @@ helm install greptimedb greptime/greptimedb-cluster \ --set datanode.podTemplate.main.resources.requests.memory= \ --set frontend.podTemplate.main.resources.requests.cpu= \ --set frontend.podTemplate.main.resources.requests.memory= \ + greptime/greptimedb-cluster \ --create-namespace \ -n greptimedb-cluster ``` From 97ccef4bd984175933f3350082a7a7e76bea32bb Mon Sep 17 00:00:00 2001 From: Weny Xu Date: Fri, 27 Sep 2024 17:04:00 +0800 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Yiran --- .../deploy-on-kubernetes/deploy-greptimedb-cluster.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md b/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md index 9f703cf70..68e277a9d 100644 --- a/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md +++ b/docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md @@ -81,8 +81,8 @@ helm install greptimedb \ -n greptimedb-cluster ``` -### Using RemoteWAL and enable the Region Failover -If you want to enable RemoteWAL and region failover, follow this configuration. You’ll need a Kafka cluster running, and you can use its endpoint like `kafka.kafka-cluster.svc.cluster.local:9092`: +### Using Remote WAL and enable the Region Failover +If you want to enable Remote WAL and region failover, follow this configuration. You’ll need a Kafka cluster running, and you can use its endpoint like `kafka.kafka-cluster.svc.cluster.local:9092`: ```bash helm install greptimedb \ From 5016686dcce8ca2a1c610ffd1b40230664b0bd97 Mon Sep 17 00:00:00 2001 From: Weny Xu Date: Tue, 8 Oct 2024 11:55:02 +0800 Subject: [PATCH 6/8] docs: add zh docs --- .../deploy-greptimedb-cluster.md | 201 +++++++++++++----- 1 file changed, 145 insertions(+), 56 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md index fdcc6b088..cddaa943e 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md @@ -1,16 +1,18 @@ # 部署 GreptimeDB 集群 -在部署之前，请确保你已经在 Kubernetes 集群上安装了 [GreptimeDB Operator](/user-guide/deployments/deploy-on-kubernetes/manage-greptimedb-operator/deploy-greptimedb-operator.md)。 +本指南将引导您在 Kubernetes 环境中部署 GreptimeDB 集群。在继续之前，请确保您的集群已安装 [GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md)。我们将涵盖从设置 etcd 集群（可选）到配置选项和连接数据库的所有步骤。 -## 使用 Helm 进行部署 +## 前提条件 -### 创建 etcd 集群 +- [Helm](https://helm.sh/docs/intro/install/)（使用与 Kubernetes API 版本匹配的版本） +- [GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md)（假设本地主机已安装匹配版本的 GreptimeDB Operator） -首先，执行以下命令来建立一个 etcd 集群以支持 GreptimeDB： +## 创建 etcd 集群 -```shell -helm upgrade \ - --install etcd oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/etcd \ +要安装 etcd 集群，运行以下 `helm install` 命令。该命令还为安装创建了一个名为 `etcd-cluster` 的专用命名空间。 + +```bash +helm install etcd oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/etcd \ --set image.registry="greptime-registry.cn-hangzhou.cr.aliyuncs.com" \ --set image.repository="bitnami/etcd" \ --set image.tag="3.5.11" \ @@ -21,17 +23,29 @@ helm upgrade \ -n etcd-cluster ``` +## 验证 etcd 集群的安装 + +安装完成后，通过列出 etcd-cluster 命名空间中的 Pod 来验证 etcd 集群的状态： -安装完成后，你可以从安装日志中获取 etcd 集群的 endpoint `etcd.etcd-cluster.svc.cluster.local:2379`。 -该 endpoint 在后续步骤部署 GreptimeDB 集群时需要使用。 +```bash +kubectl get pods -n etcd-cluster +``` -### 创建 GreptimeDB 集群 +您应该看到类似以下的输出： +```bash +NAME READY STATUS RESTARTS AGE +etcd-0 1/1 Running 0 80s +etcd-1 1/1 Running 0 80s +etcd-2 1/1 Running 0 80s +``` -使用如下命令镜像部署： +## 部署最小化的 GreptimeDB 集群 -```shell -helm upgrade \ - --install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-cluster \ +接下来，部署一个最小化的 GreptimeDB 集群。此部署将依赖 etcd 集群进行协调。如果您已有一个正在运行的 etcd 集群，可以使用其端点。如果您按照上面的步骤操作，则使用 `etcd.etcd-cluster.svc.cluster.local:2379` 作为 etcd 端点。 + +运行此命令安装 GreptimeDB 集群： +```bash +helm install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-cluster \ --set image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ --set initializer.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ @@ -39,14 +53,85 @@ helm upgrade \ -n greptimedb-cluster ``` -### 设置资源 +### 验证 GreptimeDB 集群的安装 +检查 `greptimedb-cluster` 命名空间中的所有 Pod 是否正常运行： -GreptimeDB Helm charts 能够为部署中的每个组件指定资源请求和限制。 -以下是如何配置这些设置的示例： +```bash +kubectl get pods -n greptimedb-cluster +``` -```shell -helm upgrade \ - --install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-cluster \ +您应该看到类似以下的输出： +```bash +NAME READY STATUS RESTARTS AGE +greptimedb-datanode-0 1/1 Running 0 30s +greptimedb-datanode-2 1/1 Running 0 30s +greptimedb-datanode-1 1/1 Running 0 30s +greptimedb-frontend-7476dcf45f-tw7mx 1/1 Running 0 16s +greptimedb-meta-689cb867cd-cwsr5 1/1 Running 0 31s +``` + +## 高级配置选项 +### 使用对象存储作为后端存储 +要将数据存储在对象存储中（例如，存储到 Amazon S3），在 Helm 命令中添加以下配置： + +```bash +helm install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-cluster \ + --set image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --set initializer.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ + --set objectStorage.s3.bucket= \ + --set objectStorage.s3.region= \ + --set objectStorage.s3.root= \ + --set objectStorage.credentials.accessKeyId= \ + --set objectStorage.credentials.secretAccessKey= \ + greptime/greptimedb-cluster \ + --create-namespace \ + -n greptimedb-cluster + +``` + +### 使用 RemoteWAL 并启用 Region 故障切换 +如果您希望启用 RemoteWAL 和 region 故障切换，请遵循以下配置。您需要一个正在运行的 Kafka 集群，并可以使用其端点，例如 `kafka.kafka-cluster.svc.cluster.local:9092`： + +```bash +helm install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-cluster \ + --set image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --set initializer.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ + --set meta.enableRegionFailover=true \ + --set objectStorage.s3.bucket= \ + --set objectStorage.s3.region= \ + --set objectStorage.s3.root= \ + --set objectStorage.credentials.accessKeyId= \ + --set objectStorage.credentials.secretAccessKey= \ + --set remoteWal.enable=true \ + --set remoteWal.kafka.brokerEndpoints[0]=kafka.kafka-cluster.svc.cluster.local:9092 \ + greptime/greptimedb-cluster \ + --create-namespace \ + -n greptimedb-cluster +``` + +### 静态身份验证 +要为 GreptimeDB 集群启用静态身份验证，您可以在安装期间通过 auth 设置配置用户凭据。以下是示例： + +```bash +helm install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-cluster \ + --set image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --set initializer.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ + --set auth.enabled=true \ + --set auth.users[0].username=admin \ + --set auth.users[0].password=admin \ + greptime/greptimedb-cluster \ + --create-namespace \ + -n greptimedb-cluster +``` + +### 资源请求与限制 +要控制资源分配（CPU 和内存），请修改 Helm 安装命令，如下所示： + +```bash +helm install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-cluster \ --set image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ --set initializer.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ --set meta.etcdEndpoints=etcd.etcd-cluster.svc.cluster.local:2379 \ @@ -56,55 +141,59 @@ helm upgrade \ --set datanode.podTemplate.main.resources.requests.memory= \ --set frontend.podTemplate.main.resources.requests.cpu= \ --set frontend.podTemplate.main.resources.requests.memory= \ + greptime/greptimedb-cluster \ --create-namespace \ -n greptimedb-cluster ``` -有关通过 Helm 的可配置值的完整列表，请参考 [values](https://github.com/GreptimeTeam/helm-charts/blob/main/charts/greptimedb-cluster/README.md#values). - - -## 使用 kubectl 进行部署 - -你还可以使用 `kubectl` 手动创建 GreptimeDB 集群。 -创建一个名为 `greptimedb-cluster.yaml` 的配置文件，内容如下： - -```yml -apiVersion: greptime.io/v1alpha1 -kind: GreptimeDBCluster -metadata: - name: greptimedb - namespace: greptimedb-cluster -spec: - base: - main: - image: greptime-registry.cn-hangzhou.cr.aliyuncs.com/greptime/greptimedb:latest - frontend: - replicas: 1 - meta: - replicas: 1 - etcdEndpoints: - - "etcd.etcd-cluster.svc.cluster.local:2379" - datanode: - replicas: 3 +### 使用 values.yaml 进行复杂配置 +对于更复杂的配置，首先下载默认的 `values.yaml` 文件并在本地修改。 + +```bash +curl -sLo values.yaml https://raw.githubusercontent.com/GreptimeTeam/helm-charts/main/charts/greptimedb-cluster/values.yaml ``` -使用此配置创建 GreptimeDB 集群： +您可以通过在 `configData` 字段中指定自定义设置来配置各个组件。更多详细信息，请参阅[配置](../configuration.md)文档。 + +以下是如何修改 `values.yaml` 文件设置的示例。此示例展示了如何配置 GreptimeDB 中的特定组件。它将 metasrv 的选择器类型设置为 `round_robin`，通过将 datanode 的 Mito 引擎的 `global_write_buffer_size` 设置为 `4GB` 来调整配置，并将 frontend 的 meta 客户端 `ddl_timeout` 设置为 `60s`： + +```yaml +meta: + configData: |- + selector = "round_robin" +datanode: + configData: |- + [[region_engine]] + [region_engine.mito] + global_write_buffer_size = "4GB" +frontend: + configData: |- + [meta_client] + ddl_timeout = "60s" +``` -```shell -kubectl apply -f greptimedb-cluster.yaml +然后，使用修改后的 `values.yaml` 文件进行部署： + +```bash +helm install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-cluster \ + --set image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --set initializer.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --values values.yaml ``` +有关通过 Helm 配置的详细值列表，请参阅[配置](../configuration.md)和[value](https://github.com/GreptimeTeam/helm-charts/blob/main/charts/greptimedb-cluster/README.md#values)配置。 + ## 连接到集群 +安装完成后，使用 `kubectl port-forward` 命令暴露服务端口，便可以本地连接到集群： -安装完成后，你可以使用 `kubectl port-forward` 转发 GreptimeDB 集群的服务端口： ```shell -# 你可以使用 MySQL 或者 PostgreSQL 客户端连接集群，例如：'mysql -h 127.0.0.1 -P 4002'。 -# HTTP port: 4000 -# gRPC port: 4001 -# MySQL port: 4002 -# PostgreSQL port: 4003 -kubectl port-forward -n greptimedb-cluster svc/greptimedb-frontend 4001:4001 4002:4002 4003:4003 4000:4000 > connections.out & +# 您可以使用 MySQL 或 PostgreSQL 客户端连接集群，例如： 'mysql -h 127.0.0.1 -P 4002'。 +# HTTP 端口：4000 +# gRPC 端口：4001 +# MySQL 端口：4002 +# PostgreSQL 端口：4003 +kubectl port-forward -n greptimedb-cluster svc/greptimedb-frontend 4000: ``` 然后就可以使用 MySQL 客户端来[连接到集群](/user-guide/protocols/mysql.md#连接到服务端)。 From 0501e7393d8db27b5713af6fb09908721059ad8c Mon Sep 17 00:00:00 2001 From: Weny Xu Date: Tue, 8 Oct 2024 15:06:28 +0800 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Yiran --- .../deploy-on-kubernetes/deploy-greptimedb-cluster.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md index cddaa943e..970a7b556 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md @@ -111,8 +111,8 @@ helm install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/char -n greptimedb-cluster ``` -### 静态身份验证 -要为 GreptimeDB 集群启用静态身份验证，您可以在安装期间通过 auth 设置配置用户凭据。以下是示例： +### 鉴权认证 +要为 GreptimeDB 集群启用鉴权认证，您可以在安装期间通过 auth 设置配置用户凭据。以下是示例： ```bash helm install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-cluster \ @@ -127,7 +127,7 @@ helm install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/char -n greptimedb-cluster ``` -### 资源请求与限制 +### 资源用量与限制 要控制资源分配（CPU 和内存），请修改 Helm 安装命令，如下所示： ```bash @@ -155,7 +155,7 @@ curl -sLo values.yaml https://raw.githubusercontent.com/GreptimeTeam/helm-charts 您可以通过在 `configData` 字段中指定自定义设置来配置各个组件。更多详细信息，请参阅[配置](../configuration.md)文档。 -以下是如何修改 `values.yaml` 文件设置的示例。此示例展示了如何配置 GreptimeDB 中的特定组件。它将 metasrv 的选择器类型设置为 `round_robin`，通过将 datanode 的 Mito 引擎的 `global_write_buffer_size` 设置为 `4GB` 来调整配置，并将 frontend 的 meta 客户端 `ddl_timeout` 设置为 `60s`： +以下是如何修改 `values.yaml` 文件设置的示例。此示例展示了如何配置 GreptimeDB 中的特定组件。它将 metasrv 的 selector 类型设置为 `round_robin`，通过将 datanode 的 Mito 引擎的 `global_write_buffer_size` 设置为 `4GB` 来调整配置，并将 frontend 的 meta 客户端 `ddl_timeout` 设置为 `60s`： ```yaml meta: From b93ae493a19ee4ecf8ebb11ca797a36b6d7ab886 Mon Sep 17 00:00:00 2001 From: Weny Xu Date: Tue, 8 Oct 2024 15:07:31 +0800 Subject: [PATCH 8/8] docs: update overview.md --- .../deploy-greptimedb-cluster.md | 2 +- .../deploy-on-kubernetes/overview.md | 25 ++----------------- 2 files changed, 3 insertions(+), 24 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md index 970a7b556..5f4a93fb6 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md @@ -193,7 +193,7 @@ helm install greptimedb oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/char # gRPC 端口：4001 # MySQL 端口：4002 # PostgreSQL 端口：4003 -kubectl port-forward -n greptimedb-cluster svc/greptimedb-frontend 4000: +kubectl port-forward -n greptimedb-cluster svc/greptimedb-frontend 4000:4000 4001:4001 4002:4002 4003:4003 > connections.out & ``` 然后就可以使用 MySQL 客户端来[连接到集群](/user-guide/protocols/mysql.md#连接到服务端)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/overview.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/overview.md index 9a6599b81..982547f97 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/overview.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments/deploy-on-kubernetes/overview.md @@ -14,27 +14,6 @@ - [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)：用于与 Kubernetes 集群交互的命令行工具。 -## 添加 Helm 仓库 - -你使用以下命令添加 GreptimeDB Helm chart 仓库。 - -```shell -helm repo add greptime https://greptimeteam.github.io/helm-charts/ -helm repo update -``` - -你可以在 Github 仓库中找到维护的 [Helm charts](https://github.com/GreptimeTeam/helm-charts)。 - -或者你也可以直接使用阿里云的 OCI 仓库，比如： - -```shell -helm upgrade --install mycluster \ - oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-cluster \ - --values ./values.yaml -``` - -当使用 OCI 仓库的时候**无需显式**地添加 Helm 仓库。**中文文档会以阿里云的 OCI 仓库为主以提升网络速度**，如果有其他仓库，会在文档中说明。 - ## 组件 在 Kubernetes 上部署 GreptimeDB 涉及以下组件： @@ -47,6 +26,6 @@ helm upgrade --install mycluster \ 请按照以下步骤继续操作： -- [GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md)：本章节指导你安装 GreptimeDB Operator。 -- [部署GreptimeDB集群](deploy-greptimedb-cluster.md)：本节介绍了如何在 Kubernetes 上部署 etcd 集群和 GreptimeDB 集群。 +- [部署 GreptimeDB Operator](./manage-greptimedb-operator/deploy-greptimedb-operator.md)：本章节指导你安装 GreptimeDB Operator。 +- [部署 GreptimeDB 集群](deploy-greptimedb-cluster.md)：本节介绍了如何在 Kubernetes 上部署 etcd 集群和 GreptimeDB 集群。 - [销毁集群](destroy-cluster.md)：本节介绍如何卸载 GreptimeDB Operator 和 GreptimeDB 集群。