Kubernetes入門｜主要リソースとYAMLの書き方、kubectl早見表

Kubernetes（クバネティス、略してK8s）とは、たくさんのコンテナを複数のサーバーにまたがって配置し、落ちたら自動で立て直し、負荷に合わせて数を増減させる「コンテナのオーケストレーション（まとめて管理する）」基盤です。「コンテナをこういう状態で3つ動かしておいて」とYAMLであるべき状態を宣言すると、Kubernetesがその状態を保ち続けます。

入門の段階でつまずきやすいのは、リソースの種類が多く、どれが何をするのかが見えにくいことです。この記事では、よく使う8つのリソースを1枚の表にまとめ、Docker Composeの書き方と対応づけて説明します。記事中のYAMLは、Kubernetes 1.36 のAPIスキーマで実際に検証ツールにかけて、正しく書けていることを確認しました。わざと間違えたYAMLで出るエラーも載せています。

Kubernetesの主要リソース早見表

普段の開発で自分で書くのは、Deployment・Service・ConfigMap・Secret・Ingressの5つが中心です。PodとReplicaSetは、Deploymentが自動で作ります。

なぜKubernetesが必要なのか

コンテナ1つ、サーバー1台なら docker run やDocker Composeで十分です。サービスが大きくなると、次のような仕事が増えていきます。

「手順を実行する」のではなく「あるべき状態を宣言する」のがKubernetesの考え方です。Podを手で消しても、Deploymentに replicas: 3 と書いてあれば、すぐに3つ目が作り直されます。

クラスターの構成

┌──────────── クラスター ────────────┐
│ コントロールプレーン                  │
│  API Server / etcd / Scheduler /    │  ← kubectl はここに命令する
│  Controller Manager                 │
├─────────────────────────────────────┤
│ ワーカーノード1   ワーカーノード2      │
│  kubelet          kubelet           │
│  [Pod][Pod]       [Pod]             │  ← コンテナが実際に動く
└─────────────────────────────────────┘

マネージドサービス（EKS・GKE・AKS）では、コントロールプレーンの運用はクラウド側が担当し、利用者はワーカーノードとアプリに集中できます。

Docker Composeとの対応

Docker Composeを使ったことがあれば、次の対応で理解が早くなります。

# compose.yaml
services:
  web:
    image: nginx:1.30
    ports:
      - "8080:80"
    environment:
      APP_MODE: production
    deploy:
      replicas: 3

depends_on がない点が大きな違いです。Kubernetesでは、アプリ自身が「接続先がまだ準備中なら待って再試行する」ように作り、準備が整ったかどうかはreadinessProbeで伝えます。

YAMLの例：Deployment＋Service

nginxを3つ動かし、Service web で振り分ける最小構成に、プローブ・リソース指定・ConfigMap/Secretの読み込みを加えた例です。

# app.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web            # ① このラベルのPodを管理する
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: web          # ② ①と一致させる
    spec:
      containers:
        - name: web
          image: nginx:1.30
          ports:
            - containerPort: 80
          env:
            - name: APP_MODE
              valueFrom:
                configMapKeyRef:
                  name: web-config
                  key: APP_MODE
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: web-secret
                  key: DB_PASSWORD
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              memory: 256Mi
          readinessProbe:
            httpGet:
              path: /
              port: 80
            initialDelaySeconds: 3
            periodSeconds: 5
          livenessProbe:
            httpGet:
              path: /
              port: 80
            initialDelaySeconds: 10
            periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  type: ClusterIP
  selector:
    app: web              # ③ ②のラベルを持つPodに振り分ける
  ports:
    - port: 80            # Serviceが受けるポート
      targetPort: 80      # Podのコンテナのポート

# config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: web-config
data:
  APP_MODE: production
---
apiVersion: v1
kind: Secret
metadata:
  name: web-secret
type: Opaque
stringData:
  DB_PASSWORD: change-me
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
spec:
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

