命令行工具 (kubectl)

Kubernetes 提供了一个命令行工具,用于使用 Kubernetes API 与 Kubernetes 集群的 控制平面 通信。

此工具名为 kubectl

为了配置,kubectl 会在 $HOME/.kube 目录中查找名为 config 的文件。您可以通过设置 KUBECONFIG 环境变量或设置 --kubeconfig 标志来指定其他 kubeconfig 文件。

本概述涵盖了 kubectl 语法,描述了命令操作,并提供了一些常见示例。有关每个命令的详细信息,包括所有支持的标志和子命令,请参阅 kubectl 参考文档。

有关安装说明,请参阅 安装 kubectl;有关快速指南,请参阅 备忘单。如果您习惯使用 docker 命令行工具,kubectl 针对 Docker 用户 解释了 Kubernetes 的一些等效命令。

语法

使用以下语法从您的终端窗口运行 kubectl 命令

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

其中 commandTYPENAMEflags

  • command:指定您要对一个或多个资源执行的操作,例如 creategetdescribedelete

  • 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<#>

  • flags:指定可选标志。例如,您可以使用 -s--server 标志来指定 Kubernetes API 服务器的地址和端口。

如果您需要帮助,请从终端窗口运行 kubectl help

集群内身份验证和命名空间覆盖

默认情况下,kubectl 首先会确定它是否在 pod 内运行,因此在集群内运行。它首先检查 KUBERNETES_SERVICE_HOSTKUBERNETES_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 假设它在您的集群中运行。kubectl 工具会查找该 ServiceAccount 的命名空间(这与 Pod 的命名空间相同),并针对该命名空间执行操作。这与在集群外部发生的情况不同;当 kubectl 在集群外部运行并且您没有指定命名空间时,kubectl 命令会针对您客户端配置中为当前上下文设置的命名空间执行操作。要更改 kubectl 的默认命名空间,您可以使用以下命令

kubectl config set-context --current --namespace=<namespace-name>

操作

下表包含所有 kubectl 操作的简短描述和一般语法

