Kubernetes 提供了一个命令行工具,用于通过 Kubernetes API 与 Kubernetes 集群的 控制平面 进行通信。
该工具名为 kubectl。
为了进行配置,kubectl 会在 $HOME/.kube 目录下查找名为 config 的文件。你可以通过设置 KUBECONFIG 环境变量或设置 --kubeconfig 标志来指定其他 kubeconfig 文件。
本概述涵盖了 kubectl 的语法,描述了命令操作,并提供了常见的示例。关于每个命令的详细信息(包括所有支持的标志和子命令),请参阅 kubectl 参考文档。
有关概述,请参阅 kubectl 命令行工具。有关安装说明,请参阅 安装 kubectl;快速指南请参考 速查表。如果你习惯使用 docker 命令行工具,Docker 用户使用 kubectl 解释了一些 Kubernetes 的等效命令。
使用以下语法从终端窗口运行 kubectl 命令:
kubectl [command] [TYPE] [NAME] [flags]
其中 command、TYPE、NAME 和 flags 分别表示:
command:指定要对一个或多个资源执行的操作,例如 create、get、describe、delete。
TYPE:指定 资源类型。资源类型不区分大小写,你可以指定单数、复数或缩写形式。例如,以下命令产生的输出相同:
kubectl get pod pod1
kubectl get pods pod1
kubectl get po pod1
NAME:指定资源的名称。名称区分大小写。如果省略名称,则显示所有资源的详细信息,例如 kubectl get pods。
在对多个资源执行操作时,你可以按类型和名称指定每个资源,或者指定一个或多个文件:
按类型和名称指定资源:
如果资源类型相同,可将其分组:TYPE1 name1 name2 name<#>。
示例:kubectl get pod example-pod1 example-pod2
分别指定多种资源类型:TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>。
示例:kubectl get pod/example-pod1 replicationcontroller/example-rc1
使用一个或多个文件指定资源:-f file1 -f file2 -f file<#>
kubectl get -f ./pod.yamlflags:指定可选标志。例如,你可以使用 -s 或 --server 标志来指定 Kubernetes API 服务器的地址和端口。
如果需要帮助,请在终端窗口运行 kubectl help。
默认情况下,kubectl 会首先判断它是否在 Pod 中运行(即在集群内)。它首先检查 KUBERNETES_SERVICE_HOST 和 KUBERNETES_SERVICE_PORT 环境变量,以及 /var/run/secrets/kubernetes.io/serviceaccount/token 处是否存在服务账号令牌文件。如果三者皆存在,则假定使用集群内认证。
为了保持向后兼容性,如果在集群内认证期间设置了 POD_NAMESPACE 环境变量,它将覆盖服务账号令牌中的默认命名空间。任何依赖命名空间默认值的清单或工具都将受到影响。
POD_NAMESPACE 环境变量
如果设置了 POD_NAMESPACE 环境变量,对命名空间范围内的资源执行的 CLI 操作将默认使用该变量的值。例如,如果变量设置为 seattle,kubectl get pods 将返回 seattle 命名空间中的 Pod。这是因为 Pod 是命名空间范围内的资源,且命令中未提供命名空间。请查看 kubectl api-resources 的输出,以确定资源是否属于命名空间范围。
显式使用 --namespace <value> 可以覆盖此行为。
kubectl 如何处理 ServiceAccount 令牌
如果:
/var/run/secrets/kubernetes.io/serviceaccount/token 处的 Kubernetes 服务账号令牌文件,且KUBERNETES_SERVICE_HOST 环境变量,且KUBERNETES_SERVICE_PORT 环境变量,且那么 kubectl 会假定它在你的集群中运行。kubectl 工具会查找该 ServiceAccount 的命名空间(与 Pod 的命名空间相同)并针对该命名空间采取行动。这与集群外发生的情况不同;当 kubectl 在集群外运行且你未指定命名空间时,kubectl 命令会针对客户端配置中当前上下文设置的命名空间采取行动。要更改 kubectl 的默认命名空间,可以使用以下命令:
kubectl config set-context --current --namespace=<namespace-name>
下表包含所有 kubectl 操作的简要说明和一般语法:
| 操作 | 语法 | 描述 |
|---|---|---|
alpha | kubectl alpha SUBCOMMAND [flags] | 列出对应 alpha 特性的可用命令(这些特性在 Kubernetes 集群中默认未启用)。 |
annotate | kubectl annotate (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags] | 为一个或多个资源添加或更新注解。 |
api-resources | kubectl api-resources [flags] | 列出可用的 API 资源。 |
api-versions | kubectl api-versions [flags] | 列出可用的 API 版本。 |
apply | kubectl apply -f FILENAME [flags] | 从文件或标准输入(stdin)将配置更改应用于资源。 |
attach | kubectl attach POD -c CONTAINER [-i] [-t] [flags] | 连接到运行中的容器,以查看输出流或与容器交互(stdin)。 |
auth | kubectl auth [flags] [options] | 检查授权。 |
autoscale | kubectl autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MAXPODS [--cpu=CPU] [flags] | 自动扩缩由复制控制器(replication controller)管理的 Pod 集合。 |
certificate | kubectl certificate SUBCOMMAND [options] | 修改证书资源。 |
cluster-info | kubectl cluster-info [flags] | 显示有关集群中主节点(master)和服务的信息。 |
completion | kubectl completion SHELL [options] | 输出指定 Shell(bash 或 zsh)的 Shell 自动补全代码。 |
config | kubectl config SUBCOMMAND [flags] | 修改 kubeconfig 文件。有关详细信息,请参阅各个子命令。 |
convert | kubectl convert -f FILENAME [options] | 在不同 API 版本之间转换配置文件。接受 YAML 和 JSON 格式。注意:需要安装 kubectl-convert 插件。 |
cordon | kubectl cordon NODE [options] | 将节点标记为不可调度。 |
cp | kubectl cp <file-spec-src> <file-spec-dest> [options] | 将文件和目录复制到容器和从容器复制。 |
create | kubectl create -f FILENAME [flags] | 从文件或标准输入创建一种或多种资源。 |
delete | kubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags] | 通过文件、标准输入或指定标签选择器、名称、资源选择器或资源来删除资源。 |
describe | kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags] | 显示一种或多种资源的详细状态。 |
diff | kubectl diff -f FILENAME [flags] | 比较文件或标准输入与当前活动配置之间的差异。 |
drain | kubectl drain NODE [options] | 为维护做准备,清空节点。 |
编辑 | kubectl edit (-f FILENAME | TYPE NAME | TYPE/NAME) [flags] | 使用默认编辑器在服务器上编辑并更新一种或多种资源的定义。 |
events | kubectl events | 列出事件。 |
exec | kubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]] | 在 Pod 中的容器上执行命令。 |
explain | kubectl explain TYPE [--recursive=false] [flags] | 获取各种资源的文档(例如 pods、nodes、services 等)。 |
expose | kubectl expose (-f FILENAME | TYPE NAME | TYPE/NAME) [--port=port] [--protocol=TCP|UDP] [--target-port=number-or-name] [--name=name] [--external-ip=external-ip-of-service] [--type=type] [flags] | 将复制控制器、服务或 Pod 公开为新的 Kubernetes 服务。 |
get | kubectl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags] | 列出一种或多种资源。 |
kustomize | kubectl kustomize <dir> [flags] [options] | 根据 kustomization.yaml 文件中的指令生成 API 资源列表。该参数必须是包含该文件的目录路径,或者一个 git 仓库 URL(并在路径后缀中指明相对于仓库根目录的位置)。 |
label | kubectl label (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags] | 为一个或多个资源添加或更新标签。 |
日志 | kubectl logs POD [-c CONTAINER] [--follow] [flags] | 打印 Pod 中容器的日志。 |
options | kubectl options | 全局命令行选项列表(适用于所有命令)。 |
patch | kubectl patch (-f FILENAME | TYPE NAME | TYPE/NAME) --patch PATCH [flags] | 使用策略性合并补丁(strategic merge patch)流程更新资源的一个或多个字段。 |
plugin | kubectl plugin [flags] [options] | 提供用于与插件交互的工具。 |
port-forward | kubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags] | 将一个或多个本地端口转发到 Pod。 |
proxy | kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix] [flags] | 运行一个到 Kubernetes API 服务器的代理。 |
replace | kubectl replace -f FILENAME | 从文件或标准输入替换资源。 |
rollout | kubectl rollout SUBCOMMAND [options] | 管理资源的滚动更新(rollout)。有效资源类型包括:deployments、daemonsets 和 statefulsets。 |
run | kubectl run NAME --image=image [--env="key=value"] [--port=port] [--dry-run=server|client|none] [--overrides=inline-json] [flags] | 在集群上运行指定的镜像。 |
scale | kubectl scale (-f FILENAME | TYPE NAME | TYPE/NAME) --replicas=COUNT [--resource-version=version] [--current-replicas=count] [flags] | 更新指定复制控制器的大小。 |
set | kubectl set SUBCOMMAND [options] | 配置应用程序资源。 |
taint | kubectl taint NODE NAME KEY_1=VAL_1:TAINT_EFFECT_1 ... KEY_N=VAL_N:TAINT_EFFECT_N [options] | 更新一个或多个节点上的污点。 |
top | kubectl top (POD | NODE) [flags] [options] | 显示 Pod 或 Node 的资源(CPU/内存/存储)使用情况。 |
uncordon | kubectl uncordon NODE [options] | 将节点标记为可调度。 |
version | kubectl version [--client] [flags] | 显示客户端和服务器上运行的 Kubernetes 版本。 |
wait | kubectl wait ([-f FILENAME] | resource.group/resource.name | resource.group [(-l label | --all)]) [--for=delete|--for condition=available] [options] | 实验性:等待一个或多个资源上的特定条件。 |
要了解有关命令操作的更多信息,请参阅 kubectl 参考文档。
下表包含所有支持的资源类型及其缩写别名列表。
(此输出可从 kubectl api-resources 获取,且截至 Kubernetes 1.25.0 时保持准确)
| 名称 | 缩写 | API 版本 | 命名空间作用域 | 类别 (KIND) |
|---|---|---|---|---|
bindings | v1 | true | Binding | |
componentstatuses | cs | v1 | false | ComponentStatus |
configmaps | cm | v1 | true | ConfigMap |
endpoints | ep | v1 | true | 端点 |
events | ev | v1 | true | Event |
limitranges | limits | v1 | true | LimitRange |
namespaces | ns | v1 | false | Namespace |
nodes | no | v1 | false | Node |
persistentvolumeclaims | pvc | v1 | true | PersistentVolumeClaim |
persistentvolumes | pv | v1 | false | PersistentVolume |
pods | po | v1 | true | Pod |
podtemplates | v1 | true | PodTemplate | |
replicationcontrollers | rc | v1 | true | ReplicationController |
resourcequotas | quota | v1 | true | ResourceQuota |
secrets | v1 | true | Secret | |
serviceaccounts | sa | v1 | true | ServiceAccount |
services | svc | v1 | true | Service |
mutatingwebhookconfigurations | admissionregistration.k8s.io/v1 | false | MutatingWebhookConfiguration | |
validatingwebhookconfigurations | admissionregistration.k8s.io/v1 | false | ValidatingWebhookConfiguration | |
customresourcedefinitions | crd,crds | apiextensions.k8s.io/v1 | false | CustomResourceDefinition |
apiservices | apiregistration.k8s.io/v1 | false | APIService | |
controllerrevisions | apps/v1 | true | ControllerRevision | |
daemonsets | ds | apps/v1 | true | DaemonSet |
deployments | deploy | apps/v1 | true | Deployment |
replicasets | rs | apps/v1 | true | ReplicaSet |
statefulsets | sts | apps/v1 | true | StatefulSet |
tokenreviews | authentication.k8s.io/v1 | false | TokenReview | |
localsubjectaccessreviews | authorization.k8s.io/v1 | true | LocalSubjectAccessReview | |
selfsubjectaccessreviews | authorization.k8s.io/v1 | false | SelfSubjectAccessReview | |
selfsubjectrulesreviews | authorization.k8s.io/v1 | false | SelfSubjectRulesReview | |
subjectaccessreviews | authorization.k8s.io/v1 | false | SubjectAccessReview | |
horizontalpodautoscalers | hpa | autoscaling/v2 | true | HorizontalPodAutoscaler |
cronjobs | cj | batch/v1 | true | CronJob |
jobs | batch/v1 | true | Job | |
certificatesigningrequests | csr | certificates.k8s.io/v1 | false | CertificateSigningRequest |
leases | coordination.k8s.io/v1 | true | Lease | |
endpointslices | discovery.k8s.io/v1 | true | EndpointSlice | |
events | ev | events.k8s.io/v1 | true | Event |
flowschemas | flowcontrol.apiserver.k8s.io/v1beta2 | false | FlowSchema | |
prioritylevelconfigurations | flowcontrol.apiserver.k8s.io/v1beta2 | false | PriorityLevelConfiguration | |
ingressclasses | networking.k8s.io/v1 | false | IngressClass | |
ingresses | ing | networking.k8s.io/v1 | true | Ingress |
networkpolicies | netpol | networking.k8s.io/v1 | true | NetworkPolicy |
runtimeclasses | node.k8s.io/v1 | false | RuntimeClass | |
poddisruptionbudgets | pdb | policy/v1 | true | PodDisruptionBudget |
podsecuritypolicies | psp | policy/v1beta1 | false | PodSecurityPolicy |
clusterrolebindings | rbac.authorization.k8s.io/v1 | false | ClusterRoleBinding | |
clusterroles | rbac.authorization.k8s.io/v1 | false | ClusterRole | |
rolebindings | rbac.authorization.k8s.io/v1 | true | RoleBinding | |
roles | rbac.authorization.k8s.io/v1 | true | 角色 | |
priorityclasses | pc | scheduling.k8s.io/v1 | false | PriorityClass |
csidrivers | storage.k8s.io/v1 | false | CSIDriver | |
csinodes | storage.k8s.io/v1 | false | CSINode | |
csistoragecapacities | storage.k8s.io/v1 | true | CSIStorageCapacity | |
storageclasses | sc | storage.k8s.io/v1 | false | StorageClass |
volumeattachments | storage.k8s.io/v1 | false | VolumeAttachment |
请使用以下章节获取有关如何格式化或排序某些命令输出的信息。关于哪些命令支持各种输出选项的详细信息,请参阅 kubectl 参考文档。
所有 kubectl 命令的默认输出格式为人类可读的纯文本格式。要以特定格式将详细信息输出到终端窗口,你可以在受支持的 kubectl 命令中添加 -o 或 --output 标志。
kubectl [command] [TYPE] [NAME] -o <output_format>
根据 kubectl 操作的不同,支持以下输出格式:
| 输出格式 | 描述 |
|---|---|
-o custom-columns=<spec> | 使用以逗号分隔的 自定义列 列表打印表格。 |
-o custom-columns-file=<filename> | 使用 <filename> 文件中的 自定义列 模板打印表格。 |
-o json | 输出 JSON 格式的 API 对象。 |
-o jsonpath=<template> | 打印由 jsonpath 表达式定义的字段。 |
-o jsonpath-file=<filename> | 打印由 <filename> 文件中的 jsonpath 表达式定义的字段。 |
-o kyaml | 输出 KYAML 格式的 API 对象(测试版)。 |
-o name | 仅打印资源名称,不打印其他内容。 |
-o wide | 以纯文本格式输出并包含任何额外信息。对于 Pod,会包含节点名称。 |
-o yaml | 输出 YAML 格式的 API 对象。KYAML 是一个实验性的 Kubernetes 特定 YAML 方言,可以解析为 YAML。 |
在此示例中,以下命令将单个 Pod 的详细信息输出为 YAML 格式的对象:
kubectl get pod web-pod-13je7 -o yaml
请记住:有关每个命令支持哪些输出格式的详细信息,请参阅 kubectl 参考文档。
要定义自定义列并仅将所需详细信息输出到表格中,可以使用 custom-columns 选项。你可以选择以内联方式定义自定义列,或使用模板文件:-o custom-columns=<spec> 或 -o custom-columns-file=<filename>。
内联:
kubectl get pods <pod-name> -o custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion
模板文件:
kubectl get pods <pod-name> -o custom-columns-file=template.txt
其中 template.txt 文件包含:
NAME RSRC
metadata.name metadata.resourceVersion
运行任一命令的结果类似于:
NAME RSRC
submit-queue 610995
kubectl 支持从服务器接收有关对象的特定列信息。这意味着对于任何给定的资源,服务器将返回与该资源相关的列和行,供客户端打印。通过让服务器封装打印细节,这可以实现在针对同一集群使用的不同客户端之间获得一致的人类可读输出。
此功能默认启用。要禁用它,请在 kubectl get 命令中添加 --server-print=false 标志。
要打印有关 Pod 状态的信息,请使用如下命令:
kubectl get pods <pod-name> --server-print=false
输出类似于
NAME AGE
pod-name 1m
要将对象输出为排序列表,你可以在受支持的 kubectl 命令中添加 --sort-by 标志。使用 --sort-by 标志指定任何数字或字符串字段来对对象进行排序。要指定字段,请使用 jsonpath 表达式。
kubectl [command] [TYPE] [NAME] --sort-by=<jsonpath_exp>
要打印按名称排序的 Pod 列表,请运行:
kubectl get pods --sort-by=.metadata.name
使用以下示例集来帮助你熟悉常见的 kubectl 操作:
kubectl apply - 从文件或标准输入应用或更新资源。
# Create a service using the definition in example-service.yaml.
kubectl apply -f example-service.yaml
# Create a replication controller using the definition in example-controller.yaml.
kubectl apply -f example-controller.yaml
# Create the objects that are defined in any .yaml, .yml, or .json file within the <directory> directory.
kubectl apply -f <directory>
kubectl get - 列出一种或多种资源。
# List all pods in plain-text output format.
kubectl get pods
# List all pods in plain-text output format and include additional information (such as node name).
kubectl get pods -o wide
# List the replication controller with the specified name in plain-text output format. Tip: You can shorten and replace the 'replicationcontroller' resource type with the alias 'rc'.
kubectl get replicationcontroller <rc-name>
# List all replication controllers and services together in plain-text output format.
kubectl get rc,services
# List all daemon sets in plain-text output format.
kubectl get ds
# List all pods running on node server01
kubectl get pods --field-selector=spec.nodeName=server01
kubectl describe - 显示一种或多种资源的详细状态,默认包含未初始化的资源。
# Display the details of the node with name <node-name>.
kubectl describe nodes <node-name>
# Display the details of the pod with name <pod-name>.
kubectl describe pods/<pod-name>
# Display the details of all the pods that are managed by the replication controller named <rc-name>.
# Remember: Any pods that are created by the replication controller get prefixed with the name of the replication controller.
kubectl describe pods <rc-name>
# Describe all pods
kubectl describe pods
kubectl get 命令通常用于检索相同资源类型的一种或多种资源。它具有丰富的标志集合,允许你使用 -o 或 --output 标志来自定义输出格式。你可以指定 -w 或 --watch 标志来开始监视特定对象的更新。kubectl describe 命令更专注于描述指定资源的多个相关方面。它可能会调用 API 服务器的多个 API 调用来为用户构建视图。例如,kubectl describe node 命令不仅检索有关节点的信息,还检索在该节点上运行的 Pod 的摘要、为该节点生成的事件等。kubectl delete - 通过文件、标准输入或指定标签选择器、名称、资源选择器或资源来删除资源。
# Delete a pod using the type and name specified in the pod.yaml file.
kubectl delete -f pod.yaml
# Delete all the pods and services that have the label '<label-key>=<label-value>'.
kubectl delete pods,services -l <label-key>=<label-value>
# Delete all pods, including uninitialized ones.
kubectl delete pods --all
kubectl exec - 在 Pod 中的容器上执行命令。
# Get output from running 'date' from pod <pod-name>. By default, output is from the first container.
kubectl exec <pod-name> -- date
# Get output from running 'date' in container <container-name> of pod <pod-name>.
kubectl exec <pod-name> -c <container-name> -- date
# Get an interactive TTY and run /bin/bash from pod <pod-name>. By default, output is from the first container.
kubectl exec -ti <pod-name> -- /bin/bash
kubectl logs - 打印 Pod 中容器的日志。
# Return a snapshot of the logs from pod <pod-name>.
kubectl logs <pod-name>
# Start streaming the logs from pod <pod-name>. This is similar to the 'tail -f' Linux command.
kubectl logs -f <pod-name>
kubectl diff - 查看集群拟议更新的差异。
# Diff resources included in "pod.json".
kubectl diff -f pod.json
# Diff file read from stdin.
cat service.yaml | kubectl diff -f -
使用以下示例集来帮助你熟悉编写和使用 kubectl 插件:
# create a simple plugin in any language and name the resulting executable file
# so that it begins with the prefix "kubectl-"
cat ./kubectl-hello
#!/bin/sh
# this plugin prints the words "hello world"
echo "hello world"
编写插件后,让我们使其可执行:
chmod a+x ./kubectl-hello
# and move it to a location in our PATH
sudo mv ./kubectl-hello /usr/local/bin
sudo chown root:root /usr/local/bin
# You have now created and "installed" a kubectl plugin.
# You can begin using this plugin by invoking it from kubectl as if it were a regular command
kubectl hello
hello world
# You can "uninstall" a plugin, by removing it from the folder in your
# $PATH where you placed it
sudo rm /usr/local/bin/kubectl-hello
为了查看 kubectl 可用的所有插件,请使用 kubectl plugin list 子命令:
kubectl plugin list
输出类似于
The following kubectl-compatible plugins are available:
/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
/usr/local/bin/kubectl-bar
kubectl plugin list 还会警告你不可执行或被其他插件覆盖的插件;例如:
sudo chmod -x /usr/local/bin/kubectl-foo # remove execute permission
kubectl plugin list
The following kubectl-compatible plugins are available:
/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
- warning: /usr/local/bin/kubectl-foo identified as a plugin, but it is not executable
/usr/local/bin/kubectl-bar
error: one plugin warning was found
你可以将插件视为在现有 kubectl 命令之上构建更复杂功能的手段:
cat ./kubectl-whoami
接下来的几个示例假设你已经编写了 kubectl-whoami 并具备以下内容:
#!/bin/bash
# this plugin makes use of the `kubectl config` command in order to output
# information about the current user, based on the currently selected context
kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ printf "%s\n" .context.user }}{{ end }}{{ end }}'
运行上述命令,输出将包含 KUBECONFIG 文件中当前上下文的用户信息:
# make the file executable
sudo chmod +x ./kubectl-whoami
# and move it into your PATH
sudo mv ./kubectl-whoami /usr/local/bin
kubectl whoami
Current user: plugins-user
kubectl 参考文档:kubectl 使用约定