kubectlの概要

kubectlコマンドラインツールを使うと、Kubernetesクラスターを制御できます。環境設定のために、kubectlは、$HOME/.kubeディレクトリにあるconfigという名前のファイルを探します。他のkubeconfigファイルは、KUBECONFIG環境変数を設定するか、--kubeconfigフラグを設定することで指定できます。 この概要では、kubectlの構文を扱い、コマンド操作を説明し、一般的な例を示します。サポートされているすべてのフラグやサブコマンドを含め、各コマンドの詳細については、kubectlリファレンスドキュメントを参照してください。インストール方法については、kubectlのインストールおよびセットアップをご覧ください。

構文

ターミナルウィンドウからkubectlコマンドを実行するには、以下の構文を使用します。

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

ここで、commandTYPENAMEflagsは、以下を表します。

  • command: 1つ以上のリソースに対して実行したい操作を指定します。例えば、creategetdescribedeleteです。

  • TYPE: リソースタイプを指定します。リソースタイプは大文字と小文字を区別せず、単数形や複数形、省略形を指定できます。例えば、以下のコマンドは同じ出力を生成します。

    kubectl get pod pod1
    kubectl get pods pod1
    kubectl get po pod1
    
  • NAME: リソースの名前を指定します。名前は大文字と小文字を区別します。kubectl get podsのように名前が省略された場合は、すべてのリソースの詳細が表示されます。

    複数のリソースに対して操作を行う場合は、各リソースをタイプと名前で指定するか、1つまたは複数のファイルを指定することができます。

    • リソースをタイプと名前で指定する場合

      • タイプがすべて同じとき、リソースをグループ化するには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

    • リソースを1つ以上のファイルで指定する場合は、-f file1 -f file2 -f file<#>とします。

  • flags: オプションのフラグを指定します。例えば、-sまたは--serverフラグを使って、Kubernetes APIサーバーのアドレスやポートを指定できます。

ヘルプが必要な場合は、ターミナルウィンドウからkubectl helpを実行してください。

操作

以下の表に、kubectlのすべての操作の簡単な説明と一般的な構文を示します。

操作                 構文 説明
alpha kubectl alpha SUBCOMMAND [flags] アルファ機能に該当する利用可能なコマンドを一覧表示します。これらの機能は、デフォルトではKubernetesクラスターで有効になっていません。
annotate kubectl annotate (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags] 1つ以上のリソースのアノテーションを、追加または更新します。
api-resources kubectl api-resources [flags] 利用可能なAPIリソースを一覧表示します。
api-versions kubectl api-versions [flags] 利用可能なAPIバージョンを一覧表示します。
apply kubectl apply -f FILENAME [flags] ファイルまたは標準出力から、リソースの設定変更を適用します。
attach kubectl attach POD -c CONTAINER [-i] [-t] [flags] 実行中のコンテナにアタッチして、出力ストリームを表示するか、コンテナ(標準入力)と対話します。
auth kubectl auth [flags] [options] 認可を検査します。
autoscale kubectl autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MAXPODS [--cpu-percent=CPU] [flags] ReplicationControllerで管理されているPodのセットを、自動的にスケールします。
certificate kubectl certificate SUBCOMMAND [options] 証明書のリソースを変更します。
cluster-info kubectl cluster-info [flags] クラスター内のマスターとサービスに関するエンドポイント情報を表示します。
completion kubectl completion SHELL [options] 指定されたシェル(bashまたはzsh)のシェル補完コードを出力します。
config kubectl config SUBCOMMAND [flags] kubeconfigファイルを変更します。詳細は、個々のサブコマンドを参照してください。
convert kubectl convert -f FILENAME [options] 異なるAPIバージョン間で設定ファイルを変換します。YAMLとJSONに対応しています。
cordon kubectl cordon NODE [options] Nodeをスケジュール不可に設定します。
cp kubectl cp <file-spec-src> <file-spec-dest> [options] コンテナとの間でファイルやディレクトリをコピーします。
create kubectl create -f FILENAME [flags] ファイルまたは標準出力から、1つ以上のリソースを作成します。
delete kubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags] ファイル、標準出力、またはラベルセレクター、リソースセレクター、リソースを指定して、リソースを削除します。
describe kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags] 1つ以上のリソースの詳細な状態を表示します。
diff kubectl diff -f FILENAME [flags] ファイルまたは標準出力と、現在の設定との差分を表示します。
drain kubectl drain NODE [options] メンテナンスの準備のためにNodeをdrainします。
edit kubectl edit (-f FILENAME | TYPE NAME | TYPE/NAME) [flags] デファルトのエディタを使い、サーバー上の1つ以上のリソースリソースの定義を編集し、更新します。
exec kubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]] Pod内のコンテナに対して、コマンドを実行します。
explain kubectl explain [--recursive=false] [flags] 様々なリソースのドキュメントを取得します。例えば、Pod、Node、Serviceなどです。
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] ReplicationController、Service、Podを、新しいKubernetesサービスとして公開します。
get kubectl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags] 1つ以上のリソースを表示します。
kustomize kubectl kustomize <dir> [flags] [options] kustomization.yamlファイル内の指示から生成されたAPIリソースのセットを一覧表示します。引数はファイルを含むディレクトリのPath,またはリポジトリルートに対して同じ場所を示すパスサフィックス付きの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] 1つ以上のリソースのラベルを、追加または更新します。
logs 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の処理を使用して、リソースの1つ以上のフィールドを更新します。
plugin kubectl plugin [flags] [options] プラグインと対話するためのユーティリティを提供します。
port-forward kubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags] 1つ以上のローカルポートを、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] リソースのロールアウトを管理します。有効なリソースには、Deployment、DaemonSetとStatefulSetが含まれます。
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] 指定したReplicationControllerのサイズを更新します。
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] 1つ以上のNodeのtaintを更新します。
top kubectl top [flags] [options] リソース(CPU/メモリー/ストレージ)の使用量を表示します。
uncordon kubectl uncordon NODE [options] Nodeをスケジュール可に設定します。
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] 実験中の機能: 1つ以上のリソースが特定の状態になるまで待ちます。