操作语法描述
alphakubectl alpha SUBCOMMAND [flags]列出与 alpha 功能相对应的可用命令,这些功能在 Kubernetes 集群中默认情况下未启用。
annotatekubectl annotate (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags]添加或更新一个或多个资源的注释。
api-resourceskubectl api-resources [flags]列出可用的 API 资源。
api-versionskubectl api-versions [flags]列出可用的 API 版本。
applykubectl apply -f FILENAME [flags]将配置更改应用于来自文件或标准输入的资源。
attachkubectl attach POD -c CONTAINER [-i] [-t] [flags]附加到正在运行的容器,以查看输出流或与容器交互(标准输入)。
authkubectl auth [flags] [options]检查授权。
autoscalekubectl autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MAXPODS [--cpu-percent=CPU] [flags]自动缩放由复制控制器管理的 pod 集。
certificatekubectl certificate SUBCOMMAND [options]修改证书资源。
cluster-infokubectl cluster-info [flags]显示有关集群中主节点和服务的端点信息。
completionkubectl completion SHELL [options]为指定的 shell(bash 或 zsh)输出 shell 完成代码。
configkubectl config SUBCOMMAND [flags]修改 kubeconfig 文件。有关详细信息,请参阅各个子命令。
convertkubectl convert -f FILENAME [options]在不同 API 版本之间转换配置文件。接受 YAML 和 JSON 格式。注意 - 需要安装 kubectl-convert 插件。
cordonkubectl cordon NODE [options]将节点标记为不可调度。
cpkubectl cp <file-spec-src> <file-spec-dest> [options]将文件和目录复制到容器中和从容器中复制。
createkubectl create -f FILENAME [flags]从文件或标准输入创建一个或多个资源。
deletekubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags]从文件、标准输入或指定标签选择器、名称、资源选择器或资源中删除资源。
describekubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags]显示一个或多个资源的详细状态。
diffkubectl diff -f FILENAME [flags]将文件或标准输入与实时配置进行比较。
drainkubectl drain NODE [options]在准备维护时排空节点。
editkubectl edit (-f FILENAME | TYPE NAME | TYPE/NAME) [flags]使用默认编辑器编辑和更新服务器上一个或多个资源的定义。
eventskubectl events列出事件
execkubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]]对 Pod 中的容器执行命令。
explainkubectl explain TYPE [--recursive=false] [flags]获取各种资源的文档。例如 Pod、节点、服务等。
exposekubectl 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 服务。
getkubectl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags]列出一个或多个资源。
kustomizekubectl kustomize <dir> [flags] [options]列出从 kustomization.yaml 文件中的指令生成的 API 资源集。参数必须是包含该文件的目录的路径,或带有路径后缀的 git 仓库 URL,该后缀指定相对于仓库根目录的路径。
labelkubectl label (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags]添加或更新一个或多个资源的标签。
logskubectl logs POD [-c CONTAINER] [--follow] [flags]打印 Pod 中容器的日志。
optionskubectl options所有命令都适用的全局命令行选项列表。
patchkubectl patch (-f FILENAME | TYPE NAME | TYPE/NAME) --patch PATCH [flags]使用策略合并修补过程更新资源的一个或多个字段。
pluginkubectl plugin [flags] [options]提供与插件交互的实用程序。
port-forwardkubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags]将一个或多个本地端口转发到 Pod。
proxykubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix] [flags]运行代理到 Kubernetes API 服务器。
replacekubectl replace -f FILENAME从文件或标准输入替换资源。
rolloutkubectl rollout SUBCOMMAND [options]管理资源的发布。有效的资源类型包括:部署、守护进程集和有状态集。
runkubectl run NAME --image=image [--env="key=value"] [--port=port] [--dry-run=server|client|none] [--overrides=inline-json] [flags]在集群上运行指定的镜像。
scalekubectl scale (-f FILENAME | TYPE NAME | TYPE/NAME) --replicas=COUNT [--resource-version=version] [--current-replicas=count] [flags]更新指定复制控制器的规模。
setkubectl set SUBCOMMAND [options]配置应用程序资源。
taintkubectl taint NODE NAME KEY_1=VAL_1:TAINT_EFFECT_1 ... KEY_N=VAL_N:TAINT_EFFECT_N [options]更新一个或多个节点上的污点。
topkubectl top (POD | NODE) [flags] [options]显示 Pod 或节点的资源(CPU/内存/存储)使用情况。
uncordonkubectl uncordon NODE [options]将节点标记为可调度。
versionkubectl version [--client] [flags]显示客户端和服务器上运行的 Kubernetes 版本。
waitkubectl 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 时是准确的)

