tkctl 使用指南

tkctl (TiDB Kubernetes Control) 是为 TiDB in 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) 有: pdtikvtidbvolumeall(用于同时查询所有组件)。

参数缩写说明
--tidb-cluster-t指定 TiDB 集群,默认为当前使用的 TiDB 集群
--output-o输出格式,可选值有 defaultjsonyaml,默认值为 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