Skip to content

Commit

Permalink
outsource doc and fix some nits
Browse files Browse the repository at this point in the history 
Signed-off-by: sh2 <[email protected]>
  • Loading branch information
@shawnh2
shawnh2 committed Sep 11, 2023
1 parent 7078dae commit 59f532d
Show file tree
Hide file tree
Showing 3 changed files with 4 additions and 204 deletions.
204 changes: 2 additions & 202 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,209 +12,9 @@
<img alt="screenshot" src="./docs/images/screenshot.png" width="800px">
</p>

## Installation
## Documentation

### One-line Installation

Download the binary using the following command:

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

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

You also can install `gtctl` from the AWS-CN S3 bucket:

```console
curl -fsSL https://downloads.greptime.cn/releases/scripts/gtctl/install.sh | sh -s -- -s aws
```

### Homebrew

On macOS, `gtctl` is available via Homebrew:

```console
brew tap greptimeteam/greptime
brew install gtctl
```

### From Source

If you already have the [Go](https://go.dev/doc/install) installed, you can run the `make` command under this project to build `gtctl`:

```console
make gtctl
```

After building, the `gtctl` will be generated in `./bin/`. If you want to install `gtctl`, you can run the `install` command:

```bash
# The built gtctl will be installed in /usr/local/bin.
make install

# The built gtctl will be installed in your customed path.
make install INSTALL_DIR=<your-path>
```

### Enable gtctl autocompletion

#### Bash

The `gtctl` completion script for Bash can be generated with the command `gtctl completion bash`. Sourcing the completion script in your shell enables `gtctl` autocompletion.

```console
echo 'source <(gtctl completion bash)' >> ~/.bashrc
```

#### Zsh

The `gtctl` completion script for Zsh can be generated with the command `gtctl completion zsh`. Sourcing the completion script in your shell enables `gtctl` autocompletion.

```console
mkdir -p $ZSH/completions && gtctl completion zsh > $ZSH/completions/_gtctl
```

#### Fish

The `gtctl` completion script for Fish can be generated with the command `gtctl completion fish`. Sourcing the completion script in your shell enables `gtctl` autocompletion.

```console
gtctl completion fish | source
```

## Getting Started

### Playground

The **fastest** way to experience the GreptimeDB cluster is to use the playground:

```console
gtctl playground
```

The `playground` will deploy the minimal GreptimeDB cluster on your environment in bare-metal mode.

### Deploy in Bare-Metal Environment

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

```console
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:

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

You can refer to the example [`cluster.yaml`](./examples/bare-metal/cluster.yaml) and [`cluster-with-local-artifacts.yaml`](./examples/bare-metal/cluster-with-local-artifacts.yaml).

### Deploy in Kubernetes

#### Prerequisites

- **Kubernetes 1.18 or higher version is required.**

You can use the [`kind`](https://kind.sigs.k8s.io/) to create your own Kubernetes cluster:

```console
kind create cluster
```

#### Cluster Operations

Create your own GreptimeDB cluster and etcd cluster:

```console
gtctl cluster create mycluster -n default
```

If you want to use artifacts(charts and images) that are stored in the CN region, you can enable `--use-greptime-cn-artifacts`:

```console
gtctl cluster create mycluster -n default --use-greptime-cn-artifacts
```

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

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

# List all clusters.
gtctl cluster list
```

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

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

Use your `mysql` client to connect to your cluster:

```console
mysql -h 127.0.0.1 -P 4002
```

If you want to delete the cluster, you can:

```console
# 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:

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

#### Experimental Feature

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

```console
# 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
```

## Development

There are many useful tools provided through Makefile, you can simply run `make help` to get more information:

- Compile the project

```console
make
```

Then the `gtctl` will be generated in `./bin/`.


- Run the unit test

```console
make test
```

- Run the e2e test

```console
make e2e
```
* [Quickstart](https://docs.greptime.com/user-guide/operations/gtctl) to install and use gtctl

## License

Expand Down
2 changes: 1 addition & 1 deletion pkg/cmd/gtctl/cluster/connect/connect.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ func NewConnectCommand(l logger.Logger) *cobra.Command {
return nil
},
}
cmd.Flags().String("p", "mysql", "Specify a database")

cmd.Flags().StringVarP(&options.Namespace, "namespace", "n", "default", "Namespace of GreptimeDB cluster.")
cmd.Flags().StringVarP(&options.Protocol, "protocol", "p", "mysql", "Specify a database")
return cmd
Expand Down
2 changes: 1 addition & 1 deletion pkg/cmd/gtctl/cluster/create/create.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ func NewCreateClusterCommand(l logger.Logger) *cobra.Command {
cmd.Flags().StringVar(&options.StorageRetainPolicy, "retain-policy", "Retain", "Datanode pvc retain policy.")
cmd.Flags().StringVarP(&options.Namespace, "namespace", "n", "default", "Namespace of GreptimeDB cluster.")
cmd.Flags().BoolVar(&options.DryRun, "dry-run", false, "Output the manifests without applying them.")
cmd.Flags().IntVar(&options.Timeout, "timeout", -1, "Timeout in seconds for the command to complete, default is no timeout.")
cmd.Flags().IntVar(&options.Timeout, "timeout", 600, "Timeout in seconds for the command to complete, -1 means no timeout, default is 10 min.")
cmd.Flags().StringArrayVar(&options.Set.rawConfig, "set", []string{}, "set values on the command line for greptimedb cluster, etcd and operator (can specify multiple or separate values with commas: eg. cluster.key1=val1,etcd.key2=val2).")
cmd.Flags().StringVar(&options.GreptimeDBChartVersion, "greptimedb-chart-version", "", "The greptimedb helm chart version, use latest version if not specified.")
cmd.Flags().StringVar(&options.GreptimeDBOperatorChartVersion, "greptimedb-operator-chart-version", "", "The greptimedb-operator helm chart version, use latest version if not specified.")
Expand Down

0 comments on commit 59f532d

Please sign in to comment.