①②③の3か所のラベルがつながっていることが、Kubernetesの配線そのものです。

検証ツールにかけた結果

Pythonの kubernetes-validate（KubernetesのOpenAPI定義から作られたJSONスキーマで検証するツール）で、上の2ファイルを確認しました。

$ pip install kubernetes-validate
$ kubernetes-validate --strict app.yaml config.yaml
INFO app.yaml passed for resource deployment/web against version 1.36
INFO app.yaml passed for resource service/web against version 1.36
INFO config.yaml passed for resource configmap/web-config against version 1.36
INFO config.yaml passed for resource secret/web-secret against version 1.36
INFO config.yaml passed for resource ingress/web against version 1.36

よくある書き間違いを2つ入れると、次のように検出されました。

# replicas を replica と書いた（--strict なしでは通ってしまう）
ERROR ... spec: Additional properties are not allowed ('replica' was unexpected)

# containerPort を "80"（文字列）と書いた
ERROR ... spec.template.spec.containers.0.ports.0.containerPort: '80' is not of type 'integer'

--strict を付けないと、replica のようなつづりの間違いは「知らない項目」として見逃され、検証を通過しました。この場合、Kubernetesは初期値の1台で動かします。検証には --strict を付けるのがおすすめです。

一方、②のラベルを app: webx に変えて①と食い違わせたYAMLは、スキーマ検証を通過しました。スキーマは「型と項目名」しか見ないためです。公式ドキュメントでは、selectorとテンプレートのラベルが一致しないDeploymentはAPIサーバーが受け付けない仕様になっています。クラスターがあれば kubectl apply --dry-run=server -f app.yaml で、APIサーバーのチェックまで事前に確認できます。

kubectlの基本コマンド早見表

困ったらまず kubectl describe の一番下の Events を見ます。イメージが取得できない、メモリ不足で配置できない、プローブが失敗している、といった理由がここに出ます。

Podの状態とよくある原因

ローリングアップデート

Deploymentのイメージを変えると、新しいPodを少しずつ増やし、前のバージョンのPodを少しずつ減らして入れ替えます。

上のYAMLでは maxSurge: 1、maxUnavailable: 0 にしています。「1つ新しいPodを作り、readinessProbeが通ってから前のPodを1つ消す」を繰り返すので、常に3つ以上が応答できる状態を保ちます。

kubectl set image deploy/web web=nginx:1.31
kubectl rollout status deploy/web     # 完了まで待って結果を表示
kubectl rollout undo deploy/web       # 問題があれば1つ前に戻す

readinessProbeがないと、起動しただけでまだ準備ができていないPodにもアクセスが振り分けられます。ローリングアップデートを止めずに行うには、readinessProbeが重要です。

プローブ：liveness・readiness・startup

livenessProbeにDBへの接続確認を入れないのがポイントです。DBが一時的に止まると全Podが再起動を繰り返し、DBが戻っても復旧に時間がかかります。livenessは「プロセス自身が応答できるか」だけ、外部への依存はreadinessで見ると役割がはっきりします。

requestsとlimits

requestsを書かないと、ノードに詰め込みすぎて性能が不安定になることがあります。まずは実際の使用量（kubectl top pods、metrics-serverが必要）を見て、requestsを平常時の使用量、limits.memoryを余裕を持った上限に設定するのが始めやすい方法です。

Namespaceで区切る

kubectl create namespace dev
kubectl apply -f app.yaml -n dev
kubectl get pods -n dev

同じNamespaceの中なら、Service web には http://web で届きます。別のNamespaceからは http://web.dev.svc.cluster.local（サービス名.Namespace名.svc.cluster.local）で指定します。チームや環境（dev/stg）ごとに分け、権限（RBAC）やリソースの上限（ResourceQuota）をNamespace単位でかけられます。

ConfigMapとSecretの注意点

