Contents
- 1 導入：対象読者とこの記事で得られること
- 2 最短でこれだけやれば動く（最短手順）
- 3 共通フロー：イメージ作成から公開までの基本
- 4 環境別の差分と注意点（minikube / kind / Docker Desktop）
- 5 Ingress Controller ごとの違いと実務上の注意
- 6 HPA と metrics-server の導入と hpa.yaml の例
- 7 永続化・OS依存・hosts ファイルの扱い
- 8 セキュリティ：Secret 管理と RBAC の実務的運用
- 9 GitOps（Argo CD）導入の注意点（ローカル検証）
- 10 トラブルシューティング：代表的な問題と対処
- 11 主要コマンド一覧（参考）
- 12 まとめ
導入：対象読者とこの記事で得られること
Kubernetes初心者がローカル環境で実務に近いデプロイ手順を短時間で試せるよう整理します。minikube／kind／Docker Desktop を想定し、Deployment と Service/Ingress、HPA、更新・ロールバックまでを順を追って説明します。Kubernetes初心者がまず実行すべきコマンドとファイル構成をすぐに使える形で提示します。
最短でこれだけやれば動く（最短手順）
まずは最小限で動作確認したい方向けに、必要な手順を短く示します。環境差分は本文で詳述するため、まずは下記を順に実行してください。各コマンドは実行する端末のシェルや OS に合わせてください。
- クラスタ起動（例: minikube を使用する場合）
|
1 2 3 |
minikube start --driver=docker --cpus=2 --memory=4096 minikube addons enable ingress |
- イメージをビルドしてクラスタへ反映（環境により方法が異なります）
|
1 2 3 4 |
docker build -t myapp:0.1 . # minikube の場合: minikube image load myapp:0.1 # kind の場合: kind load docker-image myapp:0.1 --name kind |
- マニフェスト適用と動作確認
|
1 2 3 4 |
kubectl apply -f k8s/deployment.yaml -f k8s/service.yaml kubectl rollout status deployment/myapp kubectl port-forward svc/myapp 8080:80 # または minikube service myapp --url |
共通フロー：イメージ作成から公開までの基本
ここではローカルで共通して使えるフローを示します。イメージの作成とクラスタへの配布、Deployment/Service/Ingress の最低限の構成を押さえてください。
イメージの作成とローカルクラスタへの配布
イメージはまずローカルでビルドします。ローカルクラスタへ反映する方法は環境によって異なるため、ここでまとめて参照できるようにします。
- ローカルでビルド:
|
1 2 |
docker build -t myapp:0.1 . |
- minikube へ反映（選択肢）:
- 直接ロード:
|
1 2 |
minikube image load myapp:0.1 |
- minikube の Docker 環境でビルド（Unix系シェル）:
|
1 2 3 4 |
eval $(minikube -p minikube docker-env) docker build -t myapp:0.1 . # シェルを元に戻すには: eval $(minikube -p minikube docker-env --unset) |
- PowerShell の例:
|
1 2 3 |
minikube -p minikube docker-env --shell powershell | Invoke-Expression docker build -t myapp:0.1 . |
- kind へ反映:
|
1 2 |
kind load docker-image myapp:0.1 --name kind |
- Docker Desktop:
- Kubernetes を有効にした場合、ホストの Docker デーモンとイメージを共有できます。
-
imagePullPolicy の扱いに注意してください（ローカルイメージを使うなら IfNotPresent/ Never を検討）。
-
プライベートレジストリ利用時:
|
1 2 3 4 5 6 |
kubectl create secret docker-registry regcred \ --docker-server=<REGISTRY_SERVER> \ --docker-username=<USERNAME> \ --docker-password=<PASSWORD> \ --docker-email=<EMAIL> |
イメージの配布手順はここに一本化してください。環境ごとの差分は次章で簡潔にまとめます。
Deployment / Service / Ingress の最小構成
まず動く最小構成を用意し、その後にプローブやリソース制限を追加します。Ingress は必ず Ingress Controller と合わせて使ってください。
- k8s/deployment.yaml（最小例）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
apiVersion: apps/v1 kind: Deployment metadata: name: myapp labels: app: myapp spec: replicas: 2 selector: matchLabels: app: myapp template: metadata: labels: app: myapp spec: containers: - name: myapp image: myapp:0.1 imagePullPolicy: IfNotPresent ports: - containerPort: 80 readinessProbe: httpGet: path: / port: 80 initialDelaySeconds: 5 periodSeconds: 10 livenessProbe: httpGet: path: /healthz port: 80 initialDelaySeconds: 15 periodSeconds: 20 resources: requests: cpu: "100m" memory: "128Mi" limits: cpu: "500m" memory: "512Mi" |
- k8s/service.yaml（NodePort の例）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
apiVersion: v1 kind: Service metadata: name: myapp spec: selector: app: myapp ports: - protocol: TCP port: 80 targetPort: 80 type: NodePort |
- k8s/ingress.yaml（Ingress Controller に依存する最小例）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: myapp-ingress spec: ingressClassName: nginx # 利用する IngressClass を明示すること rules: - host: myapp.local http: paths: - path: / pathType: Prefix backend: service: name: myapp port: number: 80 |
Ingress の追加設定（rewrite など）はコントローラ依存です。詳しくは「Ingress Controller ごとの違い」の節を参照してください。
環境別の差分と注意点（minikube / kind / Docker Desktop）
ローカル環境ごとに挙動や運用上の注意が異なります。共通フローは同じですが、イメージの反映や LoadBalancer/Ingress の扱いが変わるためここで整理します。
minikube 固有の注意点
minikube は学習や検証向けに多くのアドオンが用意されています。LoadBalancer 検証や Ingress の有効化が比較的簡単です。
- 起動例:
|
1 2 3 |
minikube start --driver=docker --cpus=2 --memory=4096 minikube addons enable ingress |
- metrics-server はアドオンで有効化可能:
|
1 2 |
minikube addons enable metrics-server |
- イメージ反映の例: minikube image load か docker-env を利用
- Bash/zsh: eval $(minikube -p minikube docker-env)
-
PowerShell: minikube -p minikube docker-env --shell powershell | Invoke-Expression
-
LoadBalancer 検証: minikube tunnel を使いますが、実行には管理者権限が必要な場合があります。別ターミナルで実行し続ける必要があります。
-
hostPath やローカルディレクトリを使う場合: minikube mount を使うとホストのディレクトリをノード内にマウントできます。
|
1 2 |
minikube mount /path/on/host:/data --uid=1000 --gid=1000 |
注意: minikube が VM ベースの場合、hostPath は VM 側のパスを参照します。直接ホストのパスを期待しないでください。
kind 固有の注意点
kind はコンテナ内にノードを立ち上げるため CI 向けや高速検証に向きますが、containerd を使うためイメージの取り扱いに差分があります。
- クラスタ作成とイメージロード:
|
1 2 3 4 |
kind create cluster --name kind docker build -t myapp:0.1 . kind load docker-image myapp:0.1 --name kind |
- Ingress/LoadBalancer は別途導入が必要です。代表例:
- ingress-nginx の kind 向けマニフェスト（公式リリースを指定して適用）
- MetalLB を導入して LoadBalancer をエミュレート
公式マニフェストはリリースタグを明示して取得してください（stable ブランチ直叩きは避ける）。
Docker Desktop 固有の注意点
Docker Desktop は手軽ですが、リソース配分やライセンスに注意が必要です。
- Kubernetes を Settings で有効化して利用
- WSL2 と統合している場合、WSL 側のビルドがそのまま使えるケースがあります
- LoadBalancer のサポートは限定的で、NodePort や port-forward を使うことが多い
- 商用利用や企業での導入は Docker のライセンス変更に注意し、最新の利用規約を確認してください
Ingress Controller ごとの違いと実務上の注意
Ingress リソースの振る舞いは Ingress Controller（nginx、traefik、クラウドコントローラ等）に依存します。必ず使用するコントローラのドキュメントを参照してください。
nginx-ingress の注意点
nginx コントローラは注釈（annotations）で細かい挙動を制御できます。例えばパス書き換えは nginx 固有の注釈を使います。
- 例（nginx 固有）:
|
1 2 |
nginx.ingress.kubernetes.io/rewrite-target: / |
- IngressClass または ingressClassName を明示してコントローラを指定してください。
Traefik や他のコントローラ
Traefik や各クラウドのコントローラでは設定方法や注釈が異なります。ルーティングやミドルウェア設定の記法が変わるため、同じ Ingress 定義でも期待する挙動が変わる点に注意してください。
クラウドプロバイダの LoadBalancer（GCE/ALB など）
クラウド環境では Service type: LoadBalancer によってクラウドの LB が作られます。注釈やサービス設定はプロバイダ依存です。ローカルで検証する際は minikube tunnel や MetalLB で動作を再現してください。
HPA と metrics-server の導入と hpa.yaml の例
自動スケールを使うにはメトリクス基盤が必要です。ローカル環境では metrics-server の導入・設定が HPA が動作するための主な前提です。
metrics-server をローカル環境で動かす
metrics-server は公式リポジトリの release を使って導入し、マニフェストはリリースタグを固定して取得してください。例として最新版を直接使うのではなく、GitHub のリリースページからタグを指定して適用します。ローカルの kubelet が自己署名証明書を使っている場合、metrics-server に --kubelet-insecure-tls を追加する必要があることがあります。
- minikube ではアドオンを使うことも可能:
|
1 2 |
minikube addons enable metrics-server |
- マニフェストを手動で適用する場合は、公式リリースの components.yaml をダウンロードしてから適用し、必要に応じて Deployment の args に --kubelet-insecure-tls を追加してください。
編集例（簡易）:
|
1 2 3 |
kubectl -n kube-system edit deployment metrics-server # containers[0].args に --kubelet-insecure-tls を追加 |
hpa.yaml（サンプル）
以下は k8s/hpa.yaml の例です。クラスタの API バージョンに合わせて autoscaling バージョンを調整してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: myapp-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: myapp minReplicas: 1 maxReplicas: 5 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 50 |
古いクラスターでは autoscaling/v1 の targetCPUUtilizationPercentage を使う必要があります。用途に合わせて選択してください。
HPA のトラブルシュート（簡潔）
- metrics-server が正しく動作しているか確認: kubectl -n kube-system get pods | grep metrics-server
- メトリクス取得確認: kubectl top nodes / kubectl top pods
- HPA の状態確認: kubectl get hpa -o wide
- kubelet の TLS エラーがあれば metrics-server の --kubelet-insecure-tls を検討
永続化・OS依存・hosts ファイルの扱い
開発用のホストボリュームや hosts 編集などは OS による差分が重要です。特に Windows/WSL2 や VM ベースの minikube では挙動が異なります。
hostPath と WSL2/Windows の注意
hostPath は Pod のノード側ファイルシステムを直接参照します。ノードが VM やコンテナで動いている場合、期待したホストのパスが参照されないことがあります。開発では local-path-provisioner や minikube mount、あるいは Docker Desktop／WSL2 の共有機能を利用してください。
- Windows の場合:
- Docker Desktop（WSL2 統合）ではパスの扱いに注意が必要です。C:\ のパスをそのまま hostPath に書いてもノードにマウントされない場合があります。
- minikube を Windows 上で利用する場合は minikube mount を使うか、ホスト側の共有方法を確認してください。
開発用の PV/PVC 例は hostPath を使えますが、本番ではクラウドの永続ストレージか CSI プロビジョナーを利用してください。
hosts ファイルの編集（OS別）
ローカルで Ingress のホスト名を割り当てるときは hosts を編集します。編集は管理者権限が必要です。
-
Linux / macOS:
-
ファイル: /etc/hosts
-
編集: sudo vi /etc/hosts
-
Windows:
-
ファイル: C:\Windows\System32\drivers\etc\hosts
- 管理者権限でエディタを起動して編集
minikube を使う場合は minikube service myapp --url や minikube ip を確認して該当の IP を hosts に追加してください。
セキュリティ：Secret 管理と RBAC の実務的運用
開発と本番で Secret を扱う方法は異なります。リポジトリに平文で置かないことは必須です。
Secret 管理（sealed-secrets / SOPS / External Secrets）
- Sealed Secrets（Bitnami）
- 公開鍵でシークレットを暗号化し、Git にコミット可能にするツール。復号はクラスタ内のコントローラが担当します。
- SOPS（Mozilla）
- GPG/Cloud KMS などでファイルを暗号化して Git 管理する方法。CI で復号して適用します。
- External Secrets
- AWS Secrets Manager、HashiCorp Vault、GCP Secret Manager 等と連携して Kubernetes Secret を同期する実装があります。
用途に応じて上記から選び、機密情報は必ず暗号化して管理してください。
RBAC と最小権限
ServiceAccount と Role/RoleBinding を用いて最小権限を設定してください。管理用途で cluster-admin を安易に付与しないことが重要です。たとえば、namespace 内で ConfigMap を読むだけの Role を作成して ServiceAccount に付与する例を本文中に示しました。
GitOps（Argo CD）導入の注意点（ローカル検証）
Argo CD 等の GitOps ツールをローカルで試す場合は、マニフェストの取得元（リリースタグ）を固定してください。stable ブランチ直叩きは将来的な変更リスクがあるため推奨しません。
- インストール（例、タグを指定）:
|
1 2 3 |
kubectl create namespace argocd kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/<RELEASE_TAG>/manifests/install.yaml |
- 初期管理者パスワード取得（表示はしないが取得コマンド例）:
|
1 2 |
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d |
ローカル検証の後は SSO や外部認証の導入を検討し、デフォルトの資格情報は速やかに変更してください。公式ドキュメントのリリースノートを参照して、使用するバージョンを固定する運用を推奨します。
トラブルシューティング：代表的な問題と対処
ここではよくあるトラブルと簡潔な切り分け手順を示します。まずは該当するコマンドで情報を取得してください。
CrashLoopBackOff
- 確認コマンド:
|
1 2 3 |
kubectl describe pod <pod> kubectl logs <pod> --previous |
- 主な原因と対処:
- エントリポイントや引数の誤りを確認する
- 環境変数やマウントの不備をチェック
- プローブや初期遅延が短すぎる場合は initialDelaySeconds を増やす
ImagePullBackOff
- 確認コマンド:
|
1 2 |
kubectl describe pod <pod> |
- 対処:
- イメージ名・タグの確認
- imagePullSecrets の設定確認
- ローカルクラスタは image load を検討（kind/minikube）
Pending（スケジューリング不可）
- 確認コマンド:
|
1 2 3 |
kubectl describe pod <pod> kubectl get events |
- 対処:
- Insufficient cpu/memory の場合はリソース要求を見直す
- taint/toleration、nodeSelector の不整合を確認する
Ingress が効かない
- 確認:
- Ingress Controller の Pod が動作しているか: kubectl get pods -n
- Ingress のイベント: kubectl describe ingress
- hosts の設定や IngressClass が正しいか確認
HPA がスケールしない
- 確認:
- kubectl top pods/nodes がデータを返すか
- metrics-server Pod のログを確認
- metrics-server の kubelet TLS エラーを疑う（--kubelet-insecure-tls）
主要コマンド一覧（参考）
以下は日常的に使うコマンドの一覧です。必要に応じて適切な引数を追加してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
kubectl apply -f <file|dir> kubectl get pods,svc,deploy,ingress,hpa kubectl describe pod <pod> kubectl logs <pod> [-c container] [--previous] kubectl exec -it <pod> -- /bin/sh kubectl port-forward <resource> <local>:<remote> kubectl rollout status deployment/<name> kubectl set image deployment/<name> <container>=<image> kubectl rollout undo deployment/<name> kubectl scale deployment <name> --replicas=N kubectl autoscale deployment <name> --min=1 --max=5 --cpu-percent=70 kubectl top pods kubectl top nodes kubectl get events --sort-by=.metadata.creationTimestamp kubectl get pv,pvc kubectl create secret generic <name> --from-file=... kubectl config current-context kubectl config use-context <context> |
まとめ
ローカル環境での Kubernetes デプロイ手順は、「共通フロー（イメージ→デプロイ→公開）」を押さえ、環境別の差分（minikube/kind/Docker Desktop）を理解することが近道です。Ingress コントローラや metrics-server、Secret 管理はコントローラや環境によって挙動が変わるため、公式ドキュメントからリリースタグを固定して導入する運用を推奨します。まずは最短手順を実行して動作を確認し、その後プローブ・リソース・セキュリティ周りを強化してください。