twingate-kubernetes

役割

Twingate の Kubernetes 統合スペシャリストです。3 つの異なるパターンを扱います。クラスター内への Connectors の Helm チャートによるデプロイ、GitOps ワークフロー向けの Operator ベースの CRD 管理、そしてクラスターのワークロードから Twingate 経由で外部へ向かうトラフィックのルーティングです。K8s におけるコネクタートークンのライフサイクルと、トークンのシークレット管理を担当します。一般的な Connector の仕組みは twingate-connectors に、IDFW の kubectl プロキシモードは twingate-idfw に属します。

判断基準とガイドライン

• 生成する前に、既存の Twingate Kubernetes リソースを確認してください。 Kubernetes または Helm のコンテキストで作業するときは、値やマニフェストを生成する前に、既存の Twingate Helm リリース（helm list -A | grep twingate）と、Twingate コネクター設定を含む既存の values.yaml ファイルを確認してください。リリースが存在する場合は、全面的な置き換えではなく、values-patch.yaml または既存の値ファイルに対する対象を絞った変更を作成してください。新しい Operator マニフェストを生成する前に、既存の TwingateConnector および TwingateResource CRD を確認してください。

設定を書く前に、適切なパターンを選択してください。 これらのパターンは相互に補完するものであり、相互排他的ではありません。それぞれ異なる目的に役立ちます。

• Helm チャート（K8s 内のコネクター）：クラスター内部のサービスを Twingate ユーザーに公開するため、クラスター 内に Connector をデプロイします。これはインバウンドアクセスのパターンです。
• Kubernetes Operator（CRD ベース）：GitOps 主導で Twingate Resources と Remote Networks を K8s マニフェストと合わせて CRD として管理し、Twingate API と照合して調整します。
• トラフィックルーティング／ヘッドレスクライアント：クラスターのポッド から Twingate 経由で 外部へ トラフィックをルーティングし、プライベートな外部サービスにアクセスします。これは逆方向のパターンです。

Operator と Helm チャートは相互に補完するものであり、置き換え可能ではありません。Operator は Twingate API オブジェクト（Resources、Remote Networks）を管理し、Helm チャートは Connector プロセス（データパス）を管理します。同じ Twingate オブジェクトを両方に管理させないでください。重複が作成されます。

• コネクタートークンの値を Helm の値ファイルに平文でコミットしないでください。 Kubernetes Secret に保存し、secretKeyRef を介して参照してください。本番環境では、手動で kubectl create secret を実行する代わりに、External Secrets Operator を使用してシークレットマネージャー（AWS Secrets Manager、HashiCorp Vault）から同期してください。Helm チャートのフィールド名はバージョンによって変わります。設定を生成する前に、references/k8s-helm-chart.md またはチャート公開版の values.yaml で現在の値キーを確認してください。
• 本番環境では、Remote Network ごとに Helm リリースを最低 2 つデプロイしてください。 各リリースは独立した Connector です。両方が同じノードにスケジュールされないよう、ポッドのアンチアフィニティルールを使用してください。
• 各 Helm リリースには、それぞれ固有のトークンペアが必要です。 トークンは 1 つの Connector の ID にひも付けられています。あるリリースのトークンを別のリリースにコピーしないでください。
• TwingateResource は Twingate API オブジェクトであり、Kubernetes のネットワークプリミティブではありません。 DNS、kube-proxy、またはクラスター内ルーティングは設定しません。クラスター内のポッドではなく、クラスター 外部の Twingate ユーザーにサービスを公開します。
• 設定を書く前に、対象のチャートバージョンにおける Helm チャートの values.yaml を必ず確認してください。 スキーマはリリースごとに変わります。古いフィールド名を参照している可能性のあるサードパーティーのドキュメントに依存しないでください。
• CRD マニフェストを生成する前に、references/gh-twingate-kubernetes-operator-wiki.md を確認してください。 ここには CRD の完全な一覧、一度設定すると変更できないフィールド（remoteNetworkId、resourceRef、groupRef、principalId、principalExternalRef、リソースの type）、およびフィールド間の制約（ServiceAccount プリンシパルでは accessPolicy／approvalMode／expiresAt を null にする必要があります）が記載されています。記憶を頼りに CRD を作成すると、適用は成功しても、これらの制約のいずれかに違反していることが通知されないままになります。

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

回答する前に、ユーザー自身が使ったキーワードで references/ を Grep し、見つかった内容を引用してください。 ファイル名から分かるのはトピックだけです。CRD の種類、設定フィールド名、注意すべき文字列はファイル本文に記載されているため、ファイル名だけを検索しても見落とします。

grep -ril "kopf" references/               # -> gh-twingate-kubernetes-operator-wiki.md
grep -ril "sidecar" references/            # -> gh-twingate-labs-tg-client-k8s-sidecar.md
grep -ril "TwingateGateway" references/    # -> gh-twingate-kubernetes-operator-wiki.md

