Kubectl常用命令详解

要使用和维护Kubernetes集群，最常用且直接的方式，就是使用自带的命令行工具Kubectl。这里梳理下常用的子命令及参数，方便查找参考。

参考文档：

• Overview of kubectl
• kubectl.docs
• kubernetes-handbook

kubectl概述

祭出一张图，转载至kubernetes-handbook/kubectl命令概述，可以对命令族有个整体的概念。

环境准备

kubectl安装后，默认是没有比如自动补全等功能的，频繁使用比较不方便。目前已经有各类kubectl小工具可以提高效率，还有kubectl专用的shell了。个人感觉比较好用有以下这些：

• 自动补全
  kubectl 命令在bash中默认是没有自动补全的，需要安装bash_completion，添加自动补全脚本。这里以CentOS为例，其他操作系统配置可以参看Install and Set Up kubectl

# 安装bash-completion
yum install -y epel-release.noarch
yum install -y bash_completion
# 添加补全脚本
kubectl completion bash >/etc/bash_completion.d/kubectl

重新登录shell，可以发现kubectl的子命令，包括资源名称都可以用Tab键自动补全了:

• 快速切换集群和Namespace
  生产环境一般是多集群，至少也是多NS的环境，免不了经常在不同集群和不同NS间切换。切换集群要修改环境变量、切换NS要在命令跟上 -n namespace，都不是太方便。而用kubectx和kubens两个小工具可以实现快速切换。这俩在同一项目里：ahmetb/kubectx

# 安装
sudo git clone https://github.com/ahmetb/kubectx /opt/kubectx
sudo ln -s /opt/kubectx/kubectx /usr/local/bin/kubectx
sudo ln -s /opt/kubectx/kubens /usr/local/bin/kubens

# 使用kubectx
# kubectx  : 列出所有上下文
# kubectx <NAME> : 切换到某个上下文
$ kubectx minikube
Switched to context "minikube".
# kubectx -   : 切换回上一个上下文
$ kubectx -
Switched to context "oregon".
# kubectx <NEW_NAME>=<NAME> : 重命名一个集群上下文
$ kubectx dublin=gke_ahmetb_europe-west1-b_dublin
Context "dublin" set.
Aliased "gke_ahmetb_europe-west1-b_dublin" as "dublin".
# kubectx <NEW_NAME>=. : 重命名当前上下文
# kubectx -d <NAME>  : 删除上下文

# 使用kubens
# kubens : 列出所有的NS
# kubens <NS-NAME>  : 切换当前NS
$ kubens kube-system
Context "test" set.
Active namespace is "kube-system".
# kubens - : 切换回上一个NS
$ kubens -
Context "test" set.
Active namespace is "default".

关于多集群切换的配置和上下文的概念可以参看官方文档，有中文。

• kubectl shell
  kubectl已经有比较成熟的专用shell了，优化了自动补全，模糊匹配等功能：

但实际使用过程中，偶尔还是会各种小问题。推荐两个比较热门的，有需要可以尝试一下：
kube-shell
kube-prompt

常用命令详解

上面的概述图很全面，为了方便说明，这里把Kubectl常用子命令大概分为以下几类：

语法

$ kubectl [command] [TYPE] [NAME] [flags]

•  

command：子命令

TYPE：资源类型
NAME：资源名称
flags：命令参数

• 命令帮助
  kubectl命令的帮助很详细，kubectl -h会列出所有的子命令，在任何子命令后跟 -h，都会输出详细的帮助以及用例，遇到问题可以随时查看帮助。

• 资源对象
  kubectl大部分子命令后都可以指定要操作的资源对象，可以用kubectl api-resources命令参考

• 全局参数
  kubectl options命令可以列出可以全局使用的命令参数，比较重要的有：

--cluster='': 指定命令操作对象的集群
--context='':  指定命令操作对象的上下文
-n, --namespace='': 指定命令操作对象的Namespace

• 资源字段
  kubectl explain命令可以输出资源对应的属性字段及定义,在定义资源配置文件时候非常有用。

# Usage:
  kubectl explain RESOURCE [options]
# Examples: 
$ kubectl  explain deployment.spec.selector
KIND:     Deployment
VERSION:  extensions/v1beta1

RESOURCE: selector <Object>

DESCRIPTION:
     Label selector for pods. Existing ReplicaSets whose pods are selected by
     this will be the ones affected by this deployment.

     A label selector is a label query over a set of resources. The result of
     matchLabels and matchExpressions are ANDed. An empty label selector matches
     all objects. A null label selector matches no objects.

