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

Jump to bottom

Add tkctl user manual #452

Merged
merged 9 commits into from
May 8, 2019
Merged

Add tkctl user manual #452

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
1046e52
Add basic documents for CLI tool
aylei Apr 17, 2019
4ca5c1a
Add TOC for manual
aylei May 5, 2019
c8c1d16
Document about installation and shell completion
aylei May 6, 2019
1e42210
Merge branch 'master' into issue-305-doc
tennix May 8, 2019
7a8e6c3
Address review comments
aylei May 8, 2019
8f6422b
Merge branch 'issue-305-doc' of github.com:aylei/tidb-operator into i…
aylei May 8, 2019
ad60076
Merge branch 'master' into issue-305-doc
aylei May 8, 2019
c67a454
Fix toc anchor link
aylei May 8, 2019
32eec4e
Merge branch 'master' into issue-305-doc
tennix May 8, 2019
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
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,4 @@ vendor
tests/e2e/e2e.test
.orig
tkc
tkctl
aylei marked this conversation as resolved.
Show resolved Hide resolved
252 changes: 252 additions & 0 deletions docs/cli-manual.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,252 @@
# The TiDB Kubernete Contorl(tkctl) User Manual
aylei marked this conversation as resolved.
Show resolved Hide resolved

> **Disclaimer**: The tkctl CLI tool is currently **Alpha**. The design and sub-commands may change in the future, use at your own risk.

The TiDB Kubernetes Control(tkctl) is a command line utility for TiDB operators to operate and diagnose their TiDB clusters in kubernetes.

