Skip to content

Commit

Permalink
refactor: refactor GreptimeDB k8s deployment part
Browse files Browse the repository at this point in the history
  • Loading branch information
@WenyXu
WenyXu committed Sep 20, 2024
1 parent 0fa6b7c commit ffd445f
Showing 1 changed file with 110 additions and 48 deletions.
158 changes: 110 additions & 48 deletions docs/user-guide/deployments/deploy-on-kubernetes/deploy-greptimedb-cluster.md
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,105 @@
# 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 \
--create-namespace \
-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 \
Expand All @@ -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

<!-- ### Use a different GreptimeDB version
For more intricate configurations, first download the default values.yaml file and modify it locally.

### Specify the database configuration file -->
```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).

<!-- ### Use a different GreptimeDB version
### Specify the database configuration file -->

## 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'.
Expand Down

0 comments on commit ffd445f

Please sign in to comment.