【ITニュース解説】Kubernetes cluster marathon!

Kubernetesは、たくさんのアプリケーション（コンテナ）を複数のコンピューター（サーバー）で動かす際に、それらを自動で管理してくれる強力なツールである。システムエンジニアを目指す者にとって、この技術は非常に重要であり、習得することで大規模なシステムを効率的に運用するスキルが身につく。しかし、実際にKubernetesクラスタを構築する過程は、特に最新のオペレーティングシステム（OS）であるUbuntu 24.04のような環境では、一筋縄ではいかないことが多い。この記事は、Kubernetesクラスタを構築する際によく遭遇する問題と、その解決策、そして最終的に最も重要な教訓をまとめている。

最初の課題は、Kubernetesの主要なツールであるkubectl、kubelet、kubeadmをインストールしようとした際に発生した。これらのツールは、Kubernetesクラスタの操作、各ノードでのコンテナ管理、クラスタの初期設定に不可欠なものである。コマンドを実行しても「プログラムが見つからない」というエラーが出たのは、Googleが2024年にKubernetesのソフトウェアを配布している場所（パッケージリポジトリ）のアドレスを変更したためであった。多くの古いガイドには古いアドレスが記載されているため、正しいインストールを進めるには、まずこのリポジトリのアドレスを新しいものに更新する必要がある。具体的には、古いリポジトリ情報を削除し、新しいGPGキー（ソフトウェアの信頼性を保証する鍵）を追加し、最新のpkgs.k8s.ioで始まる公式リポジトリのアドレスをシステムに登録することで、ようやく必要なツールをインストールできるようになった。これは、ソフトウェアのインストール時には、配布元の信頼性と最新情報を確認することの重要性を示している。

次に遭遇した問題は、Kubernetesクラスタの初期設定を行うkubeadm initコマンドを実行した際に発生した「どのCRIソケットを使うか定義せよ」というエラーである。CRI（Container Runtime Interface）ソケットとは、Kubernetesがコンテナを実際に動かす「コンテナランタイム」と通信するための窓口のようなものである。Ubuntu 24.04環境では、Dockerやcontainerdといった複数のコンテナランタイムがシステムにインストールされている可能性があり、Kubernetesはどれを使ってコンテナを動かせばよいのか混乱してしまう。現代のKubernetesではcontainerdが推奨されているため、これをメインのコンテナランタイムとして選択し、明示的に設定する必要があった。containerdをインストールした後、その設定ファイル（/etc/containerd/config.toml）を適切に生成し、SystemdCgroup = trueという設定を有効にした。これは、Linuxのシステムリソース管理機構であるSystemdとcontainerdを連携させるために不可欠な設定である。また、CRIプラグインが誤って無効になっていないことを確認し、containerdサービスを再起動することで、この問題を解決した。

しかし、containerdの設定を終えた後も「CRI v1 Runtime API」に関するエラーが依然として発生した。これは、containerdの構成ファイルが正しく生成されておらず、CRIプラグインが機能していなかったことが原因であった。この問題の解決策は、一度containerdサービスを停止し、既存の不完全な設定ファイルを削除した後、containerd config defaultコマンドを使って適切なデフォルト設定ファイルを再生成することである。再生成されたファイルで再度SystemdCgroup = trueを設定し、CRIプラグインが有効であることを確認してからcontainerdを再起動することで、ようやくCRIランタイムが正しく機能するようになった。

さらに、kubeadm initの実行中にホスト名解決に関するエラーが発生した。これは、Kubernetesが他のサーバーと通信する際に、各サーバーの「名前」（ホスト名）と「ネットワーク上の住所」（IPアドレス）を正確に知る必要があるためである。Ubuntu 24.04のデフォルト設定では、ホスト名に127.0.1.1という特別なローカルIPアドレスが割り当てられることがあるが、このアドレスは同じコンピューター内でのみ有効であり、他のコンピューターからは到達できない。そのため、クラスタ内の他のノードからアクセスできるように、/etc/hostsファイルを編集して、ホスト名に実際のネットワークIPアドレス（例えば192.168.1.244のような）を関連付け、さらにkubeadm initコマンドにも--apiserver-advertise-addressオプションでこの実際のIPアドレスを明示的に指定する必要があった。

また、試行錯誤の過程でkubeadm resetコマンドを実行しても、依然として「ポート6443が使用中」というエラーが発生することがあった。これは、Kubernetes関連のプロセスが完全に終了していなかったり、設定ファイルやデータが残っていたりする場合に発生する。この問題を解決するためには、kubeadm resetコマンドに加え、/etc/kubernetes/、/var/lib/etcd/などの関連するディレクトリを完全に削除し、iptables（Linuxのファイアウォール機能）の設定をリセットし、さらにkube-apiserverなどのKubernetes関連プロセスを強制的に終了させるという、徹底的なクリーンアップが必要となる。これにより、システムをほぼ初期状態に戻し、ポートの競合を解消できる。

最後に、コントロールプレーンが正常に動作した後、ワーカーノードをクラスタに参加させようとした際に、ネットワーク接続に関するタイムアウトエラーが発生した。ワーカーノードがコントロールプレーンのAPIサーバーに到達できないことが原因であった。この問題は最もデバッグが困難なものであり、複数の要因が絡み合っていた。例えば、VPNツールであるTailscaleがコントロールプレーンにのみ導入されていたこと、ファイアウォール設定の問題、あるいは仮想マシンのネットワーク構成の複雑さなどである。

このような複数の問題が複雑に絡み合った結果、解決に要する時間と労力が膨大になることに直面した。そして、この経験から得られた最も重要な教訓は「時には最初からやり直すのが最善の解決策である」という点である。複雑な問題を一つずつ解決しようとするよりも、クリーンな仮想マシンを用意し、最初から計画的に構築し直す方が、結果的に早く成功にたどり着けることが多い。具体的には、Tailscaleのようなオーバーレイネットワーク（複数の物理ネットワークを仮想的に一つのネットワークとして扱う技術）をKubernetesコンポーネントを導入する前に設定し、クラスタ内の通信をすべてTailscaleのIPアドレスで行うようにすることで、ネットワークルーティングやファイアウォール、IPアドレスの混乱といった問題を最初から回避できる。また、コンテナランタイムも最初から一つに絞り、その設定を適切に行うことで、混乱を避けることができる。

Kubernetesのセットアップは学習曲線が急峻であり、特にネットワーク関連の問題は経験豊富なエンジニアにとっても難しい。しかし、このようなトラブルシューティングの経験は、システム全体への深い理解をもたらす貴重な機会である。問題解決の過程で得られた知見、例えばKubernetesリポジトリのURL変更、containerdのSystemdCgroup設定の重要性、CRIソケットの明示的な指定、マルチノードクラスタでのIPアドレスの適切な使用、そして徹底的なクリーンアップの必要性は、今後のシステム構築において必ず役立つだろう。最初からやり直すことを恐れず、学びながら進む姿勢が、最終的な成功への鍵となる。