gtctl

README

gtctl

Overview

gtctl(g-t-control) is a command-line tool for managing the GreptimeDB cluster. gtctl is the All-in-One binary that integrates multiple operations of the GreptimeDB cluster.

One-line Installation

curl -fsSL https://raw.githubusercontent.com/greptimeteam/gtctl/develop/hack/install.sh | sh

After downloading, the gtctl will be in the current directory.

Getting Started

Deploy in Bare-Metal Environment

You can deploy the GreptimeDB cluster on a bare-metal environment by the following simple command:

gtctl cluster create mycluster --bare-metal

It will create all the meta information on ${HOME}/.gtctl.

If you want to do more configurations, you can use the yaml format config file:

gtctl cluster create mycluster --bare-metal --config <your-config-file>

You can refer to the example cluster.yaml and cluster-with-local-artifacts.yaml.

Deploy in Kubernetes

Prerequisites

• Kubernetes 1.18 or higher version is required.

  You can use the kind to create your own Kubernetes cluster:

  kind create cluster
  

Cluster Operations

Create your own GreptimeDB cluster and etcd cluster:

gtctl cluster create mycluster -n default

After creating, the whole GreptimeDB cluster will start in the default namespace:

# Get the cluster.
gtctl cluster get mycluster -n default

# List all clusters.
gtctl cluster list

You can use kubectl port-forward command to forward frontend requests:

kubectl port-forward svc/mycluster-frontend 4002:4002 > connections.out &

Use your mysql client to connect to your cluster:

mysql -h 127.0.0.1 -P 4002

If you want to delete the cluster, you can:

# Delete the cluster.
gtctl cluster delete mycluster -n default

# Delete the cluster, including etcd cluster.
gtctl cluster delete mycluster -n default --tear-down-etcd

Dry Run Mode

gtctl provides --dry-run option in cluster creation. If a user executes the command with --dry-run, gtctl will output the manifests content without applying them:

gtctl cluster create mycluster -n default --dry-run

Experimental Feature

You can use the following commands to scale (or down-scale) your cluster:

# Scale datanode to 3 replicas.
gtctl cluster scale <your-cluster> -n <your-cluster-namespace> -c datanode --replicas 3

# Scale frontend to 5 replicas.
gtctl cluster scale <your-cluster> -n <your-cluster-namespace> -c frontend --replicas 5

Specify the image registry

gtctl uses DockerHub as the default image registry and also supports specifying image registry when creating a cluster with the --image-registry option (the AliCloud image registry mirror greptime-registry.cn-hangzhou.cr.aliyuncs.com is now available).

中国用户可使用如下命令创建集群：

gtctl cluster create mycluster --image-registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com

Development

• Compile the project

  make
  

  Then the gtctl will be generated in bin/.

License

gtctl uses the Apache 2.0 license to strike a balance between open contributions and allowing you to use the software however you want.