• Secretは初期状態では暗号化ではなくBase64で保存されています。kubectl get secret web-secret -o yaml で見える値は、誰でも元に戻せます
• SecretのYAMLをそのままGitにコミットしないのが基本です。クラウドのシークレット管理サービスと連携する仕組みや、暗号化してから保存するツールを組み合わせます
• 環境変数として読み込んだ値は、ConfigMapを変えてもPodを作り直すまで反映されません。kubectl rollout restart deploy/web で入れ替えます

Ingressと、これからのGateway API

Ingressは、1つの入口（ロードバランサー）で、ホスト名やパスごとに複数のServiceへ振り分けるリソースです。Ingressを動かすには、別途Ingressコントローラーのインストールが必要です。

2026年時点では、Ingressの後継として設計された Gateway API（HTTPRoute など）が標準的な選択肢になっています。Kubernetesコミュニティが提供していたコントローラー「ingress-nginx」は2026年3月にメンテナンスを終えており、新しく構築する場合は、Gateway APIに対応したコントローラーや、クラウドが提供するロードバランサー連携を選ぶとよいでしょう。Ingressリソース自体は引き続き利用できます。

ローカルで試す方法

# kind の例
kind create cluster --name dev
kubectl apply -f config.yaml -f app.yaml
kubectl get pods
kubectl port-forward svc/web 8080:80   # ブラウザで http://localhost:8080
kind delete cluster --name dev

まずkindかminikubeで、この記事のYAMLを apply → Podを1つ削除して自動で戻ることを確認 → イメージを変えてローリングアップデート、の順に触ってみると、Kubernetesの動きが体でわかります。

マネージドKubernetes：EKS・GKE・AKS

どれもKubernetesのAPIは共通なので、この記事のYAMLとkubectlの知識はそのまま使えます。違いが出るのは、ロードバランサー・ストレージ・認証など、クラウドの機能とつなぐ部分です。

Kubernetesは約4か月ごとに新しいマイナーバージョンが出て、各バージョンのサポート期間は約1年です（2026年9月時点の最新は1.37）。マネージドサービスでも定期的なバージョンアップが必要になるため、運用の計画に含めておきます。

Kubernetesを使うかどうかの判断表

Kubernetesは強力な分、覚えることも多い仕組みです。規模と必要な機能に合わせて選ぶのが、無理のない進め方です。

よくある質問

Q. DockerとKubernetesの違いは何ですか？ A. Dockerはコンテナを作って動かすための道具、Kubernetesはたくさんのコンテナを複数のサーバーで管理するための基盤です。KubernetesはDockerなどで作ったコンテナイメージを受け取って動かします。

Q. PodではなくDeploymentを書くのはなぜですか？ A. Podを直接作ると、落ちたときやノードが止まったときに作り直されません。Deploymentにすると、指定した数を保ち、更新とロールバックもできるためです。

Q. Serviceに接続できません。どこを見ればいいですか？ A. kubectl get endpoints web（または kubectl get endpointslices）で、振り分け先のPodが登録されているかを確認します。空なら、ServiceのselectorとPodのラベルが一致していないか、readinessProbeが通っていないことが多いです。

Q. 入門にはどのくらいのPCスペックが必要ですか？ A. kindやminikubeで小さなアプリを動かすなら、メモリ8GB程度から試せます。Docker Desktopなどに割り当てるメモリを増やしておくと安定します。

まとめ

• Kubernetesは、あるべき状態をYAMLで宣言し、その状態を自動で保つコンテナ管理基盤
• 自分で書くのは Deployment・Service・ConfigMap・Secret・Ingress が中心
• selectorとラベルの一致が配線そのもの。検証ツールは --strict を付けて使う
• 困ったら kubectl describe のEvents と kubectl logs --previous
• readinessは振り分けの判断、livenessは再起動の判断。役割を分けて設定する
• requestsは配置の基準、limitsは上限。メモリ上限を超えるとOOMKilled
• まずは kind・minikube で、自己修復とローリングアップデートを体験する

株式会社RJCでは、コンテナからKubernetesへと広がるインフラの技術も、手を動かしながら仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。