Cluster APIをCAPD（Cluster API Provider Docker）で使っていると、「kubeconfigのAPIサーバーアドレスがhttps://172.18.0.3:6443のようなDocker内部のIPアドレスになっていて、macOSからアクセスできない...」という問題に遭遇したことはありませんでしょうか？

本稿では、この問題をIPアドレスを変更することなく解決する方法について解説していきます。

問題の背景

Cluster API + CAPD環境では、Control PlaneがDocker network上のコンテナーとして動作します。clusterctl get kubeconfigで取得したkubeconfigを見てみると、以下のようなエントリーが含まれています：

clusters:
  - cluster:
      server: https://172.18.0.3:6443

この172.18.0.3はDocker内部のネットワークアドレスで、macOS（ホストマシン）から直接アクセスすることはできません。

解決方法の概要

今回ご紹介する方法は、以下の2つのステップで構成されています：

macOSのloopbackインターフェースに172.18.0.3を追加する
172.18.0.3:6443へのアクセスをDocker Desktop VMに転送する

この方法の良いところは、kubeconfigを一切変更する必要がなく、副作用も最小限に抑えられる点です。それでは、具体的な手順を見ていきましょう。

ステップ1: loopbackインターフェースにIPアドレスを追加する

まず、macOSのloopbackインターフェース（lo0）に172.18.0.3を追加します：

# ループバックに /32 で alias を張る（再起動時は消える）
sudo ifconfig lo0 alias 172.18.0.3/32

なぜこれが安全なのか？

172.18.0.0/16はDocker Desktop VM内部でのみ使用されているプライベートアドレス空間です。macOS側に同じアドレスを持たせても：

外部ネットワークとの衝突は起きません
Docker Desktop VMとも直接は衝突しません（別々のネットワーク空間）
完全に"自己完結"したIPアドレスとして機能します

ステップ2: ポート転送の設定

次に、172.18.0.3:6443へのアクセスを、実際にKubernetes APIが公開されているポートに転送します。

Docker Desktop VMのポートを確認

まず、実際のポート番号を確認しましょう：

docker port workload-1-lb 6443

出力例：

0.0.0.0:55000

この場合、127.0.0.1:55000でKubernetes APIにアクセスできることがわかります。

socatを使った転送設定

確認したポート番号を使って、socatで転送を設定します：

# socatがまだインストールされていない場合
brew install socat

# 転送を開始（バックグラウンドで動かす場合は & を最後に）
sudo socat \
  TCP-LISTEN:6443,bind=172.18.0.3,reuseaddr,fork \
  TCP:127.0.0.1:55000

これで、https://172.18.0.3:6443へのアクセスが127.0.0.1:55000に転送されるようになります！

動作確認

設定が完了したら、kubectlコマンドで動作を確認してみましょう：

kubectl --kubeconfig=./workload-1.kubeconfig get nodes

正常に動作していれば、ノード一覧が表示されるはずです。

設定の解除方法

作業が終わったら、以下の手順で設定を解除できます：

# socatプロセスを停止（前景で動かしている場合はCtrl-C）
pkill -f "socat.*TCP-LISTEN:6443"

# loopbackのaliasを削除（再起動でも消えます）
sudo ifconfig lo0 -alias 172.18.0.3

まとめ

Cluster API + CAPD環境でmacOSからKubernetes APIにアクセスする問題を、kubeconfigを変更することなく解決する方法を紹介しました。

ポイントは：

loopbackインターフェースを活用することで、安全にIPアドレスを追加
socatを使った簡潔なポート転送設定
必要に応じて簡単に設定・解除が可能

この方法を使えば、開発環境でのCluster APIの検証がよりスムーズになるはずです。ぜひお試しください！

最後までお読みくださりありがとうございました。Cluster APIやKubernetesに関する技術情報を発信していますので、よかったらフォローお願いします😌