命令列工具 (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]

其中 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<#>

    • 使用 YAML 而非 JSON，因為 YAML 往往更使用者友善，尤其適用於組態檔。
      範例：kubectl get -f ./pod.yaml

• flags：指定選用旗標。例如，您可以使用 -s 或 --server 旗標來指定 Kubernetes API 伺服器的位址和埠。
  

如果您需要協助，請從終端機視窗執行 kubectl help。

叢集內身份驗證和命名空間覆寫

預設情況下，kubectl 會先判斷它是否在 Pod 內執行，從而在叢集中執行。它首先檢查 KUBERNETES_SERVICE_HOST 和 KUBERNETES_SERVICE_PORT 環境變數，以及 /var/run/secrets/kubernetes.io/serviceaccount/token 中是否存在服務帳戶權杖檔案。如果找到這三者，則假設為叢集內身份驗證。

為了保持向後相容性，如果在叢集內身份驗證期間設定了 POD_NAMESPACE 環境變數，它將會覆寫服務帳戶權杖中的預設命名空間。任何依賴命名空間預設值的 Manifest 或工具都將受到影響。

POD_NAMESPACE 環境變數

如果設定了 POD_NAMESPACE 環境變數，則對命名空間資源的 CLI 操作將預設為變數值。例如，如果變數設定為 seattle，則 kubectl get pods 將會傳回 seattle 命名空間中的 Pod。這是因為 Pod 是命名空間資源，並且命令中未提供命名空間。檢閱 kubectl api-resources 的輸出以判斷資源是否為命名空間資源。

明確使用 --namespace <value> 會覆寫此行為。

kubectl 如何處理 ServiceAccount 權杖

如果

• Kubernetes 服務帳戶權杖檔案掛載在 /var/run/secrets/kubernetes.io/serviceaccount/token，且
• 設定了 KUBERNETES_SERVICE_HOST 環境變數，且
• 設定了 KUBERNETES_SERVICE_PORT 環境變數，且
• 您未在 kubectl 命令列上明確指定命名空間

接著，kubectl 會假設它在您的叢集中執行。kubectl 工具會查找該 ServiceAccount 的命名空間（這與 Pod 的命名空間相同），並針對該命名空間執行操作。這與叢集外部的情況不同；當 kubectl 在叢集外部執行，且您未指定命名空間時，kubectl 命令會針對用戶端配置中為目前環境設定的命名空間執行操作。若要變更 kubectl 的預設命名空間，您可以使用以下命令

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

操作

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

若要進一步瞭解命令操作，請參閱 kubectl 參考文件。

資源類型

下表包含所有支援的資源類型及其縮寫別名的清單。

(此輸出可以從 kubectl api-resources 取得，並且在 Kubernetes 1.25.0 時是準確的)

volumeattachments

輸出選項

使用以下章節以取得關於如何格式化或排序特定命令輸出的資訊。關於哪些命令支援各種輸出選項的詳細資訊，請參閱 kubectl 參考文件。

格式化輸出

語法

kubectl [command] [TYPE] [NAME] -o <output_format>

所有 kubectl 命令的預設輸出格式為人類可讀的純文字格式。若要以特定格式將詳細資訊輸出到您的終端機視窗，您可以將 -o 或 --output 旗標新增至支援的 kubectl 命令。

輸出 YAML 格式的 API 物件。

範例

kubectl get pod web-pod-13je7 -o yaml

在此範例中，以下命令會將單一 Pod 的詳細資訊輸出為 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

範本檔案

NAME          RSRC
metadata.name metadata.resourceVersion

其中 template.txt 檔案包含

NAME           RSRC
submit-queue   610995

執行任一命令的結果類似於

伺服器端欄位

kubectl 支援從伺服器接收關於物件的特定欄位資訊。這表示對於任何給定的資源，伺服器將傳回與該資源相關的欄位和列，以供用戶端列印。這透過讓伺服器封裝列印的詳細資訊，實現跨用於相同叢集的不同用戶端之間一致的人類可讀輸出。

若要定義自訂欄位並僅將您想要的詳細資訊輸出到表格中，您可以使用 custom-columns 選項。您可以選擇內嵌定義自訂欄位，或使用範本檔案：-o custom-columns=<spec> 或 -o custom-columns-file=<filename>。

此功能預設為啟用。若要停用它，請將 --server-print=false 旗標新增至 kubectl get 命令。

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

若要印出關於 Pod 狀態的資訊，請使用類似以下的命令

NAME       AGE
pod-name   1m

輸出結果類似於

排序清單物件

語法

kubectl [command] [TYPE] [NAME] --sort-by=<jsonpath_exp>

輸出 YAML 格式的 API 物件。

若要將物件輸出到終端機視窗中的排序清單，您可以將 --sort-by 旗標新增至支援的 kubectl 命令。透過指定任何數值或字串欄位以及 --sort-by 旗標來排序您的物件。若要指定欄位，請使用 jsonpath 表達式。

kubectl get pods --sort-by=.metadata.name

若要印出依名稱排序的 Pod 清單，您可以執行

範例：常見操作

使用以下範例集來幫助您熟悉執行常用的 kubectl 操作

# 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 apply - 從檔案或標準輸入套用或更新資源。

# 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 get - 列出一個或多個資源。

# 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 摘要、為節點產生的事件等。

# 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 delete - 從檔案、標準輸入刪除資源，或指定標籤選取器、名稱、資源選取器或資源。

# 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 exec - 針對 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 logs - 印出 Pod 中容器的日誌。

# Diff resources included in "pod.json".
kubectl diff -f pod.json

# Diff file read from stdin.
cat service.yaml | kubectl diff -f -

kubectl diff - 檢視對叢集建議更新的差異。

範例：建立和使用外掛程式

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

使用以下範例集來幫助您熟悉編寫和使用 kubectl 外掛程式

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 plugin list

若要印出關於 Pod 狀態的資訊，請使用類似以下的命令

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 檔案中目前 context 使用者的輸出。

# 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 指令參考
  • 命令列引數 參考
• 了解關於 kubectl 使用慣例
• 閱讀關於 kubectl 中的 JSONPath 支援
• 閱讀關於如何使用外掛程式擴充 kubectl
  • 若要進一步瞭解外掛程式，請查看範例 CLI 外掛程式。