ngrok-surfaces

ユーザーの環境で ngrok を適用する

ジョブスキルは、ngrok-engine でエンドポイントの種類とポリシーの両方、つまり 何を 構築するかを決定します。このスキルは、どこに 適用するかを決め、具体的な手順に引き継ぎます。

設定そのものは、どの環境でも変わりません。 ポリシー本文、エンドポイント URL、内部ホスト名は同じです。異なるのはラッパーだけです。したがって、ユーザーが環境を切り替えたからといって、ポリシーを再導出しないでください。ラッパーを付け替えてください。

環境を選ぶ

質問するのではなく、ユーザーのプロジェクトを見て判断してください。

手掛かり	環境	参照先
ターミナル、ポート、または「URLだけください」	エージェント CLI / ngrok.yml	references/cli.md
ngrok の依存関係がある package.json、pyproject.toml、go.mod、または Cargo.toml。または、プロセスとともにエンドポイントを起動・停止する必要がある	SDK	references/sdk.md
テナント／サンドボックス／デバイスごとにリソースを実行時に作成するコントロールプレーン	REST API	references/api.md
*.tf ファイル	Terraform	references/terraform.md
Chart.yaml、kustomization.yaml、k8s マニフェスト	Kubernetes Operator	references/kubernetes-operator.md

どれにも当てはまらない場合、単発の作業には CLI が安全なデフォルトです。

実際に違いを生む軸

環境の違いは、リソースを作成するタイミングと、そのライフサイクルを管理するものです。

• CLI と SDK は、ワークロード内から実行時にリソースを作成します。エージェントまたはプロセスの稼働中は存続します。
• Terraform と Operator は、デプロイ時に、事前に把握されていてリポジトリにチェックインされた一連のエンドポイントを宣言します。
• REST API は、ワークロードの外部から実行時にリソースを作成します。事前には把握されていない一連のエンドポイント、つまりサンドボックス、顧客、またはデバイスごとに 1 つずつ、数千件のエンドポイントを作成する場合に使います。

Terraform と API は互換性があるように見えますが、そうではありません。「自分のアカウントにはこの 3 つのエンドポイントがある」は Terraform です。「すべてのサンドボックスに 1 つずつ割り当てる」は API です。後者については provision-sandbox-access を参照してください。

1 つのセットアップで、2 つを使うこともよくあります。API または Terraform でパブリッククラウドのエンドポイントをプロビジョニングし、CLI または SDK でワークロード内から内部エンドポイントを起動します。両者は合意済みの内部ホスト名で接続します。

認証方法は環境によって異なります

• CLI と SDK は エージェントの authtoken（NGROK_AUTHTOKEN）を使用します。これはエージェントセッションの開始にのみ使われます。
• REST API、Terraform、Operator は API キーを使用します。アカウントを管理するためのものです。Operator には両方が必要です。
• ngrok MCP サーバー は OAuth を使用し、ユーザーのロールでユーザーとして動作します。API キーなしでアカウントリソースを作成できます。次のセクションを参照してください。

これらは互換性がなく、影響範囲も大きく異なります。認証エラーで呼び出しに失敗した場合は、認証情報をローテーションする前に、どの認証情報が使われているかを確認してください。ngrok-setup を参照してください。

アカウントリソース：MCP サーバーまたは API キー

ジョブによっては、ワークロードの外部にあるアカウントリソース（予約済みドメイン、ボールトとそのシークレット、クラウドエンドポイントなど）を作成します。これらを作成するには、ngrok MCP サーバーまたは API キーが必要です。該当する最初の方法を使用してください。

1. ユーザーが ngrok をコードとして管理している場合（*.tf ファイル、Operator マニフェストなど）。リソースをそこに追加して、セットアップを再現可能な状態に保ちます。状態の確認にのみ MCP サーバーを使用してください。
2. ngrok MCP サーバーが接続されている場合（platform_whoami などのツールを呼び出せる場合）。MCP サーバーでリソースを作成し、ユーザーに API キーを求めないでください。まず platform_whoami を呼び出します。ユーザーのロールとプランが表示されます。ロールでは変更できない場合や、プランにその機能が含まれていない場合、サーバーは書き込みを拒否します。そのため、実行を試みる前にその旨をユーザーに伝えてください。
3. MCP サーバーが接続されていない場合。ユーザーが設定した API キー（ngrok-setup を参照）を使って ngrok api を使用するか、ダッシュボードを使用します。ここでは ngrok MCP サーバーを使えば API キーが不要になることを一度ユーザーに伝えてから、作業を続けてください。

リソース	MCP サーバーのツール	API キーを使う CLI
予約済みドメイン	gw_reserve_domain	ngrok api reserved-domains create
ボールト	gw_create_vault	ngrok api vaults create
シークレット	gw_create_secret	ngrok api secrets create
クラウドエンドポイント	gw_create_cloud_endpoint、変更するには続けて gw_update_cloud_endpoint	ngrok api endpoints create

MCP サーバーを使用する場合：

• gw_create_secret は値を受け取りません。ユーザーが値を入力するダッシュボードのリンクを、ステータス awaiting_user_action とともに返します。ユーザーがフォームを保存するまで、シークレットは作成されません。結果に含まれる started_at を指定し、同じ引数でツールを再度呼び出してください。ステータスが complete になってから、シークレットを読み取るポリシーを作成してください。
• クラウドエンドポイントを作成する前に、endpoint_type を cloud に設定して、そのポリシーを gw_validate_traffic_policy で検証してください。ユーザーのプロジェクト内のファイルにポリシーを保存し、作成したリソースの ID をユーザーに伝えてください。これにより、ユーザーはあなたがいなくてもセットアップを再作成または削除できます。

この順序は、ユーザーのために行うセットアップに適用されます。コントロールプレーンなど、実行時にリソースを作成するコード（provision-sandbox-access を参照）では、常に API キーを使用します。

エージェント向けの注意事項

• シェルを使用できる場合は、自分でコマンドを実行し、手順ではなく結果を返してください。
• ngrok MCP サーバーが接続されている場合、どのサーフェスに適用する場合も、適用前後に MCP サーバーを使って状態を確認してください。gw_list_endpoints または URL を指定した get_resource でエンドポイントが稼働中であることを確認し、gw_validate_traffic_policy でポリシーを確認します（ngrok-engine を参照）。
• ポリシーは独立した policy.yaml に保存し、そこを参照してください。そうすることで、ユーザーが後から別のサーフェスを追加しても、ポリシーを移植できます。通常、ユーザーは別のサーフェスも追加します。
• Kubernetes Operator は TCP エンドポイントをサポートしていません。ユーザーが k8s で TCP を必要としている場合は、後から判明する前にその点を伝えてください。
• 設定を記憶だけに頼ってサーフェス間で移植しないでください。形式が異なるため、ネットワークの問題に見える失敗が起こる可能性があります。対象のサーフェスのリファレンスファイルを読んでください。