Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: remove docs in readme and fix some nits #147

Merged
merged 2 commits into from
Sep 11, 2023
Merged

docs: remove docs in readme and fix some nits #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
59f532d
outsource doc and fix some nits
shawnh2 Sep 11, 2023
aedef74
leave some necessary docs in readme
shawnh2 Sep 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 4 additions & 188 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,81 +12,14 @@
<img alt="screenshot" src="./docs/images/screenshot.png" width="800px">
</p>

## Installation
## Quickstart

### One-line Installation

Download the binary using the following command:
Install the `gtctl` binary using the following **one-line installatio**n 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
Expand All @@ -95,126 +28,9 @@ 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
## Documentation

```console
make e2e
```
* [More](https://docs.greptime.com/user-guide/operations/gtctl) features and usage about `gtctl`

## License

Expand Down
2 changes: 1 addition & 1 deletion pkg/cmd/gtctl/cluster/connect/connect.go
View file
Open in desktop
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
Open in desktop
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
Loading