TiDB
社区
联系我们
​

tkctl 使用指南

tkctl (TiDB Kubernetes Control) 是为 TiDB on Kubernetes 设计的命令行工具，用于运维集群和诊断集群问题。

安装

安装 tkctl 时，可以直接下载预编译的可执行文件，也可以自行从源码进行编译。

下载预编译的可执行文件

下载解压后，将 tkctl 可执行文件加入到可执行文件路径 (PATH) 中即完成安装。

源码编译

要求：Go 版本 1.11 及以上

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

命令自动补全

你可以配置 tkctl 的自动补全以简化使用。

为 BASH 配置自动补全（需要预先安装 bash-completion）的方法如下。

在当前 shell 中设置自动补全：

source <(tkctl completion bash)

永久设置自动补全：

echo "if hash tkctl 2>/dev/null; then source <(tkctl completion bash); fi" >> ~/.bashrc

为 ZSH 配置自动补全的方法如下。

在当前 shell 中设置自动补全：

source <(tkctl completion zsh)

永久设置自动补全：

echo "if hash tkctl 2>/dev/null; then source <(tkctl completion zsh); fi" >> ~/.zshrc

Kubernetes 配置

tkctl 复用了 kubeconfig 文件（默认位置是 ~/.kube/config）来连接 Kubernetes 集群。你可以通过下面的命令来验证 kubeconfig 是否设置正确：

tkctl version

假如上面的命令正确输出服务端的 TiDB Operator 版本，则 kubeconfig 配置正确。

所有命令

tkctl version

该命令用于展示本地 tkctl 和集群中 tidb-operator 的版本：

示例如下：

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

该命令用于列出所有已安装的 TiDB 集群：

参数缩写说明
--all-namespaces-A是否查询所有的 Kubernetes Namespace
--output-o输出格式，可选值有 [default,json,yaml]，默认值为 default

示例如下：

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

该命令用于指定当前 tkctl 操作的 TiDB 集群，在使用该命令设置当前操作的 TiDB 集群后，所有针对集群的操作命令会自动选定该集群，从而可以略去 --tidbcluster 参数。

示例如下：

tkctl use --namespace=foo demo-cluster

Tidb cluster switched to foo/demo-cluster

tkctl info

该命令用于展示 TiDB 集群的信息。

参数缩写说明
--tidb-cluster-t指定 TiDB 集群，默认为当前使用的 TiDB 集群

示例如下：

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:v3.0.0-rc.1
  TiKV:  Normal   3      3        1000m  2Gi     10Gi     pingcap/tikv:v3.0.0-rc.1
  TiDB   Upgrade  1      2        500m   1Gi              pingcap/tidb:v3.0.0-rc.1
Endpoints(NodePort):
  - 172.16.4.158:31441
  - 172.16.4.155:31441

tkctl get [component]

该命令用于获取 TiDB 集群中组件的详细信息。

可选的组件 (component) 有： pd、tikv、tidb、volume 和 all（用于同时查询所有组件）。

参数缩写说明
--tidb-cluster-t指定 TiDB 集群，默认为当前使用的 TiDB 集群
--output-o输出格式，可选值有 default、json 和 yaml，默认值为 default

示例如下：

tkctl get tikv

NAME                  READY   STATUS    MEMORY          CPU   RESTARTS   AGE     NODE
demo-cluster-tikv-0   2/2     Running   2098Mi/4196Mi   2/2   0          3m19s   172.16.4.155
demo-cluster-tikv-1   2/2     Running   2098Mi/4196Mi   2/2   0          4m8s    172.16.4.160
demo-cluster-tikv-2   2/2     Running   2098Mi/4196Mi   2/2   0          4m45s   172.16.4.157

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]

该命令用于诊断 TiDB 集群中的 Pod。

实际使用时，该命令会在目标 Pod 的宿主机上启动 debug launcher Pod 并以指定镜像启动一个 debug 容器，该容器会与目标 Pod 中的容器共享 namespace，因此可以无缝使用 debug 容器中的各种工具对目标容器进行诊断。

参数缩写描述
--image指定 debug 容器使用的镜像，默认为 pingcap/tidb-debug:latest
--launcher-image指定启动 debug 容器的 debug launcher Pod 使用的镜像，默认为 pingcap/debug-launcher:latest
--container-c选择需要诊断的容器，默认为 Pod 定义中的第一个容器
--docker-socket指定目标节点上的 Docker Socket，默认为 /var/run/docker.sock
--privileged是否为 debug 容器开启 privileged 模式

示例如下：

tkctl debug demo-cluster-tikv-0

ps -ef

由于 debug 容器和目标容器拥有不同的根文件系统，在 tidb-debug 容器中使用 GDB 和 perf 等工具时可能会碰到一些问题，下面将补充说明如何解决这些问题。

GDB

使用 GDB 调试目标容器中的进程时，需要将 program 参数设置为目标容器中的可执行文件。假如是在 tidb-debug 以外的其它 debug 容器中进行调试，或者调试的目标进行 pid 不为 1，则需要使用 set sysroot 命令调整动态链接库的加载位置。操作如下：

tkctl debug demo-cluster-tikv-0

gdb /proc/${pid:-1}/root/tikv-server 1

tidb-debug 中预配置的 .gdbinit 会将 sysroot 设置为 /proc/1/root/，因此在 tidb-debug 中，假如目标容器的 pid 为 1，则下面的命令可以省略。

(gdb) set sysroot /proc/${pid}/root/

开始调试：

(gdb) thread apply all bt

(gdb) info threads

Perf 以及火焰图

使用 perf 命令和 run-flamegraph.sh 脚本时，需要将目标容器的可执行文件拷贝到 Debug 容器中：

tkctl debug demo-cluster-tikv-0

cp /proc/1/root/tikv-server /

./run_flamegraph.sh 1

该脚本会自动将生成的火焰图（SVG 格式）上传至 transfer.sh，通过访问脚本输出的链接即可下载火焰图。

tkctl ctop

命令的完整形式：tkctl ctop [pod_name | node/node_name ]。

该命令用于查看集群中 Pod 或 Node 的实时监控信息，和 kubectl top 相比，tkctl ctop 还会展示网络和磁盘的使用信息。

参数简写描述
--image指定 ctop 的镜像，默认为 quay.io/vektorlab/ctop:0.7.2
--docker-socket指定 ctop 使用的 Docker Socket，默认为 /var/run/docker.sock

示例如下：

tkctl ctop demo-cluster-tikv-0

tkctl ctop node/172.16.4.155

tkctl help [command]

该命令用于展示各个子命令的帮助信息。

示例如下：

tkctl help debug

tkctl options

该命令用于展示 tkctl 的所有的全局参数。

示例如下：

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

这些参数主要用于指定如何连接 Kubernetes 集群，其中最常用的参数是：

  • --context：指定目标 Kubernetes 集群
  • --namespace：指定 Namespace

文档内容是否有帮助？

下载 PDF文档反馈社区交流