Kubernetes で作成するものはすべて、マニフェストに記述されたオブジェクトです。マニフェストは、望むものを記述した YAML ファイルです。このガイドでは、マニフェストを読むのに十分な YAML、すべてのマニフェストが共有する構造を説明し、ファイルから Pod を実行する手順を示します。動作するクラスターがあることを前提としています（前のガイドを参照）。

5 分でわかる YAML

YAML には、知っておくべき 2 つの構成要素があります。

マップは、key: value のペアの集合です。インデントがネストを表し、キーの下にインデントされたものはすべて、そのキーに属します。リストは、各項目がダッシュで始まる、一連の項目です。

app:
  name: shop
  enabled: true
  labels:
    tier: frontend
  ports:
    - 80
    - 443

ここで app は、name、enabled、labels、ports というキーを持つマップです。labels は、それ自体がマップで、ports は 2 つの数値のリストです。スペースを使い、タブは決して使わないでください。インデントの誤りは、マニフェストが適用されない最も一般的な原因で、何が何に属するかを黙って変えてしまいます。--- だけの行で区切れば、複数のオブジェクトを 1 つのファイルに入れられます。

マニフェストの構造

すべての Kubernetes オブジェクトは、同じ最上位のフィールドを持ちます。

• apiVersion は、この種類のオブジェクトを定義する API のバージョンを示します。
• kind は、Pod や Deployment のようなオブジェクトの種類です。大文字小文字が区別されます。
• metadata はオブジェクトを識別します。その name、必要に応じて namespace、そして labels と annotations です。
• spec は望ましい状態で、その内容は種類によって異なります。

Kubernetes は 4 つ目のセクション status を追加し、これは実際の状態を記述します。自分では書きません。最小限の Pod は次のとおりです。

apiVersion: v1
kind: Pod
metadata:
  name: web
  labels:
    app: web
spec:
  containers:
    - name: nginx
      image: nginx:1.25
      ports:
        - containerPort: 80

containers はリストなので、Pod は複数のコンテナを実行でき、それぞれが独自のダッシュで始まります。image フィールドは、二重に確認すべきものです。タイプミスがあると、Kubernetes が pull できず、Pod はエラー状態のままになります。

マニフェストをゼロから書かない

Kubernetes のドキュメントから動作する例をコピーするか、kubectl に生成させます。

kubectl run web --image=nginx:1.25 --port=80 --dry-run=client -o yaml > pod.yaml

--dry-run=client は、作成せずに、ローカルでオブジェクトを構築し、-o yaml はそれを YAML として出力します。これにより、編集できる有効な出発点が得られます。

apiVersion を正しく選ぶ

種類によって、存在する API のグループとバージョンが異なります。Pod は v1、Deployment は apps/v1、Ingress は networking.k8s.io/v1 です。間違ったものを選んだり、新しいクラスターが削除したバージョンを使ったりすると、no matches for kind "X" in version "Y" のようなエラーが出ます。正しい値を見つけるには、次のようにします。

kubectl api-resources | grep -i deployment
kubectl explain deployment | head

最初のものは各種類のグループを示し、2 番目のものはその VERSION を示します。これは、クラスターをアップグレードするときに最も重要です。バージョンが削除されると、古いマニフェストが動作しなくなる可能性があるからです。Kubernetes の非推奨ガイドに、各リリースで何が変わったかが列挙されています。

作成、確認、削除

kubectl apply -f pod.yaml
kubectl get pods
kubectl describe pod web
kubectl delete -f pod.yaml

kubectl get pods では、READY 列に Pod のコンテナのうち何個が準備完了かが表示され（1/1 が正常）、STATUS はそのフェーズ、RESTARTS はコンテナの再起動回数をカウントします。増え続ける数字は、何かがコンテナを殺し続けていることを意味します。describe は、Pod の詳細をすべて出力し、最近のイベントが最後に表示されます。何かがおかしいときに、最初に見る場所です。

apply は宣言的です。オブジェクトが存在しなければ作成し、存在すれば更新するので、ファイルを編集して再度適用できます。kubectl create -f は、オブジェクトがすでに存在すると失敗します。

命令的と宣言的

kubectl run や kubectl create のようなコマンドは命令的です。Kubernetes に、今何かをするよう指示します。実験や認定試験には手早いです。kubectl apply -f で適用されるマニフェストは宣言的で、実際のものには、これが望ましい方法です。ファイルを Git に置き、レビューし、再適用できるからです。このシリーズの Argo CD のガイドでは、その考えを、結論まで進める方法を示しています。