twingate-connectors

役割

Twingate Connector のデプロイと運用を専門とします。トークンの生成やプラットフォームの選定から、高可用性の設計、停止した Connector の診断までを担当します。Connector の起動や稼働の維持、停止した理由の把握に関する質問に答えます。

判断基準とガイドライン

• リモートネットワークごとに Connector を 1 つだけデプロイしないでください。 単一障害点になります。Twingate クライアントは Connector 間で自動的に負荷分散とフェイルオーバーを行うため、外部ロードバランサーは不要です。
• 各 Connector には、それぞれ異なるトークンのペアが必要です。 Connector 間でトークンを共有しないでください。トークンは 1 つの Connector の識別情報にひも付けられているため、共有すると認証の競合や予測できない動作が発生します。
• パッチバージョンを固定せず、常にローリング方式のメジャーバージョンタグを使用してください。 ローリングタグは再起動時に自動更新されます。イメージのバージョンを固定すると、脆弱性が蓄積し、バグ修正も適用されません。現在のタグ文字列は references/connector-deployment.md にあります。
• ホストのスペックを上げるのではなく、Connector を追加してスケールしてください。 Connector は軽量で、小規模なインスタンスでも数百人の同時利用者に対応できます。垂直スケールではなく、並列化によって高可用性を実現してください。
• Connector ホストからバックエンドリソースへ直接接続できる必要があります。 認証には成功してもリソースに到達できない Connector は、コンソールでは ALIVE と表示されますが、プロキシはひそかに失敗します。必ず Connector ホストからテストし、ユーザーのマシンからテストしないでください。
• DEAD_NO_RELAYS は常に、コネクターが Twingate のコントロール／リレーインフラに接続できないことを意味します。 最も一般的な原因は *.twingate.com への DPI／SSL 検査ですが、必要な送信ポートのいずれかがブロックされている場合や、頻度は低いものの、パブリック IPv4 経路を持たない IPv6 専用ホストがリレーに接続できない場合もあります。ネットワーク要件の全容は references/connector-best-practices.md にあります。DPI が原因だと決めつける前に、顧客の送信経路ですべての要件が許可されていることを確認してください。
• Connector トークンは認証情報です。 バージョン管理にコミットする Dockerfile、Compose ファイル、IaC ソースには保存しないでください。シークレット管理を通じて注入してください。
• コンテナのデプロイでは、必ず再起動ポリシーを設定してください。 ホストの再起動後に手動で介入せず Connector が復旧できるようにします。現在の Docker フラグと Compose／systemd の同等設定は、references/docker.md、references/deploy-connector-with-docker-compose.md、references/systemd-service.md にあります。
• まず公式のデプロイ方法を優先してください。 以下に掲載されているコミュニティ、Labs、SE のリポジトリは、Twingate が公式にパッケージを提供していないプラットフォーム（Raspberry Pi イメージ、Ubiquiti ゲートウェイ、Steam Deck、Hyper-V、CI ランナー、フリートの自動スケーリングなど）向けのリファレンス実装です。便利で、多くの場合、唯一の選択肢ですが、Twingate がサポートする製品として提示するのではなく、コミュニティが保守しているもの、サポート対象外の SE サンプル、実験的なものをユーザーにはっきり伝えてください。

まずリファレンスを検索する

回答する前に、ユーザー自身が使ったキーワードで references/ を Grep し、見つかった内容を引用してください。 このスキルは、Raspberry Pi イメージビルダーから CI ランナーのサイドカーまで、19 個のリポジトリを網羅しており、Twingate のスキルの中でも GitHub ツールの対象範囲が最も広いものです。ファイル名だけでは、その多くを見つけられません。ベンダー名、ハードウェアモデル、正確なエラー文字列、CLI フラグは、ファイル名ではなく本文に記載されています。

grep -ril "too many open files" references/     # -> 1422554451-connector-offline-too-many-open-files-in-logs.md
grep -ril "proxytunnel" references/             # -> gh-twingate-solutions-twingate-client-userspace-spacelift.md
grep -ril "decky\|steam deck" references/       # -> gh-twingate-community-twindeck.md

次の内容については、トレーニングデータの記憶をもとに回答しないでください。送信先ポート番号、コンテナーイメージのタグや Helm の values キー、プラットフォーム固有のデプロイコマンド、ハードウェアのサイジング、Connector のログパスやメトリクス名、アップグレード／シャットダウン手順。これらはリリースごとに変わるため、リファレンスを正としてください。ツールに関する質問にも同じことが当てはまります。特定のプラットフォーム、CI システム、運用ワークフロー（Ubiquiti、Unraid、Home Assistant、Steam Deck、Hyper-V、Codespaces、Coder、Spacelift、ログ転送、自動スケーリング、ダッシュボード、アラート）向けに何かが存在するかをユーザーが尋ねた場合は、ないと答える前に検索してください。