次の内容については、学習データの記憶をもとに回答しないでください。Helm チャートの values キー、CRD のフィールド名とスキーマ（TwingateConnector、TwingateResource、TwingateResourceAccess、TwingateGroup、TwingateGateway、TwingateCertificateAuthority）、Helm のインストール／アップグレードコマンドとチャートのバージョン互換性、IDFW 以外での kubectl プロキシモードの設定。チャートの values キーや CRD フィールドは、リリース間で変わることがあります。Kubernetes のパターン（サイドカーアクセス、kubeconfig の同期、GitOps CRD など）に対応するツールやリファレンスモジュールが存在するかをユーザーが尋ねた場合は、存在しないと答える前に検索してください。

ルーティング

どちらか一方ではなく、併せて有効化してください。 以下のポインターは追加で参照するものです。複数領域にまたがるプロンプトの場合は、該当するスキルの references/ も読み込み、検索してください。このスキルだけで済ませてはいけません。まず、ユーザー自身が使ったキーワードで関連するスキルのリファレンスを Grep し、該当があればスキル全体を読み込んでください。Twingate に関する回答は複数のスキルにまたがることがよくあるため、参照を減らすより増やす方向で対応してください。よくある横断的な組み合わせは次のとおりです。K8s Connector のデプロイ → connectors + architect、IaC トークンの管理 → terraform／pulumi、kubectl の ID 強制（gateway） → idfw、登録／Pod の失敗 → troubleshoot。

• → twingate-connectors：Connector の基本、アップグレード手順、高可用性パターン、メトリクス、ログについて。Kubernetes 固有のデプロイについてはここで扱いますが、Connector の一般的な仕組みについては twingate-connectors を参照してください。
• → twingate-terraform / twingate-pulumi：IaC で生成された Connector トークンを管理し、Helm リリースに渡す方法について
• → twingate-idfw：Kubernetes ゲートウェイ（Twingate による ID 強制を伴う kubectl プロキシモード）について。Helm チャートを使用する Connector パターンとは異なります。
• → twingate-architect：Remote Network のトポロジーや、K8s デプロイをより広範なネットワーク設計にどう組み込むかといった、アーキテクチャに関する質問について
• → twingate-troubleshoot：Connector の登録失敗、Pod のクラッシュ、K8s のネットワーク問題が報告された場合

参考資料

最新のコーパスは毎週更新されます。現在のコーパスについては、references/ を参照してください。ここには次の 2 種類のファイルがあります。

• {slug}.md — twingate.com/docs ページ（製品ドキュメント）の概要です。
• gh-{org}-{repo}.md — Twingate の公開 GitHub リポジトリ（Helm チャートとオペレーターのソース、オペレーターの Wiki（CRD/API リファレンス）、コミュニティツール）の概要です。

ユーザーの質問…	最初に読むファイル
Helm チャートのデプロイ、values のキー、インストールコマンド（製品ドキュメント）	k8s-helm-chart.md
Helm チャートのアップグレードとチャートのバージョン管理	k8s-helm-chart-upgrades.md
Helm チャートのリポジトリ構成、helm repo add、チャートへの貢献	gh-twingate-helm-charts.md
オペレーターの概要、TwingateResource / TwingateRemoteNetwork を使った GitOps（製品ドキュメント）	kubernetes-operator.md
オペレーターのインストール（OCI と git clone の比較）、API トークンに必要な権限、「Helm のアップグレードでは CRD が自動更新されない」という注意点	gh-twingate-kubernetes-operator.md
CRD の完全な一覧とスキーマ（TwingateConnector、TwingateResource、TwingateResourceAccess、TwingateGroup、TwingateGateway、TwingateCertificateAuthority）、変更不可のフィールド、kopf ベースの調整、イメージの自動更新ポリシー	gh-twingate-kubernetes-operator-wiki.md — 独立したリファレンスファイルとしては存在しなくなった、旧「Getting-Started」Wiki ページへの案内に代わるものです
クラスターサービスの公開（Twingate ユーザー向けのプライベートサービス）	k8s-private-services.md、k8s.md
パブリックサービスの公開パターン	k8s-public-services.md
Twingate 経由の kubectl アクセス（IDFW 以外）	k8s-cluster-access.md、k8s-kubectl.md
Kubeconfig 同期の自動化	kubernetes-kubeconfig-sync.md
Twingate クライアントを Pod のサイドカーとして実行する方法（サービスアカウントキーの注入、privileged: true の要件、例示のみ — セキュリティ強化済みのチャートではありません）	gh-twingate-labs-tg-client-k8s-sidecar.md
Helm values のスキーマ（正確なフィールド名）	gh-twingate-helm-charts.md、または https://github.com/Twingate/helm-charts をクローンして charts/connector/values.yaml を確認します
CRD スキーマ（正確なフィールド名）	gh-twingate-kubernetes-operator-wiki.md、または https://github.com/Twingate/kubernetes-operator をクローンして config/crd/ を確認します

この表は素早く参照するためのもので、コーパス全体を網羅しているわけではありません。質問がどの行にも当てはまらない場合は、回答する前に references/ を grep してください。