- [Installation](#installation)
- [Bash Completion](#bash-completion)
aylei marked this conversation as resolved.
Show resolved Hide resolved
- [Kubernetes Configuration](#kubernetes-configuration)
- [Commands](#commands)
- [tkctl version](#tkctl-version)
- [tkctl list](#tkctl-list)
- [tkctl use](#tkctl-use)
- [tkctl info](#tkctl-info)
- [tkctl get](#tkctl-get)
- [tkctl debug](#tkctl-debug)
- [tkctl ctop](#tkctl-ctop)
- [tkctl help](#tkctl-help)
- [tkctl options](#tkctl-options)
aylei marked this conversation as resolved.
Show resolved Hide resolved

# Installation

You can download the pre-built binary or build `tkctl` from source:

### Download the Pre-built Binary

- [MacOS](http://download.pingcap.org/tkctl-darwin-amd64-latest.tgz)
- [Linux](http://download.pingcap.org/tkctl-linux-amd64-latest.tgz)
- [Windows](http://download.pingcap.org/tkctl-windows-amd64-latest.tgz)

### Build from Source

```shell
$ git clone https://github.com/pingcap/tidb-operator.git
$ GOOS=${YOUR_GOOS} make cli
$ mv tkctl /usr/local/bin/tkctl
```

## Bash Completion
aylei marked this conversation as resolved.
Show resolved Hide resolved

BASH
```shell
# setup autocomplete in bash into the current shell, bash-completion package should be installed first.
source <(tkctl completion bash)

# add autocomplete permanently to your bash shell.
echo "source <(tkctl completion bash)" >> ~/.bashrc
```

ZSH
```shell
# setup autocomplete in zsh into the current shell
source <(tkctl completion zsh)

# add autocomplete permanently to your zsh shell
echo "if [ $commands[tkctl] ]; then source <(tkctl completion zsh); fi" >> ~/.zshrc
aylei marked this conversation as resolved.
Show resolved Hide resolved
```

## Kubernetes Configuration

`tkctl` reuse the kubeconfig(default to `~/.kube/config`) file to talk with kubernetes cluster. You don't have to set up `kubectl` to use `tkctl`, but make sure you have `~/.kube/config` properly set. You can verify the configuration by executing:

```shell
$ tkctl version
```

If you see the version of tkctl tool and version of TiDB operator installed in target cluster or "No TiDB Controller Manager found, please install one first.", `tkctl` is correctly configured to access your cluster.

# Commands

## tkctl version

This command used to show the version of **tkctl** and **tidb-operator** installed in target cluster.

Example:
```
$ tkctl version
Client Version: v1.0.0-beta.1-p2-93-g6598b4d3e75705-dirty
TiDB Controller Manager Version: pingcap/tidb-operator:latest
TiDB Scheduler Version: pingcap/tidb-operator:latest
```

## tkctl list

This command used to list all tidb clusters installed.

| Flags | Shorthand | Description |
| ----- | --------- | ----------- |
| --all-namespaces | -A | search all namespaces |
| --output | -o | output format, one of [default,json,yaml], the default format is `default` |

Example:

```
$ tkctl list -A
NAMESPACE NAME PD TIKV TIDB AGE
foo demo-cluster 3/3 3/3 2/2 11m
bar demo-cluster 3/3 3/3 1/2 11m
```

## tkctl use

This command used to specify the current TiDB cluster to use, the other commands could omit `--tidbcluster` option and defaults to select current TiDB cluster if there is a current TiDB cluster set.

Example:

```
$ tkctl use --namespace=foo demo-cluster
Tidb cluster switched to foo/demo-cluster
```

## tkctl info

This command used to get the information of TiDB cluster, the current TiDB cluster will be used if exists.

| Flags | Shorthand | Description |
| ----- | --------- | ----------- |
| --tidb-cluster | -t | select the tidb cluster, default to current TiDB cluster |

Example:

```
$ tkctl info
Name: demo-cluster
Namespace: foo
CreationTimestamp: 2019-04-17 17:33:41 +0800 CST
Overview:
Phase Ready Desired CPU Memory Storage Version
----- ----- ------- --- ------ ------- -------
PD: Normal 3 3 200m 1Gi 1Gi pingcap/pd:v2.1.4
TiKV: Normal 3 3 1000m 2Gi 10Gi pingcap/tikv:v2.1.4
TiDB Upgrade 1 2 500m 1Gi pingcap/tidb:v2.1.4
Endpoints(NodePort):
- 172.16.4.158:31441
- 172.16.4.155:31441
```

## tkctl get [component]

This is a group of commands used to get the details of TiDB cluster componentes, the current TiDB cluster will be used if exists.

Available components: `pd`, `tikv`, `tidb`, `volume`, `all`(query all components)

| Flags | Shorthand | Description |
| ----- | --------- | ----------- |
| --tidb-cluster | -t | select the tidb cluster, default to current TiDB cluster |
| --output | -o | output format, one of [default,json,yaml], the default format is `default` |

Example:

```
$ tkctl get tikv
NAME READY STATUS MEMORY CPU RESTARTS AGE NODE
demo-cluster-tikv-0 2/2 Running 2098Mi/4196Mi 0 3m19s 172.16.4.155
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the CPU column is empty now.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this example the CPU request and limit is not set.

Of course a <none>/<none> is more clear for user, I will open a new issue for this.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

[root@172.16.4.149 ~]# tkctl get tikv
NAME                     READY   STATUS    MEMORY          CPU   RESTARTS   AGE     NODE
cluster-restore-tikv-0   2/2     Running   2098Mi/8292Mi         0          5m22s   172.16.4.150
cluster-restore-tikv-1   2/2     Running   2098Mi/8292Mi         0          5m22s   172.16.4.154
cluster-restore-tikv-2   2/2     Running   2098Mi/8292Mi         0          5m22s   172.16.4.149

I try it on many clusters, but they are all empty.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

emmm... that's a bug

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will amend the manual along with the fix #465

demo-cluster-tikv-1 2/2 Running 2098Mi/4196Mi 0 4m8s 172.16.4.160
demo-cluster-tikv-2 2/2 Running 2098Mi/4196Mi 0 4m45s 172.16.4.157
$ tkctl get volume
tkctl get volume
VOLUME CLAIM STATUS CAPACITY NODE LOCAL
local-pv-d5dad2cf tikv-demo-cluster-tikv-0 Bound 1476Gi 172.16.4.155 /mnt/disks/local-pv56
local-pv-5ade8580 tikv-demo-cluster-tikv-1 Bound 1476Gi 172.16.4.160 /mnt/disks/local-pv33
local-pv-ed2ffe50 tikv-demo-cluster-tikv-2 Bound 1476Gi 172.16.4.157 /mnt/disks/local-pv13
local-pv-74ee0364 pd-demo-cluster-pd-0 Bound 1476Gi 172.16.4.155 /mnt/disks/local-pv46
local-pv-842034e6 pd-demo-cluster-pd-1 Bound 1476Gi 172.16.4.158 /mnt/disks/local-pv74
local-pv-e54c122a pd-demo-cluster-pd-2 Bound 1476Gi 172.16.4.156 /mnt/disks/local-pv72
```

## tkctl debug [pod_name]

This command used to diagnose the Pods of TiDB cluster. It launches a debug container for you which has the nessary troubleshooting tools installed.

| Flags | Shorthand | Description |
| ----- | --------- | ----------- |
| --image | | specify the docker image of debug container, default to `pingcap/tidb-debug:lastest` |
| --container | -c | select the container to diagnose, default to the first container of target Pod |
| --docker-socket | | specify the docker socket of cluster node, default to `/var/run/docker.sock` |


The default image of debug container contains almost all the related tools you may use then diagnosing, however, the image size can be kinda big. You may use `--image=pingcap/tidb-control:latest` if your just need a basic shell, `pd-ctl` and `tidb-ctl`.

Example:
```
$ tkctl debug demo-cluster-tikv-0
# you may have to wait a few seconds or minutes for the debug container running, then you will get the shell prompt
```

## tkctl ctop [pod_name | node/node_name ]

This command used to view the real-time stats of target pod or node. Compare to `kubectl top`, `tkctl ctop` provides network and disk stats, which are important for diagnosing TiDB cluster problem.

| Flags | Shorthand | Description |
| ----- | --------- | ----------- |
| --image | | specify the docker image of ctop, default to `quay.io/vektorlab/ctop:0.7.2` |
| --docker-socket | | specify the docker socket of cluster node, default to `/var/run/docker.sock` |

Example:

```
$ tkctl ctop demo-cluster-tikv-0
$ tkctl ctop node/172.16.4.155
```

If you don't see the prompt, please wait a few seconds or minutes.

## tkctl help [command]

This command used to print the help message of abitrary sub command.

```
$ tkctl help debug
```

## tkctl options

This command used to view the global flags of `tkctl`.

Example:
```
$ tkctl options
The following options can be passed to any command:

--alsologtostderr=false: log to standard error as well as files
--as='': Username to impersonate for the operation
--as-group=[]: Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
--cache-dir='/Users/alei/.kube/http-cache': Default HTTP cache directory
--certificate-authority='': Path to a cert file for the certificate authority
--client-certificate='': Path to a client certificate file for TLS
--client-key='': Path to a client key file for TLS
--cluster='': The name of the kubeconfig cluster to use
--context='': The name of the kubeconfig context to use
--insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will
make your HTTPS connections insecure
--kubeconfig='': Path to the kubeconfig file to use for CLI requests.
--log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
--log_dir='': If non-empty, write log files in this directory
--logtostderr=true: log to standard error instead of files
-n, --namespace='': If present, the namespace scope for this CLI request
--request-timeout='0': The length of time to wait before giving up on a single server request. Non-zero values
should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests.
-s, --server='': The address and port of the Kubernetes API server
--stderrthreshold=2: logs at or above this threshold go to stderr
-t, --tidbcluster='': Tidb cluster name
--token='': Bearer token for authentication to the API server
--user='': The name of the kubeconfig user to use
-v, --v=0: log level for V logs
--vmodule=: comma-separated list of pattern=N settings for file-filtered logging
```
These options are mainly used to talk with the kubernetes cluster, there are two options that used often:

- `--context`: choose the kubernetes cluster
- `--namespace`: choose the kubernetes namespace