命令列工具 (kubectl)

Kubernetes 提供一個命令列工具,用於與 Kubernetes 叢集的控制平面通訊,使用 Kubernetes API。

該工具名為 kubectl

對於配置,kubectl 會在 $HOME/.kube 目錄中查詢名為 config 的檔案。您可以設定 KUBECONFIG 環境變數或設定 --kubeconfig 標誌來指定其他 kubeconfig 檔案。

本概述涵蓋 kubectl 語法,描述命令操作,並提供常用示例。有關每個命令的詳細資訊,包括所有支援的標誌和子命令,請參閱 kubectl 參考文件。

有關安裝說明,請參閱 安裝 kubectl;有關快速指南,請參閱 備忘單。如果您習慣使用 docker 命令列工具,Docker 使用者kubectl 將解釋一些 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 操作將預設使用該變數的值。例如,如果變數設定為 seattlekubectl 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]從檔案或 stdin 應用配置更改到資源。
attachkubectl attach POD -c CONTAINER [-i] [-t] [flags]連線到正在執行的容器,以檢視輸出流或與容器互動(stdin)。
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]顯示叢集中 Master 和服務的端點資訊。
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]從檔案或 stdin 建立一個或多個資源。
deletekubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags]從檔案、stdin 或透過指定標籤選擇器、名稱、資源選擇器或資源來刪除資源。
describekubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags]顯示一個或多個資源的詳細狀態。
diffkubectl diff -f FILENAME [flags]將檔案或 stdin 與即時配置進行 diff。
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、node、service 等。
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從檔案或 stdin 替換資源。
rolloutkubectl rollout SUBCOMMAND [options]管理資源的 rollout。有效的資源型別包括:deployments、daemonsets 和 statefulsets。
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 為止是準確的)

名稱短名稱API版本名稱空間種類
bindingsv1true繫結
componentstatusescsv1falseComponentStatus
configmapscmv1trueConfigMap
endpointsepv1trueEndpoints
eventsevv1trueEvent
limitrangeslimitsv1trueLimitRange
namespacesnsv1falseNamespace
節點(nodes)nov1falseNode
persistentvolumeclaimspvcv1truePersistentVolumeClaim
persistentvolumespvv1falsePersistentVolume
Pod(pods)pov1truePod
podtemplatesv1truePodTemplate
replicationcontrollersrcv1true複製控制器
resourcequotasquotav1trueResourceQuota
secretsv1trueSecret
serviceaccountssav1trueServiceAccount
服務(services)svcv1true服務
mutatingwebhookconfigurationsadmissionregistration.k8s.io/v1falseMutatingWebhookConfiguration
validatingwebhookconfigurationsadmissionregistration.k8s.io/v1falseValidatingWebhookConfiguration
customresourcedefinitionscrd,crdsapiextensions.k8s.io/v1falseCustomResourceDefinition
apiservicesapiregistration.k8s.io/v1falseAPIService
controllerrevisionsapps/v1trueControllerRevision
daemonsetsdsapps/v1trueDaemonSet
deploymentsdeployapps/v1true部署
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/v1true定時作業
jobsbatch/v1true作業
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/v1trueIngress
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/v1true角色
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 命令的預設輸出格式是人類可讀的純文字格式。要以特定格式將詳細資訊輸出到終端視窗,您可以向支援的 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 物件(alpha,需要環境變數 KUBECTL_KYAML="true")。
-o name僅列印資源名稱,不列印其他任何內容。
-o wide以純文字格式輸出,並附帶任何額外資訊。對於 pod,將包含節點名稱。
-o yaml輸出 YAML 格式的 API 物件。KYAML 是 YAML 的實驗性 Kubernetes 特定方言,可以作為 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 支援從伺服器接收有關物件的特定列資訊。這意味著對於任何給定的資源,伺服器將返回與該資源相關的列和行,供客戶端列印。這使得伺服器能夠封裝列印的細節,從而在針對同一叢集使用的客戶端之間實現一致的可讀輸出。

此功能預設啟用。要停用它,請將 --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 - 從檔案或 stdin 應用或更新資源。

# 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 - 從檔案、stdin 或透過指定標籤選擇器、名稱、資源選擇器或資源來刪除資源。

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

# 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

下一步

最後修改日期 2025 年 7 月 1 日上午 8:58 PST:文件 KYAML (9f26f83533)