KubernetesのためのYAML：必須マニフェストパターン

Kubernetesは完全にYAMLマニフェストを通じて設定されます。すべてのPod、Deployment、Service、Ingressは YAMLで定義されます。これらのパターンをマスターすることは、コンテナオーケストレーションに携わるすべての人にとって不可欠です。このガイドでは、最も重要なリソースタイプを本番環境対応の例と共に解説します。

4つの必須フィールド

すべてのKubernetesマニフェストに必要なもの：

apiVersion: apps/v1      # このリソースタイプのAPIバージョン
kind: Deployment          # リソースタイプ
metadata:                 # リソースの識別情報
  name: my-app
  namespace: production
  labels:
    app: my-app
spec:                     # 望ましい状態の仕様
  # ... リソース固有の設定

Deployment

最も一般的なリソース — 同一のPodのセットを管理：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  labels:
    app: api-server
    environment: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: api-server
    spec:
      containers:
        - name: api
          image: myapp/api:v1.2.3
          ports:
            - containerPort: 8080
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: db-credentials
                  key: url
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 512Mi
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 15
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 5

重要なパターン

必ずリソースのrequestsとlimitsを設定する：設定しないと、単一のPodがノードのすべてのリソースを消費する可能性があります。

必ずヘルスプローブを設定する：

livenessProbe：応答しなくなった場合にPodを再起動する
readinessProbe：Podの準備ができるまでトラフィックの送信を停止する

具体的なイメージタグを使用する：本番環境では決して latest を使用しないでください。ロールバックが不可能になります。

Service

Podをネットワークトラフィックに公開：

apiVersion: v1
kind: Service
metadata:
  name: api-server
spec:
  type: ClusterIP
  selector:
    app: api-server
  ports:
    - port: 80
      targetPort: 8080
      protocol: TCP

Serviceタイプ：

ClusterIP（デフォルト）：クラスター内部アクセスのみ
NodePort：各ノードIPの静的ポートで公開
LoadBalancer：クラウドロードバランサーをプロビジョニング
ExternalName：DNS名にマッピング

ConfigMapとSecret

ConfigMap（機密性のないデータ）

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  LOG_LEVEL: "info"
  MAX_CONNECTIONS: "100"
  config.yaml: |
    server:
      port: 8080
      timeout: 30s

Secret（機密データ）

apiVersion: v1
kind: Secret
metadata:
  name: db-credentials
type: Opaque
stringData:
  url: "postgres://user:password@db:5432/myapp"
  api-key: "sk-1234567890"

Podでの使用

# 環境変数として
env:
  - name: LOG_LEVEL
    valueFrom:
      configMapKeyRef:
        name: app-config
        key: LOG_LEVEL

# マウントされたファイルとして
volumes:
  - name: config
    configMap:
      name: app-config

Ingress

外部HTTPトラフィックをServiceにルーティング：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - api.example.com
      secretName: tls-secret
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api-server
                port:
                  number: 80

Horizontal Pod Autoscaler

CPUまたはカスタムメトリクスに基づいてPodをスケール：

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-server-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-server
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

よくあるミス

1. インデントエラー

KubernetesではYAMLのインデントが非常に重要です。スペース1つの違いで構造が完全に変わります。YAMLバリデーターでマニフェストを検証してください。

2. ラベルの不一致

Serviceのselectorは、Podのラベルと完全に一致する必要があります。不一致があると、ServiceはトラフィックをルーティングするためのPodを見つけることができません。

3. リソース制限の未設定

リソース制限のないPodは、他のワークロードを枯渇させる可能性があります。常にrequests（保証された最小値）とlimits（許可される最大値）の両方を含めてください。

4. 変更可能なイメージタグ

latest やその他の変更可能なタグを使用すると、ロールバックが不可能になり、デプロイメントが予測不能になります。特定のバージョンに固定するか、不変のダイジェストを使用してください。

マルチドキュメントマニフェスト

--- をドキュメントセパレーターとして使用して、関連リソースを1つのファイルにまとめる：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  # ... Deploymentの仕様
---
apiVersion: v1
kind: Service
metadata:
  name: api-server
spec:
  # ... Serviceの仕様

YAML構文パターンの詳細については、YAML構文チュートリアルをご覧ください。

FAQ

Kubernetes YAMLは手書きすべきですか、それともジェネレーターを使うべきですか？

構造を理解するために、まず手書きでYAMLを書くことから始めてください。本番環境では、Helm（テンプレート化されたマニフェスト）、Kustomize（オーバーレイベースのカスタマイズ）、CDK8s（コードベースの生成）などのツールを使用してください。これらのツールは繰り返しを減らし、マニフェストを複製することなく環境固有の設定を可能にします。

Kubernetes YAMLエラーをデバッグするにはどうすればよいですか？

kubectl apply --dry-run=client -f manifest.yaml を使用して、適用せずに検証してください。構文エラーについては、kubectl explain deployment.spec.template.spec.containers で期待される構造を確認できます。kubeval と kubeconform ツールは、デプロイ前にKubernetes APIスキーマに対して検証を行います。