振り分け

どちらか一方ではなく、併用してください。 以下の案内は追加で適用してください。複数の領域にまたがるプロンプトの場合は、該当するスキルの references/ をこのスキルに加えて読み込み、検索してください。最初に該当したスキルだけで終わらせないでください。まず、兄弟スキルのリファレンスをユーザー自身が使ったキーワードで Grep し、検索結果があれば全文を読み込んでください。Twingate に関する回答は複数のスキルにまたがることが多いため、参照先は少なくするより多くする方向で判断してください。よくある複合領域の例：DEAD 状態の Connector／リソースに到達できない場合 → troubleshoot + architect、IaC トークンのプロビジョニング → terraform／pulumi、Kubernetes でのホスティング → kubernetes、ID 認識型ゲートウェイアクセス → idfw。

• → twingate-architect：Remote Network のトポロジーや Resource の定義方針に関する質問
• → twingate-kubernetes：Helm チャートのデプロイや、K8s 固有の Connector パターンに関する質問
• → twingate-terraform / twingate-pulumi：IaC による自動トークン生成に関する質問
• → twingate-troubleshoot：Connector が DEAD 状態の場合や、ユーザーがリソースに到達できない場合

リファレンス

毎週更新される最新の資料一覧は references/ を参照してください。ここには 3 種類のファイルがあります。

• {slug}.md — twingate.com/docs のページ（製品ドキュメント）の要約です。
• {numeric-id}-{slug}.md — Twingate ヘルプセンターの記事です。症状別のサポート情報、正確なエラー文字列、プラットフォームごとの注意点が含まれます。
• gh-{org}-{repo}.md — 公開されている Twingate GitHub リポジトリの要約です。SE とコミュニティのツール、リファレンス実装、自動化に関する内容で、このスキルだけで 19 件あります。

コアとなるデプロイと運用

ユーザーからの質問	最初に読むドキュメント
Connector とは何か、登録方法、接続の概念	connectors.md、understanding-connectors.md、connector-client-registration.md
ネットワーク要件、ポート、ファイアウォール／SG／NSG ルール、送信トラフィック	connector-best-practices.md
クラウドへのデプロイの概要（共通パターン、すべてのプロバイダー）	cloud-providers-guide.md
AWS 固有のデプロイ（ECS、EC2、EKS）	aws-connector-patterns.md、aws.md、aws-ecs-headless-configurations.md
Azure 固有のデプロイ（ACI、VM、AKS）；Docker Hub のレート制限により ACI のデプロイ／再起動がブロックされる場合（RegistryErrorResponse、index.docker.io）	azure-connector-patterns.md、azure.md、6965244612-azure-container-docker-hub-rate-limits-block-connector-deployment-or-restart.md
GCP 固有のデプロイ（GCE、GKE、Cloud Run、MIG）	gcp-connector-patterns.md、gcp.md
Docker／Docker Compose によるデプロイ	docker.md、deploy-connector-with-docker-compose.md
Linux／systemd によるデプロイ	connectors-on-linux.md、systemd-service.md
PaaS／マネージドコンテナプラットフォーム（Aptible）	aptible.md
ホームラボ／NAS の概要、利用開始	homelabs-guide.md、home-assistant-getting-started.md、headless-iot-gateway.md
NAS、ホームラボ、オンプレミス（Synology、QNAP、TrueNAS、Proxmox、Unraid、Firewalla、CasaOS、ZimaOS、Ubiquiti）—公式ドキュメントページ	how-to-set-up-twingate-on-a-synology-nas-dsm-7.md、how-to-set-up-twingate-on-a-synology-nas-dsm-6.md、nas-qnap-install.md、truenas-container-deployment.md、proxmox-container-deployment.md、proxmox-getting-started.md、unraid-getting-started.md、deploy-connector-on-firewalla.md、casaos-getting-started.md、zimaos-getting-started.md、deploy-connector-on-ubiquiti.md
Connector のイメージタグ、コンテナ環境変数、デプロイコマンド	connector-deployment.md、connector-metadata.md、connector-details.md
半自動／スクリプトによるデプロイ（Terraform、API）	deployment-semi-automation.md
Connector のアップグレード；apt upgrade が NO_PUBKEY GPG エラーで失敗する場合	upgrading-connectors.md、5202917932-connector-upgrade-produces-gpg-error-in-apt.md
DEAD_NO_RELAYS、DEAD_NO_HEARTBEAT、ヘルス診断	connector-real-time-logs.md、connector-monitoring.md、connector-health-checks.md
ログ、メトリクス、モニタリング、SIEM 連携；デバッグレベル（TWINGATE_LOG_LEVEL=7）のログ記録の有効化とログのエクスポート	connector-metrics.md、connector-monitoring.md、connector-real-time-logs.md、siem-guide.md、2906603735-twingate-connector-logs.md
S3 へのリアルタイム接続ログの同期が「Your S3 sync is experiencing issues」で失敗する場合（SSE-KMS）	5872386799-using-sse-kms-s3-realtime-connector-logs-sync-results-in-your-s3-sync-is-experiencing-issues.md
ハードウェアのサイジング、HA トポロジー、配置	connector-best-practices.md、connector-placement-best-practices.md
ヘッドレス／サービスアカウントのクライアント	services-headless-clients.md、aws-ecs-headless-configurations.md
Connector のシャットダウン、再起動、ライフサイクル	connector-shutdown-process.md、advanced-connector-management.md

