tailscale-docker-debug

Tailscale Docker のデバッグ

Docker コンテナ内の Tailscale 接続と DNS の問題を診断して修正します。 コンテナの実行モードから MagicDNS の名前解決まで、デバッグ手順全体を カバーする 6 つのチェックを順番に実行します。

このスキルでできること

1. コンテナがカーネルモードとユーザースペースモードのどちらで実行されているかを検出します。
2. TUN インターフェースが Tailscale IP を持って存在することを確認します。
3. DNS リゾルバーチェーンをチェックして、クエリの誤ったルーティングを検出します。
4. 100.100.100.100 がコンテナの Tailscale 経由でルーティングされることを確認します。
5. ホストとコンテナ間のマルチテールネットの競合を検出します。
6. 名前解決テストで MagicDNS のエンドツーエンドの動作を検証します。

よくあるきっかけ

• Docker／Podman コンテナ内で「DNS が動作しない」とユーザーから報告がある
• ホストはあるテールネットに接続し、コンテナは別のテールネットに接続している
• Compose ファイルに NET_ADMIN と /dev/net/tun が設定されているのに、Tailscale が 依然としてユーザースペースモードで実行される
• docker run から docker compose への移行によって TUN が動作しなくなる

診断ワークフロー

各ステップを順番に実行します。最初に失敗した時点で停止し、 続行する前に修正を適用してください。後続のステップは先行するステップに依存します。

ステップ 1 — コンテナの実行モードを検出する

docker logs <container> 2>&1 | grep -iE "tun|userspace|netstack"

成功： ログに tun "tailscale0" と表示されます。カーネルモードです。ステップ 2 に進みます。

失敗： ログに --tun=userspace-networking と表示されます。公式の tailscale/tailscale イメージは、機能に関係なく containerboot を介してデフォルトでユーザースペースモードになります。

修正： 環境変数に TS_USERSPACE=false を設定します。/dev/net/tun には volumes: ではなく devices: を使用します。cap_add: [NET_ADMIN, SYS_MODULE] を追加します。 設定全体については references/compose-configuration-matrix.md を参照してください。

ステップ 2 — TUN インターフェースの存在を確認する

docker exec <container> ip addr show tailscale0

成功： インターフェースに 100.x.y.z/32 アドレスが表示されます。ステップ 3 に進みます。

失敗： TS_USERSPACE=false を設定しても tailscale0 インターフェースがありません。

修正： Compose ファイルで /dev/net/tun の設定を volumes: から devices: に変更します。 コンテナ内にメジャー／マイナー番号 10, 200 のデバイスが存在することを確認します。 cap_add: [NET_ADMIN, SYS_MODULE] が設定されていることを確認します。

ステップ 3 — DNS リゾルバーチェーンをチェックする

docker exec <container> cat /etc/resolv.conf

次の 3 点を確認します。

• nameserver — 127.0.0.11（Docker 組み込み DNS）が想定されます
• 外部サーバー — 100.100.100.100 に転送されている必要があります
• search — ホストではなく、コンテナのテールネットに一致している必要があります

失敗の兆候：

• ExtServers: [host(127.0.0.53)] — Docker が Tailscale ではなく ホストの systemd-resolved に転送しています
• 検索ドメインが別のテールネットに属しています

修正： Compose ファイルの各サービスに dns: [100.100.100.100] を追加します。 名前解決の全経路については references/dns-resolver-chain.md を参照してください。

ステップ 4 — 100.100.100.100 のルーティングを確認する

docker exec <container> ip route get 100.100.100.100

成功： tailscale0 またはローカルインターフェース経由でルーティングされます。

失敗： eth0 または Docker ゲートウェイ経由でルーティングされます（例：via 172.18.0.1）。 — DNS クエリがホストに漏れています。

docker exec <container> ss -ulnp | grep 100.100

修正： これはステップ 1（ユーザースペースモード）またはステップ 2 （TUN がない）の症状です。先にそれらを修正してください。

ステップ 5 — マルチテールネットの競合を検出する

docker exec <container> tailscale status | head -1
docker exec <container> grep search /etc/resolv.conf

tailscale status に表示されるテールネットと、resolv.conf 内の検索ドメインを比較します。

失敗： 検索ドメイン（ホストから継承）がコンテナのテールネットと一致しません。 例：ホストは tucuxi-lungfish.ts.net、コンテナは tail9a660c.ts.net に接続しています。

修正： Compose ファイルに dns_search: [<correct-tailnet>.ts.net] を追加するか、 FQDN のみを使用します。根本原因は、Docker がホストの resolv.conf の検索ドメインを継承することです。

ステップ 6 — MagicDNS をエンドツーエンドで確認する

docker exec <container> tailscale dns status | head -3

成功： Tailscale DNS: enabled と表示されます。

失敗： Tailscale DNS: disabled と表示されます。

修正： 環境変数に TS_ACCEPT_DNS=true を設定します。

最終検証：

docker exec <container> nslookup <peer>.<tailnet>.ts.net 100.100.100.100
docker exec <container> ping -c 1 <peer>.<tailnet>.ts.net

両方が成功すれば、コンテナ内で MagicDNS が正しく動作しています。

エラー処理

チェックに失敗した場合は、黙ってスキップしないでください。失敗の具体的な内容と対処法を報告してから、先に進んでください。対処にコンテナの再起動が必要な場合は、コンテナを再作成し（docker compose up -d）、ステップ1からワークフローを再実行するようユーザーに案内してください。

ログメッセージ getting OS base config is not supported は致命的ではありません。Tailscale はコンテナの DNS 設定を直接読み取れません。代わりに compose ファイルで DNS を修正してください。

参考資料

• references/compose-configuration-matrix.md — MagicDNS を使用するカーネルモードの Tailscale に必要な最小限の compose 設定と、設定ごとの詳細
• references/dns-resolver-chain.md — Docker 組み込み DNS を経由する DNS 解決の全経路と、短縮名と FQDN の競合
• references/common-failures.md — 症状から原因と対処法を調べられる一覧表