2026年7月30日

minikubeでローカルKubernetes環境を構築する手順｜インストールから動作確認・アドオン・よくあるエラーまで

Docker・コンテナ

minikubeは、手元のPCにKubernetesクラスター（既定では1ノード構成）を作るツールです。DockerなどのコンテナかVMの実行環境があれば、minikube start の1コマンドでクラスターが立ち上がり、kubectl で本番と同じようにマニフェストを試せます。この記事では、インストール、起動時のドライバーとリソースの決め方、サンプルアプリの公開、自作イメージの使い方、アドオン、止め方と消し方、起動できないときの確認方法を説明します。

手順はminikubeの安定版（2026年10月現在）を前提にしています。オプションや既定値は版によって変わることがあるため、迷ったら minikube start --help と公式ドキュメントで確認してください。

始める前に用意するもの

公式ドキュメントが示している目安は、CPU 2コア以上、空きメモリ2GB以上、ディスクの空き20GB以上です。ただしこれは「起動できる」最低限で、アドオンや複数のPodを動かすなら、メモリは4GB以上を割り当てられる環境のほうが扱いやすくなります。

もう一つ必要なのが、クラスターを入れる「器」です。minikubeではこれをドライバーと呼び、Docker、Podman、Hyper-V、VirtualBox、QEMU、KVMなどから選べます。すでにDockerを使っているならDockerドライバーが手軽で、ここでもそれを前提に進めます。

minikubeをインストールする

OSごとの代表的な方法です。

# Linux（x86_64）
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube && rm minikube-linux-amd64

# macOS（Homebrew）
brew install minikube

# Windows（winget）
winget install Kubernetes.minikube

ARM版のLinuxでは、ダウンロードするファイル名が minikube-linux-arm64 に変わります。公式のインストールページでOSとCPUの種類を選ぶと、対応するコマンドが表示されます。インストール後に minikube version で版を確認しておきます。

クラスターを起動する

minikube start --driver=docker --cpus=2 --memory=4096

初回はKubernetesのイメージを取得するため数分かかります。完了すると、kubectl の接続先（コンテキスト）が自動で minikube に切り替わります。

オプションの意味と注意点は次のとおりです。

--driver：省略すると、使える環境から自動で選ばれます。毎回同じドライバーを使うなら minikube config set driver docker で既定にできます。
--cpus と --memory：クラスターに割り当てる量です。メモリはMB単位の数値か 4g のような書き方ができます。**一度作ったクラスターの割り当ては、後から start で値を変えても反映されません。** 変えたいときは minikube delete で作り直します。
--kubernetes-version：本番のクラスターと版をそろえたいときに指定します（例：--kubernetes-version=v1.33.0）。対応している版の範囲はminikubeの版ごとに決まっているので、範囲外を指定すると警告かエラーになります。

Dockerドライバーはroot権限で実行すると止められます。一般ユーザーを docker グループに追加して、sudo を付けずに実行してください。なお docker グループに入ったユーザーは実質的にrootと同じ権限を持つため、共用のサーバーではなく自分のPCで使うのが前提です。

kubectlで中身を確認する

kubectl が入っていなくても、minikubeに同梱の版を使えます。

minikube kubectl -- get nodes
minikube kubectl -- get pods -A

# 毎回打つのが面倒なら別名を付ける
alias kubectl="minikube kubectl --"

ノードが Ready、kube-system 名前空間のPodが Running になっていれば、クラスターは正常です。本番のクラスターも触るなら、kubectl を別にインストールしておき、kubectl config current-context で今どのクラスターに向いているかを確認する習慣をつけると、誤って本番に適用する事故を防げます。

サンプルアプリを動かして外から開く

公式のチュートリアルにある、リクエスト内容を返すだけのアプリで確認します。

kubectl create deployment hello-minikube --image=kicbase/echo-server:1.0
kubectl expose deployment hello-minikube --type=NodePort --port=8080

kubectl get pods
minikube service hello-minikube

minikube service はサービスにアクセスするURLを表示し、ブラウザを開きます。DockerドライバーをmacOSやWindowsで使っている場合、クラスターのIPに直接届かないため、このコマンドがトンネルを張ってローカルのポートを割り当てます。その間ターミナルを閉じないでください。

もう一つの方法がポートフォワードです。

kubectl port-forward service/hello-minikube 7080:8080