FIELDS:
   matchExpressions     <[]Object>
     matchExpressions is a list of label selector requirements. The requirements
     are ANDed.

   matchLabels  <map[string]string>
     matchLabels is a map of {key,value} pairs. A single {key,value} in the
     matchLabels map is equivalent to an element of matchExpressions, whose key
     field is "key", the operator is "In", and the values array contains only
     "value". The requirements are ANDed.

•  

声明式资源对象管理

对集群资源的声明式管理，是Kubernetes最主要的特性之一，而kubectl apply命令是最能体现这个特性的命令。apply命令最主要的参数有两个:

# Usage:
  kubectl apply (-f FILENAME | -k DIRECTORY) [options]

•  

-f 参数后跟yaml或json格式的资源配置文件，-k 参数后跟kustomization.yaml配置文件的位置。

为什么说apply是声明式管理呢，因为所有对集群的增改操作，都能用apply命令完成，一切取决于后面的配置文件：

• 如果配置文件中的资源找集群中不存在，则创建这个资源。
• 如果配置文件中的资源在集群中已存在，则根据配置对资源字段进行更新

举个例子：

# 部署一个goweb应用，配置pod数为4个：
[root@master-1 ~]# grep replicas deployment-goweb.yaml 
  replicas: 4
# 使用 apply 创建资源
[root@master-1 ~]# kubectl apply -f deployment-goweb.yaml 
deployment.apps/goweb created
[root@master-1 ~]# kubectl get po
NAME                     READY   STATUS    RESTARTS   AGE
goweb-6b5d559869-4x5mb   1/1     Running   0          14s
goweb-6b5d559869-77lbz   1/1     Running   0          14s
goweb-6b5d559869-9ztkh   1/1     Running   0          14s
goweb-6b5d559869-ccjtp   1/1     Running   0          14s

# 修改pod数量为2个：
[root@master-1 ~]# sed -ri 's/4$/2/g' deployment-goweb.yaml
[root@master-1 ~]# grep replicas deployment-goweb.yaml       
  replicas: 2

# 使用apply更新资源
[root@master-1 ~]# kubectl  apply  -f deployment-goweb.yaml 
deployment.apps/goweb configured
[root@master-1 ~]# kubectl get po
NAME                     READY   STATUS    RESTARTS   AGE
goweb-6b5d559869-4x5mb   1/1     Running   0          8m21s
goweb-6b5d559869-77lbz   1/1     Running   0          8m21s

# pod数已更新为2个

•  

可以看到，同一个kubectl apply -f deployment-goweb.yaml命令，可以用来创建资源也可以更新资源。
简单来说，apply命令的作用就是一个：使集群的实际状态朝用户声明的期望状态变化，而用户不用关心具体要进行怎样的增删改操作才能呢达到这个期望状态，也即Kubernetes的声明式资源管理。

命令式资源对象管理

命令式管理类就是直接通过命令执行增删改的操作，除了删除资源外，下面的命令能用apply代替，kubernetes也建议尽量使用apply命令。

• 创建资源

kubectl create deployment my-dep --image=busybox        # 创建一个deplpyme
kubectl expose rc nginx --port=80 --target-port=8000    # 创建一个svc，暴露nginx这个rc

• 更新资源

kubectl scale --replicas=3 -f foo.yaml                     # 将foo.yaml中描述的对象扩展为3个
kubectl annotate pods foo description='my frontend'        # 增加description='my frontend'备注,已有保留不覆盖
kubectl label --overwrite pods foo status=unhealthy        # 增加status=unhealthy 标签，已有则覆盖

• 删除资源

kubectl delete -f xxx.yaml                      # 删除一个配置文件对应的资源对象  
kubectl delete pod,service baz foo              # 删除名字为baz或foo的pod和service  
kubectl delete pods,services -l name=myLabel    # -l 参数可以删除包含指定label的资源对象                            
kubectl delete pod foo --grace-period=0 --force # 强制删除一个pod，在各种原因pod一直terminate不掉的时候很有用

•  

查看资源状态

• get
  最常用的查看命令，显示一个或多个资源的详细信息

# Usage:
  kubectl get
[(-o|--output=)](TYPE[.VERSION][.GROUP] [NAME | -l label] | TYPE[.VERSION][.GROUP]/NAME ...) [flags] 
[options]
# Examples: 
kubectl get services                          # 列出当前NS中所有service资源
kubectl get pods --all-namespaces             # 列出集群所有NS中所有的Pod
kubectl get pods -o wide                      # -o wide也比较常用，可以显示更多资源信息，比如pod的IP等
kubectl get deployment my-dep                 # 可以直接指定资源名查看
kubectl get deployment my-dep --watch         # --watch 参数可以监控资源的状态，在状态变换时输出。在跟踪服务部署情况时很有用
kubectl get pod my-pod -o yaml                # 查看yaml格式的资源配置，这里包括资实际的status，可以用--export排除
kubectl get pod my-pod -l app=nginx           # 查看所有带有标签app: nginx的pod