NAMESHORTNAMESAPIVERSIONNAMESPACEDKIND
bindingsv1trueBinding
componentstatusescsv1falseComponentStatus
configmapscmv1trueConfigMap
endpointsepv1trueEndpoints
eventsevv1trueEvent
limitrangeslimitsv1trueLimitRange
namespacesnsv1falseNamespace
nodesnov1falseNode
persistentvolumeclaimspvcv1truePersistentVolumeClaim
persistentvolumespvv1falsePersistentVolume
podspov1truePod
podtemplatesv1truePodTemplate
replicationcontrollersrcv1true复制控制器
resourcequotasquotav1trueResourceQuota
secretsv1trueSecret
serviceaccountssav1trueServiceAccount
servicessvcv1true服务
mutatingwebhookconfigurationsadmissionregistration.k8s.io/v1falseMutatingWebhookConfiguration
validatingwebhookconfigurationsadmissionregistration.k8s.io/v1falseValidatingWebhookConfiguration
customresourcedefinitionscrd,crdsapiextensions.k8s.io/v1falseCustomResourceDefinition
apiservicesapiregistration.k8s.io/v1falseAPIService
controllerrevisionsapps/v1trueControllerRevision
daemonsetsdsapps/v1trueDaemonSet
deploymentsdeployapps/v1trueDeployment
replicasetsrsapps/v1true副本集
statefulsetsstsapps/v1trueStatefulSet
tokenreviewsauthentication.k8s.io/v1falseTokenReview
localsubjectaccessreviewsauthorization.k8s.io/v1trueLocalSubjectAccessReview
selfsubjectaccessreviewsauthorization.k8s.io/v1falseSelfSubjectAccessReview
selfsubjectrulesreviewsauthorization.k8s.io/v1falseSelfSubjectRulesReview
subjectaccessreviewsauthorization.k8s.io/v1falseSubjectAccessReview
horizontalpodautoscalershpaautoscaling/v2trueHorizontalPodAutoscaler
cronjobscjbatch/v1trueCronJob
jobsbatch/v1trueJob
certificatesigningrequestscsrcertificates.k8s.io/v1falseCertificateSigningRequest
leasescoordination.k8s.io/v1trueLease
endpointslicesdiscovery.k8s.io/v1trueEndpointSlice
eventsevevents.k8s.io/v1trueEvent
flowschemasflowcontrol.apiserver.k8s.io/v1beta2falseFlowSchema
prioritylevelconfigurationsflowcontrol.apiserver.k8s.io/v1beta2falsePriorityLevelConfiguration
ingressclassesnetworking.k8s.io/v1falseIngressClass
ingressesingnetworking.k8s.io/v1true入口
networkpoliciesnetpolnetworking.k8s.io/v1trueNetworkPolicy
runtimeclassesnode.k8s.io/v1falseRuntimeClass
poddisruptionbudgetspdbpolicy/v1truePodDisruptionBudget
podsecuritypoliciespsppolicy/v1beta1falsePodSecurityPolicy
clusterrolebindingsrbac.authorization.k8s.io/v1falseClusterRoleBinding
clusterrolesrbac.authorization.k8s.io/v1falseClusterRole
rolebindingsrbac.authorization.k8s.io/v1trueRoleBinding
rolesrbac.authorization.k8s.io/v1trueRole
priorityclassespcscheduling.k8s.io/v1falsePriorityClass
csidriversstorage.k8s.io/v1falseCSIDriver
csinodesstorage.k8s.io/v1falseCSINode
csistoragecapacitiesstorage.k8s.io/v1trueCSIStorageCapacity
storageclassesscstorage.k8s.io/v1falseStorageClass
volumeattachmentsstorage.k8s.io/v1falseVolumeAttachment

输出选项

使用以下部分了解如何格式化或排序某些命令的输出。有关哪些命令支持各种输出选项的详细信息,请参阅 kubectl 参考文档。

格式化输出

所有 kubectl 命令的默认输出格式是人类可读的纯文本格式。要以特定格式将详细信息输出到您的终端窗口,您可以将 -o--output 标志添加到支持的 kubectl 命令中。

语法

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 name仅打印资源名称,不打印其他内容。
-o wide以纯文本格式输出,包含任何其他信息。对于 Pod,将包含节点名称。
-o yaml输出 YAML 格式的 API 对象。
示例

在此示例中,以下命令将单个 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 支持从服务器接收有关对象的特定列信息。这意味着对于任何给定的资源,服务器将返回与该资源相关的列和行,供客户端打印。通过让服务器封装打印的详细信息,这允许在针对同一集群使用的客户端之间实现一致的人类可读输出。

此功能默认启用。要禁用它,请将 --server-print=false 标志添加到 kubectl get 命令中。

示例

要打印有关 Pod 状态的信息,请使用以下命令

kubectl get pods <pod-name> --server-print=false

输出类似于

NAME       AGE
pod-name   1m

排序列表对象

要将对象输出到终端窗口中的排序列表中,您可以将 --sort-by 标志添加到支持的 kubectl 命令中。通过使用 --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 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

下一步

上次修改时间:2024 年 1 月 1 日下午 9:15 PST: 修复几个链接错误 (8b46ec4047)