この後 http://localhost:7080/ を開くと応答が返ります。ドライバーに関係なく同じ手順で使えるので、手早く確認したいときに便利です。

type: LoadBalancer のサービスは、そのままでは外部IPが <pending> のままになります。別のターミナルで minikube tunnel を実行している間だけIPが割り当てられます。

自作のイメージを使う

手元でビルドしたイメージは、minikubeのクラスターからは見えません。ここが最初につまずきやすい点です。方法は主に2つあります。

# 方法1：ビルド済みのイメージをクラスターに読み込む
docker build -t myapp:dev .
minikube image load myapp:dev

# 方法2：minikube内のDockerを使ってビルドする（コンテナランタイムがDockerの場合）
eval $(minikube docker-env)
docker build -t myapp:dev .

方法2はそのシェルの中だけ接続先が切り替わります。元に戻すときは eval $(minikube docker-env -u) を実行します。

どちらの場合も、マニフェストでは imagePullPolicy: IfNotPresent か Never を指定してください。タグが latest だと既定の取得方針が「毎回レジストリから取得」になり、手元にしかないイメージを探しに行って ErrImagePull になります。開発中は dev のような固定のタグを付けるのが分かりやすい方法です。

よく使うアドオン

minikubeには、追加の機能をコマンドで有効にできるアドオンがあります。

minikube addons list
minikube addons enable metrics-server
minikube addons enable ingress
minikube dashboard

metrics-server：kubectl top pods でCPUとメモリの使用量を見られるようになります。HorizontalPodAutoscalerを試すときにも必要です。
ingress：Ingressを処理するコントローラーを入れます。どのコントローラーが入るかはminikubeの版によって変わる可能性があるため、有効化した後に kubectl get ingressclass で確認してください。
dashboard：ブラウザで見られる管理画面です。minikube dashboard で起動します。

止める・消す・複数作る

minikube stop          # 停止（状態は残る）
minikube start         # 再開
minikube pause         # Kubernetesの処理だけ一時停止
minikube delete        # このクラスターを削除
minikube delete --all  # すべてのクラスターを削除

# 名前（プロファイル）を付けて別のクラスターを作る
minikube start -p test-133 --kubernetes-version=v1.33.0
minikube profile list

delete を実行すると、クラスター内のPersistentVolumeのデータも消えます。試していたデータベースの中身などを残したい場合は、先にエクスポートしておきます。

起動できないときの確認方法

まずエラーの最後に出る「Exiting due to ...」の行を読みます。原因の分類名（リソース不足、ドライバーの問題など）と、試すべきコマンドが書かれていることが多いからです。そのうえで、起きやすい順に確認します。

ドライバー（Docker）が動いていない：docker info がエラーになるなら、Docker自体を先に起動します。Docker Desktopの場合は、Desktopに割り当てたメモリが --memory の値より少ないと起動できません。
リソース不足：割り当てを下げるか、Docker Desktopの割り当てを増やします。その後 minikube delete から作り直します。
前回の状態が壊れている：PCのスリープや強制終了の後に起きやすいです。minikube delete してから start し直すのが早道です。
社内ネットワークやプロキシ：イメージの取得で止まる場合は、HTTPS_PROXY などの環境変数と、NO_PROXY にminikubeのIP範囲を入れる必要があります。

詳しく調べるときは minikube status と minikube logs を見ます。minikube logs はクラスター内部のログをまとめて出すので、--file=logs.txt でファイルに保存してから検索すると読みやすくなります。

minikube以外の選択肢

ローカルのKubernetesには、Docker上で複数ノードを手軽に作れるkind、軽量版のk3sをDockerで動かすk3d、Docker Desktopに付属のKubernetesなどもあります。アドオンや minikube service のような補助コマンドがそろっていて、学習や単体の動作確認がしやすいのがminikubeの長所です。小さなVPSで常時動かしたい場合は、k3sのほうが向いています。

まとめ

minikubeはKubernetesをローカルに作るツール（既定は1ノード）。Dockerがあれば minikube start --driver=docker で起動できる。
CPUとメモリの割り当ては作成時に決まる。変えるときは minikube delete から作り直す。
サービスの確認は minikube service か kubectl port-forward。LoadBalancerは minikube tunnel が必要。
自作イメージは minikube image load か minikube docker-env で渡し、imagePullPolicy を IfNotPresent か Never にする。
起動できないときは「Exiting due to」の行を読み、ドライバー、リソース、壊れた状態、プロキシの順に確認する。