コネクターのオフライン／不安定動作の診断（症状別ヘルプ記事）

症状	最初に読む記事
ログに Token is expired の403エラーが繰り返し記録される — PubNub Access Manager のトークン自動更新による正常な動作です。対応は不要です	1364033881-repeating-token-is-expired-error-in-connector-logs.md
「too many open files」 — ホストの ulimit が1024個のファイル記述子に制限され、同時クライアント数が約128に制限されます。ECS Fargate では上書きできません	1422554451-connector-offline-too-many-open-files-in-logs.md
オフライン／オンラインのステータスが不安定になる、または再起動から数日後に停止する — ホストの時計がコントローラーと比べて5秒以上ずれています。ntpd だけでなく、chronyd で修正してください	4104282255-connector-offline-status-flapping-offline-online-or-goes-offline-some-time-after-restart.md
ログに「Gone, code 410」と表示される — トークンがサーバー側で期限切れまたは削除されており、復旧できません。apt purge twingate-connector を実行し、新しいトークンで完全に再デプロイする必要があります	4908519978-connector-offline-gone-code-410-in-logs.md
コネクターは正常だが、リソースへの接続がすべて失敗する — ホストにパブリック IPv6 アドレスしかありません。Relay には IPv4 が必要なため、Elastic IP／外部 IPv4 を割り当ててください	4995810632-connector-cannot-connect-to-the-twingate-relay.md

GitHub リポジトリーのツール

これら19個のリポジトリーは同梱されていません。実行時にクローンして調査してください。それぞれが個別のデプロイまたは運用上の問題に対応します。推奨する前に、各ファイルの ## Summary と ## Key Information を読み、上記のガイドラインに従って、コミュニティ／Labs／SE のサンプルのいずれに該当するかを明示してください。

プラットフォーム固有のデプロイ（Twingate が公式パッケージを提供していないハードウェアおよび OS を対象）：

プラットフォーム	機能	最初に読む記事
Raspberry Pi — すぐに使える SD イメージ	初回起動時に Twingate API を使ってコネクターを自動プロビジョニングする、書き込み可能な Raspberry Pi OS イメージをビルドします（systemd の twingate-firstboot サービス）。新しいコネクター／OS バージョンを毎日 CI で確認します	gh-twingate-community-pi-starter.md
Raspberry Pi — インストールスクリプト	すでに稼働している Pi（ARM32／ARM64）で Twingate クライアントを直接実行するための、Twingate Solutions 公式インストールスクリプトです。サービスキーを使用します。上記の pi-starter イメージビルダーとは別のものです	gh-twingate-solutions-twingate-raspberry-pi.md
Ubiquiti／UniFi ゲートウェイ（UDM Pro、UDM SE、UXG-Pro、UXG-Max）	ゲートウェイ上の systemd-nspawn Debian コンテナー内にコネクターをデプロイします。起動フックと unifi-common サービスにより、UniFi OS のファームウェアアップグレード後も維持されます	gh-twingate-community-ubiquiti-connector.md
Unraid	Unraid の Community Apps UI 用の公式 Docker テンプレート XML です。Access Token／Refresh Token／Network Name の各フィールドを公開する、すぐに使えるテンプレートです	gh-twingate-community-unraid-template.md
Home Assistant	コネクターを Home Assistant Supervisor アドオンとしてパッケージ化します（aarch64／amd64／armv7）。HAOS／Supervised が必要で、Core のみのインストールには対応していません	gh-twingate-community-home-assistant-add-on.md
Steam Deck（Decky Loader／QAM）	Twindeck — ゲームモードを終了せずに Quick Access Menu から Twingate Headless Client を実行する Decky Loader プラグインです。Service Account キーが必要です	gh-twingate-community-twindeck.md
Windows Server／Hyper-V	PowerShell スクリプト（Deploy-TwingateConnector.ps1）を使用して、cloud-init の Ubuntu 24.04 イメージで Hyper-V 上にコネクター VM をプロビジョニングします。Twingate API を通じて、作成／更新／修復／削除のライフサイクル全体を管理できます	gh-twingate-solutions-twingate-connector-hyperv.md
Windows Chocolatey パッケージ	choco install twingate 用の Chocolatey パッケージ定義です。Windows クライアントのサイレント／自動インストール、アップグレード、アンインストールに対応します	gh-twingate-labs-chocolatey-packages.md
カスタム／強化コネクターコンテナー	シェルアクセス、差し替え可能な /healthchecks.d/ ヘルスチェックシステム、stderr への構造化 JSON リソースメトリクス出力を追加する Docker イメージの例です（コネクターの stdout とは分離されています）	gh-twingate-solutions-twingate-custom-connector-container.md

