はじめに
本記事は、homelabのKubernetesクラスタ（Talos Linux）にTailscaleを導入し、外部からのアクセスを可能にする過程で遭遇した問題と解決方法を記録します。
環境: Talos Linux v1.11.6 / Kubernetes v1.34.1 / 4ノード構成（CP×1 + Worker×3）
本記事で学べること
- Talos LinuxへのTailscale Extension導入方法（ExtensionServiceConfig）
- 全ノード一斉適用のヘマと推奨手順
1. やりたかったこと
1.1 背景
homelabのKubernetesクラスタに外部からアクセスしたい。現状はローカルネットワーク（10.0.0.0/24）からのみアクセス可能。
1.2 選択肢の検討
| 方式 | メリット | デメリット | 今回の判断 |
|---|---|---|---|
| ngrok | 簡単、無料枠あり | 帯域制限、URL固定に課金 | ❌ 特定アプリ向け。クラスタ全体へのアクセスには不向き |
| Cloudflare Tunnel | 高速、無料枠あり | パブリックドメイン必須 | ❌ homelab.localドメインを使いたい |
| Tailscale | WireGuardベース、簡単 | アカウント必要 | ✅ VPN方式でネットワーク全体にアクセス可能 |
今回は Tailscale を選択。理由は
- WireGuardベースで高速・安全
- 443/TCPフォールバック（外出先からでも使える）
- Talos公式Extensionがあり、試してみたかった
- kubectl/talosctlでクラスタ全体にアクセスしたかった
1.3 導入方式
TalosへのTailscale導入は2パターンある
| 方式 | 概要 |
|---|---|
| A. Talos Extension | OSレベルでインストール |
| B. K8s Operator | Kubernetes上で動作 |
今回は、A. Extension を選択
2. 事前準備
2.1 Tailscale アカウント作成
https://login.tailscale.com/ からGoogle/GitHub等で認証。
2.2 Auth Key 発行
Admin Console → Settings → Keys → Generate auth key
設定:
- Reusable: ✅（複数ノードで使用）
- Ephemeral: ❌
- Tags: tag:k8s-node
2.3 Extension バージョン確認
重要: Talosのバージョンに対応したExtensionを使用すること。
確認先: https://github.com/siderolabs/extensions/releases
| Talos Version | Tailscale Extension |
|---|---|
| v1.11.6 | 1.88.1 |
3. 設定ファイル（今回: ExtensionServiceConfig）
3.1 common.yaml（Extension追加）
machine:
# Tailscale Extension
# Talos v1.11.x 対応バージョン: 1.88.1
install:
extensions:
- image: ghcr.io/siderolabs/tailscale:1.88.1
3.2 tailscale-patch.yaml（ExtensionServiceConfig形式）
apiVersion: v1alpha1
kind: ExtensionServiceConfig
name: tailscale
environment:
- TS_AUTHKEY=tskey-auth-XXXXXXXXXX
- TS_EXTRA_ARGS=--advertise-tags=tag:k8s-node
- TS_ROUTES=10.0.0.0/24,10.96.0.0/12,10.244.0.0/16
詳細は Tailscale on Talos 公式ドキュメント を参照。
4. ハマったポイント
4.1 古い情報を鵜呑みにした
最初、ネット上の古い記事を参考に machine.files で設定ファイルを配置する方法を試した。
しかし Talos v1.7 以降は ExtensionServiceConfig が推奨されており、うまく動作しなかった。
教訓: 公式READMEを最初に読みましょう
4.2 横着して一括適用
そして、動作確認もせず全4ノードに一斉適用してしまった。
# やってしまったこと（NG）
for node in 10.0.0.200 10.0.0.201 10.0.0.202 10.0.0.203; do
talosctl apply-config --nodes $node --file *.yaml
done
「1台ずつ確認するのは面倒」という横着が招いた典型例ですね。。。
結果:
- 全ノードが設定エラーで起動不能に
- Control Plane が落ちてtalosctlも使用不能
- etcdクォーラム喪失
- ホストサーバー（Hyper-V）も高負荷でRDP不能に（当時なんもできなくてという感じでした）
5. 正しい手順（推奨）
5.1 ローリングアップデート
# Step 1: Worker 1台目
talosctl apply-config --nodes 10.0.0.201 --file worker.yaml
# Step 2: 復旧を確認（数分待つ）
talosctl --nodes 10.0.0.201 health --wait-timeout 5m
# Step 3: Tailscale Admin Consoleで接続確認
# Step 4: 問題なければ次のWorker
talosctl apply-config --nodes 10.0.0.202 --file worker.yaml
talosctl apply-config --nodes 10.0.0.203 --file worker.yaml
# Step 5: 全Worker完了後、最後にControl Plane
talosctl apply-config --nodes 10.0.0.200 --file controlplane.yaml
5.2 なぜローリングが重要か
| 一斉適用 | ローリング |
|---|---|
| 全ノードが同時に落ちる | 1台ずつ確認しながら進める |
| etcd クォーラム喪失 | クォーラム維持 |
| 問題切り分け困難 | 問題発生箇所が明確 |
| 復旧に時間がかかる | 途中で止められる |
6. セキュリティ
6.1 Git に含めないファイル
# .gitignore
talos/patches/tailscale-auth.yaml # Auth Key
talos/secrets.yaml # クラスタシークレット
talosconfig # talosctl 認証情報
6.2 secrets.yaml のバックアップ
secrets.yamlは障害時の復旧に必須。1Password 等にバックアップ推奨。
7. まとめ
学んだこと
- 公式READMEを読む - 古い記事やAIのアドバイスより公式ドキュメントを優先
- 横着しない - 必ずローリングアップデートで1台ずつ確認
振り返り
- 今思えば、最初からk8s Operator方式で試しておけばよかったかもしれない。Podとして動作確認してから、問題なければ基盤側（Extension）に適用するほうがスムーズだったが、のちのやりたいことを考えると全台導入のほうがあとのことが、楽だったので判断としてはいつどうするかの違いでしたねー
Day8のセキュリティ確認の前にやらかしクラスタを作り直していたので、なかなかヒーヒー言いながらの作業でした😂