Headscale徹底解説：プライベートネットワークを自社インフラで完結させる方法と導入レシピ


Headscale徹底解説：プライベートネットワークを自社インフラで完結させる方法と導入レシピ

juanfont/headscale

2025-10-29

Headscaleは、一言で言うと、Tailscaleのコントロールサーバーを自分でホストできるようにしたオープンソースの実装です。

Tailscaleは、設定なしで使えるVPNのようなもので、デバイス間を安全に接続してくれますよね。その「誰と誰をつなげるか」「どのデバイスを許可するか」といった制御（コントロール）を担っているのが、本来Tailscale社が運営しているコントロールサーバーです。

Headscaleを使うということは、この制御機能をご自身のサーバーでホストし、完全に管理下に置けるということなんです。

Headscaleは、特に以下のような分野でソフトウェアエンジニアの強力な味方になります。

プライベートなアクセス
外部に公開したくない開発用データベース、ステージング環境のWebサーバー、CI/CDツール（例
Jenkins、GitLab Runner）などに、セキュアなTailscaleネットワーク経由でのみアクセスできるようになります。

シンプルな認証
複雑なファイアウォール設定やVPNクライアントのセットアップが不要。Headscaleで認証されたデバイスからなら、まるでローカルネットワークにいるかのようにアクセスできます。

ユーザー数制限の解消
Tailscaleの無料プランや一部有料プランにあるノード数（デバイス数）の制限を気にせずに、社内やチーム内の全サーバー・メンバーを接続できます。

データ主権
ネットワーク制御に関わるメタデータを、外部のサービスではなく、自社のインフラ内に留めることができます。

API連携
Headscaleは豊富なRESTful APIを提供しており、新しいサーバーをプロビジョニング（準備）した際などに、自動的にTailscaleネットワークに参加させるといった自動化が容易になります。

SSO（シングルサインオン）連携
独自の認証プロバイダやLDAPなどと統合し、Tailscaleネットワークへのアクセスを自社の既存の認証システムで統一的に管理できます。

Headscaleの導入は、主にDockerを使うのが最も簡単で推奨されます。

以下のdocker-compose.yamlファイルを用意します。

version: '3.8'

services:
  headscale:
    # juanfont/headscale の最新安定版イメージを使用
    image: headscale/headscale:latest
    container_name: headscale
    restart: unless-stopped
    # 外部からポート8080（HeadscaleのAPI/Web UI）と
    # 41641/UDP（Tailscaleの制御通信）にアクセスできるようにする
    ports:
      - "8080:8080"
      - "41641:41641/udp"
    # 設定ファイルとデータベースを永続化
    volumes:
      - ./config:/etc/headscale
      - ./data:/var/lib/headscale
    environment:
      # 環境変数で基本的な設定を上書き（例：サーバーの外部URL）
      # ここにはHeadscaleをデプロイするサーバーのグローバルIPまたはドメイン名を設定
      - HEADSCALE_SERVER_URL=http://<あなたのサーバーのパブリックIPまたはドメイン>:8080
      # データベース（SQLite）のパス
      - HEADSCALE_DB_PATH=/var/lib/headscale/db.sqlite

【実行ステップ】

上記ファイルを保存し、configとdataディレクトリを作成します。

configディレクトリ内に、HeadscaleのGitHubリポジトリから取得できる最小限の設定ファイル（config.yamlなど）を配置します。

ターミナルで以下のコマンドを実行します。

docker compose up -d

これでHeadscaleサーバーが起動し、ポート8080でAPIが利用可能になります。

Headscaleサーバーに接続するためのユーザーを作成します。

# Dockerコンテナ内でコマンドを実行
docker exec headscale headscale users create dev-team

Headscaleの真価は、そのAPIを利用した自動化にあります。ここでは、新しいサーバーをネットワークに自動登録するためのマジックサイン（招待コード）を発行する例を見てみましょう。

Tailscaleクライアントをインストールしたサーバーで利用する、ネットワーク参加用の使い捨てキーを発行します。

# ユーザー「dev-team」用に、1回だけ使えるキーを生成
docker exec headscale headscale preauthkeys create dev-team --reusable=false --expiration=24h

出力されるキー（例
tskey-aBcDeFgHiJkLmNoPqRsT）をコピーします。

新しくプロビジョニングしたサーバーの起動スクリプトやAnsibleのPlaybook内で、以下のコマンドを実行します。

# 1. Tailscaleをインストール（OSによってコマンドは異なる）
# ...

# 2. HeadscaleのURLと招待キーを指定して接続
# <Headscaleの外部URL> は、docker-compose.yamlで設定した値と同じ
tailscale up \
  --login-server http://<Headscaleの外部URL>:8080 \
  --authkey <ステップ1で生成したキー>

これで、サーバーは手動でのブラウザ認証なしに、Headscaleが管理するプライベートネットワークに自動で参加します。これにより、インフラのデプロイが非常にスムーズになります。

Headscaleは、自社のインフラ環境をよりセキュアに、より自律的に制御したいソフトウェアエンジニアにとって、非常に価値のあるツールです。


juanfont/headscale