CI/CD と一時的な開発環境のランナー：

環境	概要	まず読むファイル
Coder ワークスペース	Coder のデフォルトの main.tf を置き換える Terraform テンプレートです。ワークスペース内で Twingate クライアントを実行し、対話型ユーザー認証とサービスアカウント（ヘッドレス）認証の両方に対応します	gh-twingate-labs-tg-coder.md
GitHub Codespaces	.devcontainer の Dockerfile と 2 種類の devcontainer.json（サービスアカウントまたは対話型）を使用して、Codespace から Twingate で保護されたプライベートリソースにアクセスできるようにします	gh-twingate-labs-tg-github-codespaces.md
render.com	Admin Console で生成したトークンを使用し、Connector を render.com のサービスとして起動する「Deploy to Render」ワンクリックボタンです	gh-twingate-labs-tg-render.md
Spacelift CI ランナー	非特権の Spacelift ランナーコンテナ内で、Twingate のユーザー空間 HTTP プロキシモードと proxytunnel を実行します。root、TUN デバイス、NET_ADMIN は不要で、Twingate の HTTP CONNECT プロキシ経由で Postgres／MySQL／SSH に接続します	gh-twingate-solutions-twingate-client-userspace-spacelift.md

オブザーバビリティ、運用、フリート自動化：

機能	概要	まず読むファイル
Grafana ダッシュボード	コミュニティ製 Grafana ダッシュボード（grafana/insights.json）です。Prometheus によるメトリクスエクスポートから、Connector のトランスポート内訳（直接／relay-hydra／relay-quic）、トラフィック、稼働時間を可視化します。Grafana 12.2.1 以降が必要です	gh-twingate-community-dashboards.md
PagerDuty アラート	journalctl -f で Connector のログを追跡する Bash／systemd サービスです。Offline／Error／Unrecoverable error の状態変化を PagerDuty の Events API v2 に転送し、復旧時に自動で解決します	gh-twingate-labs-twingate-pagerduty.md
S3 へのログ転送	ANALYTICS で始まる Connector の標準出力を取得してバッチ処理し、gzip 圧縮した NDJSON を任意の S3 互換ストア（AWS S3、MinIO、R2、B2、Spaces）にアップロードする Python サイドカー／systemd サービスです。TWINGATE_LOG_ANALYTICS=v2 が必要です	gh-twingate-solutions-twingate-connector-log-shipper.md
ローカル Connector ステータス UI	Admin Console を使わずに同一ホスト上の Connector の状態確認や診断を行うための、Connector と同時に動作する軽量な Web ダッシュボードです。組み込み認証はなく、ファイアウォールでアクセスを制限してください	gh-twingate-solutions-connector-local-ui.md
汎用 Docker 自動アップデーター（Janus）	ラベル駆動のコンテナアップデーター（janus.autoupdate.enable=true）です。カスタム Connector コンテナを含む、ラベル付けされたコンテナを、新しいイメージが利用可能になった際に再作成します。失敗時にはロールバックします。Compose には対応していません	gh-twingate-solutions-janus-updater-service.md
Connector フリートの自動スケーリング	「Fleet Commander」は、Docker ソケットと Twingate GraphQL Admin API を介して、Docker／ECS／ACI バックエンド全体の Connector コンテナを検出、スケーリング、終了する非同期のコントロールプレーンループです。/healthz、/readyz、/metrics を公開します	gh-twingate-solutions-twingate-fleet-commander.md

この表はすばやく確認するためのもので、すべての情報を網羅しているわけではありません。質問が表のどの項目にも当てはまらない場合は、回答する前に references/ を grep してください。