コマンド操作について詳しく知りたい場合は、kubectlリファレンスドキュメントを参照してください。

リソースタイプ

以下の表に、サポートされているすべてのリソースと、省略されたエイリアスの一覧を示します。

(この出力はkubectl api-resourcesから取得でき、Kubernetes 1.13.3時点で正確でした。)

リソース名 短縮名 APIグループ 名前空間に属するか リソースの種類
bindings true Binding
componentstatuses cs false ComponentStatus
configmaps cm true ConfigMap
endpoints ep true Endpoints
limitranges limits true LimitRange
namespaces ns false Namespace
nodes no false Node
persistentvolumeclaims pvc true PersistentVolumeClaim
persistentvolumes pv false PersistentVolume
pods po true Pod
podtemplates true PodTemplate
replicationcontrollers rc true ReplicationController
resourcequotas quota true ResourceQuota
secrets true Secret
serviceaccounts sa true ServiceAccount
services svc true Service
mutatingwebhookconfigurations admissionregistration.k8s.io false MutatingWebhookConfiguration
validatingwebhookconfigurations admissionregistration.k8s.io false ValidatingWebhookConfiguration
customresourcedefinitions crd, crds apiextensions.k8s.io false CustomResourceDefinition
apiservices apiregistration.k8s.io false APIService
controllerrevisions apps true ControllerRevision
daemonsets ds apps true DaemonSet
deployments deploy apps true Deployment
replicasets rs apps true ReplicaSet
statefulsets sts apps true StatefulSet
tokenreviews authentication.k8s.io false TokenReview
localsubjectaccessreviews authorization.k8s.io true LocalSubjectAccessReview
selfsubjectaccessreviews authorization.k8s.io false SelfSubjectAccessReview
selfsubjectrulesreviews authorization.k8s.io false SelfSubjectRulesReview
subjectaccessreviews authorization.k8s.io false SubjectAccessReview
horizontalpodautoscalers hpa autoscaling true HorizontalPodAutoscaler
cronjobs cj batch true CronJob
jobs batch true Job
certificatesigningrequests csr certificates.k8s.io false CertificateSigningRequest
leases coordination.k8s.io true Lease
events ev events.k8s.io true Event
ingresses ing extensions true Ingress
networkpolicies netpol networking.k8s.io true NetworkPolicy
poddisruptionbudgets pdb policy true PodDisruptionBudget
podsecuritypolicies psp policy false PodSecurityPolicy
clusterrolebindings rbac.authorization.k8s.io false ClusterRoleBinding
clusterroles rbac.authorization.k8s.io false ClusterRole
rolebindings rbac.authorization.k8s.io true RoleBinding
roles rbac.authorization.k8s.io true Role
priorityclasses pc scheduling.k8s.io false PriorityClass
csidrivers storage.k8s.io false CSIDriver
csinodes storage.k8s.io false CSINode
storageclasses sc storage.k8s.io false StorageClass
volumeattachments storage.k8s.io 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 name リソース名のみを表示します。
-o wide 追加情報を含めて、プレーンテキスト形式で出力します。Podの場合は、Node名が含まれます。
-o yaml YAML形式のAPIオブジェクトを出力します。

この例において、以下のコマンドは1つの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 - ファイルや標準出力から、リソースの適用や更新を行います。

# example-service.yaml内の定義を使用して、Serviceを作成します。
kubectl apply -f example-service.yaml

# example-controller.yaml内の定義を使用して、ReplicationControllerを作成します。
kubectl apply -f example-controller.yaml

# <directory>ディレクトリ内の、任意の.yaml、.yml、.jsonファイルで定義されているオブジェクトを作成します。
kubectl apply -f <directory>

kubectl get - 1つ以上のリソースの一覧を表示します。