•  

kubectl 可用JSONPATH来过滤字段，JSON Path的语法可参考这里

kubectl get pods --selector=app=cassandra rc -o jsonpath='{.items[*].metadata.labels.version}' # 获取所有具有 app=cassandra 的 pod 中的 version 标签

•  

• describe
  describe命令同样用于查看资源信息，但相比与get只输出资源本身的信息，describe聚合了相关资源的信息并输出。比如，在describe node信息时，同时会输出该node下的pod的资源利用情况。所以describe命令在排错和调试时非常有用。

# Usage:
kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | -l label] | TYPE/NAME) [options]
# Examples: 
kubectl describe nodes my-node    # 查看节点my-node的详细信息
kubectl describe pods my-pod      # 查看pod my-pod的详细信息

•  

容器管理

虽然逻辑上，Kubernetes的最小管理单位是Pod，但是实际上还是免不了与容器直接交互，特别是对于多容器的Pod，任意容器有问题，都会导致Pod不可用。

• 日志查看

# Usage:
  kubectl logs [-f] [-p] (POD | TYPE/NAME) [-c CONTAINER] [options]
# Examples: 
kubectl logs my-pod                              
# 输出一个单容器pod my-pod的日志到标准输出
kubectl logs nginx-78f5d695bd-czm8z -c nginx     
# 输出多容器pod中的某个nginx容器的日志
kubectl logs -l app=nginx                        
# 输出所有包含app-nginx标签的pod日志
kubectl logs -f my-pod                           
# 加上-f参数跟踪日志，类似tail -f
kubectl logs my-pod  -p                          
# 输出该pod的上一个退出的容器实例日志。在pod容器异常退出时很有用
kubectl logs my-pod  --since-time=2018-11-01T15:00:00Z
# 指定时间戳输出日志            
kubectl logs my-pod  --since=1h 
# 指定时间段输出日志，单位s/m/h

• 执行命令

• 命令作用和参数基本与docker exec一致

# Usage:
kubectl exec POD [-c CONTAINER] -- COMMAND [args...] [options]
# Examples:
kubectl exec my-pod ls                         # 对my-pod执行ls命令
kubectl exec -t -i nginx-78f5d695bd-czm8z bash # 进入pod的shell，并打开伪终端和标准输入

• 文件传输
• 在排错和测试服务的时候，时不时需要和容器互相交互文件，比如传输容器内存的dump到宿主机，或从宿主机临时拷贝个新配置文件做调试，这时就可以用*kubectl cp命令。要注意的是，cp命令需要容器里已安装有tar程序

# Usage:
kubectl cp <file-spec-src> <file-spec-dest> [options]
# Examples:  
kubectl cp /tmp/foo_dir <some-pod>:/tmp/bar_dir                 # 拷贝宿主机本地文件夹到pod
kubectl cp <some-namespace>/<some-pod>:/tmp/foo /tmp/bar        # 指定namespace的拷贝pod文件到宿主机本地目录
kubectl cp /tmp/foo <some-pod>:/tmp/bar -c <specific-container> # 对于多容器pod，用-c指定容器名

•  

集群管理

除了和具体的资源打交道，在对集群进行维护时，也经常需要查看集群信息和对节点进行管理，集群管理有以下这些常用的命令：

• 集群信息查看

 kubectl cluster-info      # 查看master和集群服务的地址
 kubectl cluster-info dump # 查看集群详细日志
 kubectl version           # 查看Kubernetes集群和客户端版本

•  

• 节点管理
  在集群节点出问题时，可能希望把一个节点不再被调度pod，或把节点目前的pod都驱逐出去

kubectl cordon my-node       
# 标记 my-node 为 unschedulable,禁止pod被调度过来。注意这时现有的pod还会继续运行，不会被驱逐。
kubectl uncordon my-node 
# 与cordon相反，标记 my-node 为 允许调度。
kubectl drain  my-node
# drain字面意思为排水，实际就是把my-node的pod平滑切换到其他node，同时标记pod为unschedulable，也就是包含了cordon命令。
# 但是直接使用命令一般不会成功，建议在要维护节点时，加上以下参数：
kubectl drain my-node  --ignore-daemonsets  --force  --delete-local-data  
# --ignore-daemonsets 忽略daemonset部署的pod
# --force 直接删除不由workload对象（Deployment、Job等）管理的pod
# --delete-local-data  直接删除挂载有本地目录(empty-dir方式）的pod