kubectl 快速参考
本页列举常用的 kubectl
命令和参数。
说明:
这些指令适用于 Kubernetes v1.31。要检查版本,请使用 kubectl version
命令。
kubectl 自动补全
BASH
source <(kubectl completion bash) # 在 bash 中设置当前 shell 的自动补全,要先安装 bash-completion 包
echo "source <(kubectl completion bash)" >> ~/.bashrc # 在你的 bash shell 中永久地添加自动补全
你还可以在补全时为 kubectl
使用一个速记别名:
alias k=kubectl
complete -o default -F __start_kubectl k
ZSH
source <(kubectl completion zsh) # 在 zsh 中设置当前 shell 的自动补全
echo '[[ $commands[kubectl] ]] && source <(kubectl completion zsh)' >> ~/.zshrc # 在你的 zsh shell 中永久地添加自动补全
FISH
说明:
需要 kubectl 版本 1.23 或更高版本。
echo 'kubectl completion fish | source' > ~/.config/fish/completions/kubectl.fish && source ~/.config/fish/completions/kubectl.fish
关于 --all-namespaces
的一点说明
我们经常用到 --all-namespaces
参数,你应该要知道它的简写:
kubectl -A
kubectl 上下文和配置
设置 kubectl
与哪个 Kubernetes 集群进行通信并修改配置信息。 查看使用 kubeconfig 跨集群授权访问 文档获取配置文件详细信息。
kubectl config view # 显示合并的 kubeconfig 配置
# 同时使用多个 kubeconfig 文件并查看合并的配置
KUBECONFIG=~/.kube/config:~/.kube/kubconfig2
kubectl config view
# 显示合并的 kubeconfig 配置和原始证书数据以及公开的 Secret
kubectl config view --raw
# 获取 e2e 用户的密码
kubectl config view -o jsonpath='{.users[?(@.name == "e2e")].user.password}'
# 获取 e2e 用户的证书
kubectl config view --raw -o jsonpath='{.users[?(.name == "e2e")].user.client-certificate-data}' | base64 -d
kubectl config view -o jsonpath='{.users[].name}' # 显示第一个用户
kubectl config view -o jsonpath='{.users[*].name}' # 获取用户列表
kubectl config get-contexts # 显示上下文列表
kubectl config get-contexts -o name # 获取所有上下文的名称
kubectl config current-context # 展示当前所处的上下文
kubectl config use-context my-cluster-name # 设置默认的上下文为 my-cluster-name
kubectl config set-cluster my-cluster-name # 在 kubeconfig 中设置集群条目
# 在 kubeconfig 中配置代理服务器的 URL,以用于该客户端的请求
kubectl config set-cluster my-cluster-name --proxy-url=my-proxy-url
# 添加新的用户配置到 kubeconf 中,使用 basic auth 进行身份认证
kubectl config set-credentials kubeuser/foo.kubernetes.com --username=kubeuser --password=kubepassword
# 在指定上下文中持久性地保存名字空间,供所有后续 kubectl 命令使用
kubectl config set-context --current --namespace=ggckad-s2
# 使用特定的用户名和名字空间设置上下文
kubectl config set-context gce --user=cluster-admin --namespace=foo \
&& kubectl config use-context gce
kubectl config unset users.foo # 删除用户 foo
# 设置或显示 context / namespace 的短别名
# (仅适用于 bash 和 bash 兼容的 shell,在使用 kn 设置命名空间之前要先设置 current-context)
alias kx='f() { [ "$1" ] && kubectl config use-context $1 || kubectl config current-context ; } ; f'
alias kn='f() { [ "$1" ] && kubectl config set-context --current --namespace $1 || kubectl config view --minify | grep namespace | cut -d" " -f6 ; } ; f'
kubectl apply
apply
通过定义 Kubernetes 资源的文件来管理应用。 它通过运行 kubectl apply
在集群中创建和更新资源。 这是在生产中管理 Kubernetes 应用的推荐方法。 参见 kubectl 文档。
创建对象
Kubernetes 配置可以用 YAML 或 JSON 定义。可以使用的文件扩展名有 .yaml
、.yml
和 .json
。
kubectl apply -f ./my-manifest.yaml # 创建资源
kubectl apply -f ./my1.yaml -f ./my2.yaml # 使用多个文件创建
kubectl apply -f ./dir # 基于目录下的所有清单文件创建资源
kubectl apply -f https://example.com/manifest.yaml # 从 URL 中创建资源(注意:这是一个示例域名,不包含有效的清单)
kubectl create deployment nginx --image=nginx # 启动单实例 nginx
# 创建一个打印 “Hello World” 的 Job
kubectl create job hello --image=busybox:1.28 -- echo "Hello World"
# 创建一个打印 “Hello World” 间隔 1 分钟的 CronJob
kubectl create cronjob hello --image=busybox:1.28 --schedule="*/1 * * * *" -- echo "Hello World"
kubectl explain pods # 获取 Pod 清单的文档说明
# 从标准输入创建多个 YAML 对象
kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
name: busybox-sleep
spec:
containers:
- name: busybox
image: busybox:1.28
args:
- sleep
- "1000000"
---
apiVersion: v1
kind: Pod
metadata:
name: busybox-sleep-less
spec:
containers:
- name: busybox
image: busybox:1.28
args:
- sleep
- "1000"
EOF
# 创建有多个 key 的 Secret
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
name: mysecret
type: Opaque
data:
password: $(echo -n "s33msi4" | base64 -w0)
username: $(echo -n "jane" | base64 -w0)
EOF
查看和查找资源
# get 命令的基本输出
kubectl get services # 列出当前命名空间下的所有 Service
kubectl get pods --all-namespaces # 列出所有命名空间下的全部的 Pod
kubectl get pods -o wide # 列出当前命名空间下的全部 Pod 并显示更详细的信息
kubectl get deployment my-dep # 列出某个特定的 Deployment
kubectl get pods # 列出当前命名空间下的全部 Pod
kubectl get pod my-pod -o yaml # 获取一个 Pod 的 YAML
# describe 命令的详细输出
kubectl describe nodes my-node
kubectl describe pods my-pod
# 列出当前名字空间下所有 Service,按名称排序
kubectl get services --sort-by=.metadata.name
# 列出 Pod,按重启次数排序
kubectl get pods --sort-by='.status.containerStatuses[0].restartCount'
# 列举所有 PV 持久卷,按容量排序
kubectl get pv --sort-by=.spec.capacity.storage
# 获取包含 app=cassandra 标签的所有 Pod 的 version 标签
kubectl get pods --selector=app=cassandra -o \
jsonpath='{.items[*].metadata.labels.version}'
# 检索带有 “.” 键值,例如 'ca.crt'
kubectl get configmap myconfig \
-o jsonpath='{.data.ca\.crt}'
# 检索一个 base64 编码的值,其中的键名应该包含减号而不是下划线
kubectl get secret my-secret --template='{{index .data "key-name-with-dashes"}}'
# 获取所有工作节点(使用选择算符以排除标签名称为 'node-role.kubernetes.io/control-plane' 的结果)
kubectl get node --selector='!node-role.kubernetes.io/control-plane'
# 获取当前命名空间中正在运行的 Pod
kubectl get pods --field-selector=status.phase=Running
# 获取全部节点的 ExternalIP 地址
kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="ExternalIP")].address}'
# 列出属于某个特定 RC 的 Pod 的名称
# 在转换对于 jsonpath 过于复杂的场合,"jq" 命令很有用;可以在 https://jqlang.github.io/jq/ 找到它
sel=${$(kubectl get rc my-rc --output=json | jq -j '.spec.selector | to_entries | .[] | "\(.key)=\(.value),"')%?}
echo $(kubectl get pods --selector=$sel --output=jsonpath={.items..metadata.name})
# 显示所有 Pod 的标签(或任何其他支持标签的 Kubernetes 对象)
kubectl get pods --show-labels
# 检查哪些节点处于就绪状态
JSONPATH='{range .items[*]}{@.metadata.name}:{range @.status.conditions[*]}{@.type}={@.status};{end}{end}' \
&& kubectl get nodes -o jsonpath="$JSONPATH" | grep "Ready=True"
# 使用自定义列检查哪些节点处于就绪状态
kubectl get node -o custom-columns='NODE_NAME:.metadata.name,STATUS:.status.conditions[?(@.type=="Ready")].status'
# 不使用外部工具来输出解码后的 Secret
kubectl get secret my-secret -o go-template='{{range $k,$v := .data}}{{"### "}}{{$k}}{{"\n"}}{{$v|base64decode}}{{"\n\n"}}{{end}}'
# 列出被一个 Pod 使用的全部 Secret
kubectl get pods -o json | jq '.items[].spec.containers[].env[]?.valueFrom.secretKeyRef.name' | grep -v null | sort | uniq
# 列举所有 Pod 中初始化容器的容器 ID(containerID)
# 可用于在清理已停止的容器时避免删除初始化容器
kubectl get pods --all-namespaces -o jsonpath='{range .items[*].status.initContainerStatuses[*]}{.containerID}{"\n"}{end}' | cut -d/ -f3
# 列出事件(Event),按时间戳排序
kubectl get events --sort-by=.metadata.creationTimestamp
# 列出所有警告事件
kubectl events --types=Warning
# 比较当前的集群状态和假定某清单被应用之后的集群状态
kubectl diff -f ./my-manifest.yaml
# 生成一个句点分隔的树,其中包含为节点返回的所有键
# 在复杂的嵌套JSON结构中定位键时非常有用
kubectl get nodes -o json | jq -c 'paths|join(".")'
# 生成一个句点分隔的树,其中包含为 Pod 等返回的所有键
kubectl get pods -o json | jq -c 'paths|join(".")'
# 假设你的 Pod 有默认的容器和默认的名字空间,并且支持 'env' 命令,可以使用以下脚本为所有 Pod 生成 ENV 变量。
# 该脚本也可用于在所有的 Pod 里运行任何受支持的命令,而不仅仅是 'env'。
for pod in $(kubectl get po --output=jsonpath={.items..metadata.name}); do echo $pod && kubectl exec -it $pod -- env; done
# 获取一个 Deployment 的 status 子资源
kubectl get deployment nginx-deployment --subresource=status
更新资源
kubectl set image deployment/frontend www=image:v2 # 滚动更新 "frontend" Deployment 的 "www" 容器镜像
kubectl rollout history deployment/frontend # 检查 Deployment 的历史记录,包括版本
kubectl rollout undo deployment/frontend # 回滚到上次部署版本
kubectl rollout undo deployment/frontend --to-revision=2 # 回滚到特定部署版本
kubectl rollout status -w deployment/frontend # 监视 "frontend" Deployment 的滚动升级状态直到完成
kubectl rollout restart deployment/frontend # 轮替重启 "frontend" Deployment
cat pod.json | kubectl replace -f - # 通过传入到标准输入的 JSON 来替换 Pod
# 强制替换,删除后重建资源。会导致服务不可用。
kubectl replace --force -f ./pod.json
# 为多副本的 nginx 创建服务,使用 80 端口提供服务,连接到容器的 8000 端口
kubectl expose rc nginx --port=80 --target-port=8000
# 将某单容器 Pod 的镜像版本(标签)更新到 v4
kubectl get pod mypod -o yaml | sed 's/\(image: myimage\):.*$/\1:v4/' | kubectl replace -f -
kubectl label pods my-pod new-label=awesome # 添加标签
kubectl label pods my-pod new-label- # 移除标签
kubectl label pods my-pod new-label=new-value --overwrite # 覆盖现有的值
kubectl annotate pods my-pod icon-url=http://goo.gl/XXBTWq # 添加注解
kubectl annotate pods my-pod icon-url- # 移除注解
kubectl autoscale deployment foo --min=2 --max=10 # 对 "foo" Deployment 自动扩缩容
部分更新资源
# 部分更新某节点
kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}'
# 更新容器的镜像;spec.containers[*].name 是必需的。因为它是一个合并性质的主键。
kubectl patch pod valid-pod -p '{"spec":{"containers":[{"name":"kubernetes-serve-hostname","image":"new image"}]}}'
# 使用带位置数组的 JSON patch 更新容器的镜像
kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/containers/0/image", "value":"new image"}]'
# 使用带位置数组的 JSON patch 禁用某 Deployment 的 livenessProbe
kubectl patch deployment valid-deployment --type json -p='[{"op": "remove", "path": "/spec/template/spec/containers/0/livenessProbe"}]'
# 在带位置数组中添加元素
kubectl patch sa default --type='json' -p='[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]'
# 通过修正 scale 子资源来更新 Deployment 的副本数
kubectl patch deployment nginx-deployment --subresource='scale' --type='merge' -p '{"spec":{"replicas":2}}'
编辑资源
使用你偏爱的编辑器编辑 API 资源。
kubectl edit svc/docker-registry # 编辑名为 docker-registry 的服务
KUBE_EDITOR="nano" kubectl edit svc/docker-registry # 使用其他编辑器
对资源进行扩缩
kubectl scale --replicas=3 rs/foo # 将名为 'foo' 的副本集扩缩到 3 副本
kubectl scale --replicas=3 -f foo.yaml # 将在 "foo.yaml" 中的特定资源扩缩到 3 个副本
kubectl scale --current-replicas=2 --replicas=3 deployment/mysql # 如果名为 mysql 的 Deployment 的副本当前是 2,那么将它扩缩到 3
kubectl scale --replicas=5 rc/foo rc/bar rc/baz # 扩缩多个副本控制器
删除资源
kubectl delete -f ./pod.json # 删除在 pod.json 中指定的类型和名称的 Pod
kubectl delete pod unwanted --now # 删除 Pod 且无宽限期限(无优雅时段)
kubectl delete pod,service baz foo # 删除名称为 "baz" 和 "foo" 的 Pod 和服务
kubectl delete pods,services -l name=myLabel # 删除包含 name=myLabel 标签的 Pod 和服务
kubectl -n my-ns delete pod,svc --all # 删除在 my-ns 名字空间中全部的 Pod 和服务
# 删除所有与 pattern1 或 pattern2 awk 模式匹配的 Pod
kubectl get pods -n mynamespace --no-headers=true | awk '/pattern1|pattern2/{print $1}' | xargs kubectl delete -n mynamespace pod
与运行中的 Pod 进行交互
kubectl logs my-pod # 获取 Pod 日志(标准输出)
kubectl logs -l name=myLabel # 获取含 name=myLabel 标签的 Pod 的日志(标准输出)
kubectl logs my-pod --previous # 获取上个容器实例的 Pod 日志(标准输出)
kubectl logs my-pod -c my-container # 获取 Pod 容器的日志(标准输出, 多容器场景)
kubectl logs -l name=myLabel -c my-container # 获取含 name=myLabel 标签的 Pod 容器日志(标准输出, 多容器场景)
kubectl logs my-pod -c my-container --previous # 获取 Pod 中某容器的上个实例的日志(标准输出, 多容器场景)
kubectl logs -f my-pod # 流式输出 Pod 的日志(标准输出)
kubectl logs -f my-pod -c my-container # 流式输出 Pod 容器的日志(标准输出, 多容器场景)
kubectl logs -f -l name=myLabel --all-containers # 流式输出含 name=myLabel 标签的 Pod 的所有日志(标准输出)
kubectl run -i --tty busybox --image=busybox:1.28 -- sh # 以交互式 Shell 运行 Pod
kubectl run nginx --image=nginx -n mynamespace # 在 “mynamespace” 命名空间中运行单个 nginx Pod
kubectl run nginx --image=nginx --dry-run=client -o yaml > pod.yaml
# 为运行 nginx Pod 生成规约并将其写入到名为 pod.yaml 的文件
kubectl attach my-pod -i # 挂接到一个运行的容器中
kubectl port-forward my-pod 5000:6000 # 在本地计算机上侦听端口 5000 并转发到 my-pod 上的端口 6000
kubectl exec my-pod -- ls / # 在已有的 Pod 中运行命令(单容器场景)
kubectl exec --stdin --tty my-pod -- /bin/sh # 使用交互 shell 访问正在运行的 Pod (一个容器场景)
kubectl exec my-pod -c my-container -- ls / # 在已有的 Pod 中运行命令(多容器场景)
kubectl debug my-pod -it --image=busybox:1.28 # 在现有 Pod 中创建交互式调试会话并立即附加到此 Pod 上
kubectl debug node/my-node -it --image=busybox:1.28 # 在节点上创建交互式调试会话并立即附加到此节点上
kubectl top pod # 显示默认命名空间中所有 Pod 的度量值
kubectl top pod POD_NAME --containers # 显示给定 Pod 和其中容器的度量值
kubectl top pod POD_NAME --sort-by=cpu # 显示给定 Pod 的指标并且按照 'cpu' 或者 'memory' 排序
从容器中复制文件和目录
kubectl cp /tmp/foo_dir my-pod:/tmp/bar_dir # 将 /tmp/foo_dir 本地目录复制到远程当前命名空间中 Pod 中的 /tmp/bar_dir
kubectl cp /tmp/foo my-pod:/tmp/bar -c my-container # 将 /tmp/foo 本地文件复制到远程 Pod 中特定容器的 /tmp/bar 下
kubectl cp /tmp/foo my-namespace/my-pod:/tmp/bar # 将 /tmp/foo 本地文件复制到远程 “my-namespace” 命名空间内指定 Pod 中的 /tmp/bar
kubectl cp my-namespace/my-pod:/tmp/foo /tmp/bar # 将 /tmp/foo 从远程 Pod 复制到本地 /tmp/bar
说明:
kubectl cp
要求容器镜像中存在 “tar” 二进制文件。如果 “tar” 不存在,kubectl cp
将失败。 对于进阶用例,例如符号链接、通配符扩展或保留文件权限,请考虑使用 kubectl exec
。
tar cf - /tmp/foo | kubectl exec -i -n my-namespace my-pod -- tar xf - -C /tmp/bar # 将 /tmp/foo 本地文件复制到远程 “my-namespace” 命名空间中 Pod 中的 /tmp/bar
kubectl exec -n my-namespace my-pod -- tar cf - /tmp/foo | tar xf - -C /tmp/bar # 将 /tmp/foo 从远程 Pod 复制到本地 /tmp/bar
与 Deployments 和 Services 进行交互
kubectl logs deploy/my-deployment # 获取一个 Deployment 的 Pod 的日志(单容器例子)
kubectl logs deploy/my-deployment -c my-container # 获取一个 Deployment 的 Pod 的日志(多容器例子)
kubectl port-forward svc/my-service 5000 # 侦听本地端口 5000 并转发到 Service 后端端口 5000
kubectl port-forward svc/my-service 5000:my-service-port # 侦听本地端口 5000 并转发到名字为 <my-service-port> 的 Service 目标端口
kubectl port-forward deploy/my-deployment 5000:6000 # 侦听本地端口 5000 并转发到 <my-deployment> 创建的 Pod 里的端口 6000
kubectl exec deploy/my-deployment -- ls # 在 Deployment 里的第一个 Pod 的第一个容器里运行命令(单容器和多容器例子)
与节点和集群进行交互
kubectl cordon my-node # 标记 my-node 节点为不可调度
kubectl drain my-node # 对 my-node 节点进行清空操作,为节点维护做准备
kubectl uncordon my-node # 标记 my-node 节点为可以调度
kubectl top node # 显示所有节点的度量值
kubectl top node my-node # 显示给定节点的度量值
kubectl cluster-info # 显示主控节点和服务的地址
kubectl cluster-info dump # 将当前集群状态转储到标准输出
kubectl cluster-info dump --output-directory=/path/to/cluster-state # 将当前集群状态输出到 /path/to/cluster-state
# 查看当前节点上存在的现有污点
kubectl get nodes -o='custom-columns=NodeName:.metadata.name,TaintKey:.spec.taints[*].key,TaintValue:.spec.taints[*].value,TaintEffect:.spec.taints[*].effect'
# 如果已存在具有指定键和效果的污点,则替换其值为指定值
kubectl taint nodes foo dedicated=special-user:NoSchedule
资源类型
列出所支持的全部资源类型和它们的简称、 API 组、 是否是名字空间作用域和 Kind。
kubectl api-resources
用于探索 API 资源的其他操作:
kubectl api-resources --namespaced=true # 所有命名空间作用域的资源
kubectl api-resources --namespaced=false # 所有非命名空间作用域的资源
kubectl api-resources -o name # 用简单格式列举所有资源(仅显示资源名称)
kubectl api-resources -o wide # 用扩展格式列举所有资源(又称 "wide" 格式)
kubectl api-resources --verbs=list,get # 支持 "list" 和 "get" 请求动词的所有资源
kubectl api-resources --api-group=extensions # "extensions" API 组中的所有资源
格式化输出
要以特定格式将详细信息输出到终端窗口,将 -o
(或者 --output
)参数添加到支持的 kubectl
命令中。
输出格式 | 描述 |
---|---|
-o=custom-columns=<spec> | 使用逗号分隔的自定义列来打印表格 |
-o=custom-columns-file=<filename> | 使用 <filename> 文件中的自定义列模板打印表格 |
-o=go-template=<template> | 打印在 golang 模板中定义的字段 |
-o=go-template-file=<filename> | 打印在 <filename> 文件中由 golang 模板定义的字段 |
-o=json | 输出 JSON 格式的 API 对象 |
-o=jsonpath=<template> | 打印 jsonpath 表达式中定义的字段 |
-o=jsonpath-file=<filename> | 打印在 <filename> 文件中定义的 jsonpath 表达式所指定的字段 |
-o=name | 仅打印资源名称而不打印其他内容 |
-o=wide | 以纯文本格式输出额外信息,对于 Pod 来说,输出中包含了节点名称 |
-o=yaml | 输出 YAML 格式的 API 对象 |
使用 -o=custom-columns
的示例:
# 集群中运行着的所有镜像
kubectl get pods -A -o=custom-columns='DATA:spec.containers[*].image'
# 列举 default 名字空间中运行的所有镜像,按 Pod 分组
kubectl get pods --namespace default --output=custom-columns="NAME:.metadata.name,IMAGE:.spec.containers[*].image"
# 除 "registry.k8s.io/coredns:1.6.2" 之外的所有镜像
kubectl get pods -A -o=custom-columns='DATA:spec.containers[?(@.image!="registry.k8s.io/coredns:1.6.2")].image'
# 输出 metadata 下面的所有字段,无论 Pod 名字为何
kubectl get pods -A -o=custom-columns='DATA:metadata.*'
有关更多示例,请参看 kubectl 参考文档。
kubectl 日志输出详细程度和调试
kubectl 日志输出详细程度是通过 -v
或者 --v
来控制的,参数后跟一个数字表示日志的级别。 Kubernetes 通用的日志习惯和相关的日志级别在 这里有相应的描述。
详细程度 | 描述 |
---|---|
—v=0 | 用于那些应该 始终 对运维人员可见的信息,因为这些信息一般很有用。 |
—v=1 | 如果你不想要看到冗余信息,此值是一个合理的默认日志级别。 |
—v=2 | 输出有关服务的稳定状态的信息以及重要的日志消息,这些信息可能与系统中的重大变化有关。这是建议大多数系统设置的默认日志级别。 |
—v=3 | 包含有关系统状态变化的扩展信息。 |
—v=4 | 包含调试级别的冗余信息。 |
—v=5 | 跟踪级别的详细程度。 |
—v=6 | 显示所请求的资源。 |
—v=7 | 显示 HTTP 请求头。 |
—v=8 | 显示 HTTP 请求内容。 |
—v=9 | 显示 HTTP 请求内容而且不截断内容。 |
接下来
- 参阅 kubectl 概述,进一步了解 JsonPath。
- 参阅 kubectl 选项。
- 参阅 kubectl 使用约定来理解如何在可复用的脚本中使用它。
- 查看社区中其他的 kubectl 备忘单。