# すべてのPodの一覧をプレーンテキスト形式で表示します。
kubectl get pods

# すべてのPodの一覧を、ノード名などの追加情報を含めて、プレーンテキスト形式で表示します。
kubectl get pods -o wide

# 指定した名前のReplicationControllerの一覧をプレーンテキスト形式で表示します。'replicationcontroller'リソースタイプを短縮して、エイリアス'rc'で置き換えることもできます。
kubectl get replicationcontroller <rc-name>

# すべてのReplicationControllerとServiceの一覧をまとめてプレーンテキスト形式で表示します。
kubectl get rc,services

# すべてのDaemonSetの一覧をプレーンテキスト形式で表示します。
kubectl get ds

# server01ノードで実行中のPodの一覧をプレーンテキスト形式で表示します。
kubectl get pods --field-selector=spec.nodeName=server01

kubectl describe - 1つ以上のリソースの詳細な状態を、デフォルトでは初期化されないものも含めて表示します。

# Node <node-name>の詳細を表示します。
kubectl describe nodes <node-name>

# Pod <pod-name>の詳細を表示します。
kubectl describe pods/<pod-name>

# ReplicationController <rc-name>が管理しているすべてのPodの詳細を表示します。
# ReplicationControllerによって作成された任意のPodには、ReplicationControllerの名前がプレフィックスとして付与されます。
kubectl describe pods <rc-name>

# すべてのPodの詳細を表示します。
kubectl describe pods

kubectl delete - ファイル、標準出力、または指定したラベルセレクター、名前、リソースセレクター、リソースを指定して、リソースを削除します。

# pod.yamlファイルで指定されたタイプと名前を用いて、Podを削除します。
kubectl delete -f pod.yaml

# '<label-key>=<label-value>'というラベルを持つPodとServiceをすべて削除します。
kubectl delete pods,services -l <label-key>=<label-value>

# 初期化されていないPodを含む、すべてのPodを削除します。
kubectl delete pods --all

kubectl exec - Pod内のコンテナに対してコマンドを実行します。

# Pod <pod-name>から、'date'を実行している時の出力を取得します。デフォルトでは、最初のコンテナから出力されます。
kubectl exec <pod-name> -- date

# Pod <pod-name>のコンテナ <container-name>から、'date'を実行している時の出力を取得します。
kubectl exec <pod-name> -c <container-name> -- date

# インタラクティブな TTY を取得し、Pod <pod-name>から/bin/bashを実行します。デフォルトでは、最初のコンテナから出力されます。
kubectl exec -ti <pod-name> -- /bin/bash

kubectl logs - Pod内のコンテナのログを表示します。

# Pod <pod-name>のログのスナップショットを返します。
kubectl logs <pod-name>

# Pod <pod-name>から、ログのストリーミングを開始します。Linuxの'tail -f'コマンドと似ています。
kubectl logs -f <pod-name>

kubectl diff - 提案されたクラスタに対する更新の差分を表示します。

# pod.jsonに含まれるリソースの差分を表示します。
kubectl diff -f pod.json

# 標準出力から読み込んだファイルの差分を表示します。
cat service.yaml | kubectl diff -f -

例: プラグインの作成と使用

kubectlプラグインの書き方や使い方に慣れるために、以下の例を使用してください。

# 任意の言語でシンプルなプラグインを作成し、生成される実行可能なファイルに
# プレフィックス"kubectl-"で始まる名前を付けます。
cat ./kubectl-hello
#!/bin/sh

# このプラグインは、"hello world"という単語を表示します。
echo "hello world"

プラグインを書いたら、実行可能にします。

chmod a+x ./kubectl-hello

# さらに、PATH内の場所に移動させます。
sudo mv ./kubectl-hello /usr/local/bin
sudo chown root:root /usr/local/bin

# これでkubectlプラグインを作成し、"インストール"できました。
# 通常のコマンドのようにkubectlから呼び出すことで、プラグインを使用できます。
kubectl hello
hello world
# 配置したPATHのフォルダから削除することで、プラグインを"アンインストール"できます。
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 # 実行権限を削除します。
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

# このプラグインは、`kubectl config`コマンドを使って
# 現在選択されているコンテキストに基づいて、現在のユーザーに関する情報を提供します。
kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ printf "%s\n" .context.user }}{{ end }}{{ end }}'

上記のコマンドを実行すると、KUBECONFIGファイル内のカレントコンテキストのユーザーを含んだ出力を得られます。

# ファイルを実行可能にします。
sudo chmod +x ./kubectl-whoami

# さらに、ファイルをPATHに移動します。
sudo mv ./kubectl-whoami /usr/local/bin

kubectl whoami
Current user: plugins-user

次の項目

  • kubectlを使い始めてください。

  • プラグインについてより詳しく知りたい場合は, example cli pluginを御覧ください。

最終更新 January 01, 2022 at 1:42 AM PST : replace link to en (82a201cf3)