cloud-provisioning

クラウドプロビジョニング

Cloud API を通じて Elastic Cloud インフラストラクチャをプロビジョニングして実行します。対象は Serverless プロジェクト（作成と運用開始後の操作）、トラフィックフィルター（それらのプロジェクトのネットワークセキュリティ）、および Elastic Cloud Hosted デプロイメントです。Cloud 認証の設定と組織アクセスの管理には、cloud-onboarding スキルを使用してください。

環境設定

このスキルでは、elastic CLI を通じて Elastic Cloud コントロールプレーンを操作します。 elastic CLI がインストールされていない場合は、何に必要かをユーザーに伝えてください。認証情報を推測したり、CLI を使わずに HTTP API を直接呼び出したり、ほかの回避策を試したりしないでください。

コントロールプレーンの操作では、単一のスタックデプロイメントではなく、Elastic Cloud API（組織スコープ）で認証します。 elastic CLI は、Elastic Cloud API キーを OS のキーチェーンに保存するアクティブなコンテキストから認証情報を読み取ります。コントロールプレーンの呼び出しで認証エラーが発生した場合、コンテキストが設定されていないか、Cloud API キーが含まれていません。ユーザーにキーを追加するよう案内し、API キーをチャットに貼り付けるよう求めないでください。

「elastic CLI の Elastic Cloud コンテキストを設定してから、再実行してください。Elastic Cloud API keys で組織レベルのキーを生成し、チャットにシークレットを表示せずに登録してください。」

このスキルでは、cloud: プレフィックスを付けた HTTP 省略形式でコントロールプレーンの操作を記述します（例：GET cloud:/api/v1/organizations、POST cloud:/api/v1/serverless/projects/elasticsearch）。このドキュメントの最後にある操作の表には、それぞれの省略形式に対応する elastic cloud コマンドが記載されています。HTTP API を直接呼び出さず、必ず CLI を使用してください。組織 ID は GET cloud:/api/v1/organizations で確認してください。ユーザーに尋ねないでください。

重要な原則

• シークレットをチャットに表示しないでください。 パスワードや API キーを会話やエージェントの思考内でエコー、記録、再掲しないでください。認証情報は CLI コンテキスト（OS のキーチェーン）に保存し、ユーザーにその場所を案内してください。
• 作成または削除の前に確認してください。 プロジェクトやデプロイメントのリージョンは変更できません。削除は取り消せません。作成、削除、または認証情報のリセットを行う前に、設定を提示して明示的な確認を得てください。
• 管理者認証情報は初期設定時のみ使用します。 作成時またはリセット時に返される admin パスワードは、スコープを限定した API キーを作成する目的にのみ使用します。継続的な Elasticsearch 操作に管理者認証情報を使用しないでください。まずスコープを限定したキーを発行してください。
• 利用可能になるまで待ってください。 新しいプロジェクトやデプロイメントは initializing の状態で開始します。使用する前に initialized になるまで待ってください。
• 認証情報は 2 種類あります。 Cloud コンテキスト（Cloud API キー）は、ここでのコントロールプレーン操作を許可します。プロジェクトまたはデプロイメントの Elasticsearch API キーは、その Elasticsearch エンドポイントに対するデータプレーン操作を許可します。両者を混同しないでください。references/credentials-and-context.mdを参照してください。

---

Serverless プロジェクト

プロジェクトの種類

種類	説明	含まれるサービス
elasticsearch	検索、分析、ベクトル処理	Elasticsearch, Kibana
observability	ログ、メトリクス、トレース、APM	Elasticsearch, Kibana, APM, OTLP
security	SIEM、エンドポイント保護、クラウドセキュリティ	Elasticsearch, Kibana, OTLP

ユーザーのリクエストを適切な種類に対応付けます。暗黙にデフォルトを選ばず、文脈から推測して確認するか、不明確な場合は質問してください。「search」／「elasticsearch」／ベクトル検索 → elasticsearch、「o11y」／ログ／メトリクス／トレース／APM → observability、「SIEM」／検知／エンドポイント → security。

ティアと最適化。 Elasticsearch では、ユーザーが明示的に vector をリクエストしない限り、optimized_for を general_purpose（デフォルト）に設定します。Observability では、product_tier を complete（デフォルト）または logs_essentials に設定します。Security では、製品ライン（security、cloud、endpoint）ごとに product_types のティアを complete（デフォルト）または essentials に設定します。各種類の完全なリクエストボディのスキーマについては、references/api-reference.md を参照してください。

手順：サーバーレスプロジェクトを作成する

1. プロジェクトの種類を確認します。 会話から推測して候補を提示するか、ユーザーに選択を依頼します。種類を仮定したまま先に進まないでください。
2. 構成を確認します。 名前（必須。不明な場合は質問）、リージョン（デフォルトは gcp-us-central1）、および種類に応じたティア／最適化の概要を提示し、明示的な確認を得ます。リージョンが不確かな場合は、まず GET cloud:/api/v1/serverless/regions で候補を一覧表示します。新規プロジェクトを作成できるのは、project_creation_enabled: true のリージョンのみです。リージョンは後から変更できません。
3. プロジェクトを作成します。 確認済みのボディを指定して POST cloud:/api/v1/serverless/projects/{type} を呼び出します。initialized フェーズになるまで待機し、返された認証情報を名前付き CLI コンテキストに保存します（パスワードは OS のキーチェーンに保存し、標準出力やチャットには出力しません）。
4. 準備状況を確認します。 作成処理が準備完了まで待機しなかった場合は、phase が initialized になるまで GET cloud:/api/v1/serverless/projects/{type}/{id}/status をポーリングします。作成レスポンスに含まれる Elasticsearch と Kibana のエンドポイントは共有しても問題ありませんが、パスワードは共有できません。
5. スコープを限定した API キーを作成します。 プロジェクトコンテキストを使用し、POST /_security/api_key（プロジェクトの Elasticsearch エンドポイント）経由で、ユーザーが必要とする権限のみを持つスコープ付き Elasticsearch API キーを作成します。その後、データプレーンでのすべての処理にはこのキーを使用します。elasticsearch-authn スキルが利用可能な場合は、キーのライフサイクル全体の管理に使用してください。

ワークフロー：既存のプロジェクトに接続する

現在のセッションで作成されていないプロジェクトを照会または管理するようユーザーから依頼された場合に使用します。これは Elastic Cloud Serverless プロジェクトのみが対象です。クラスターがセルフマネージドまたは Elastic Cloud Hosted の場合は、Hosted デプロイメント ワークフローを使用するか、この手順をスキップしてください。不明な場合は、「お使いの Elasticsearch インスタンスは Elastic Cloud Serverless プロジェクトですか？」と尋ねてください。

1. プロジェクトを特定します。 種類を推測し、GET cloud:/api/v1/serverless/projects/{type} でプロジェクトの一覧を取得します。ユーザーが指定した情報（名前またはエイリアス）と照合します。一致するものが複数ある場合、または見つからない場合は、候補を提示して確認を求めます。
2. エンドポイントと認証情報を読み込みます。 GET cloud:/api/v1/serverless/projects/{type}/{id} でプロジェクトを取得し、Elasticsearch と Kibana のエンドポイントを確認して、プロジェクトに紐づく CLI コンテキストを選択または作成します。
3. Elasticsearch の認証情報を取得します。 既存のプロジェクト API キーがあれば、GET /_security/_authenticate で検証します（"authentication_type": "api_key" が返されることを想定）。有効なキーがない場合は、ユーザーに確認してから、POST cloud:/api/v1/serverless/projects/{type}/{id}/_reset-credentials で管理者のブートストラップ認証情報をリセットします。管理者パスワードを一度だけ使用して、POST /_security/api_key でスコープを限定したキーを作成し、コンテキストに保存して再検証した後、管理者の認証情報を破棄します。

2 日目以降：一覧表示、取得、更新、削除、再開

• 一覧表示： 種類を指定してプロジェクトを一覧表示します：GET cloud:/api/v1/serverless/projects/{type}。
• 取得： 1 つのプロジェクトを取得します：GET cloud:/api/v1/serverless/projects/{type}/{id}。
• 更新： PATCH セマンティクスです。指定したフィールドのみ変更されます：PATCH cloud:/api/v1/serverless/projects/{type}/{id}。
• 認証情報のリセット： 事前に確認します：POST cloud:/api/v1/serverless/projects/{type}/{id}/_reset-credentials。
• 削除： 事前に確認します。削除は取り消せません：DELETE cloud:/api/v1/serverless/projects/{type}/{id}。
• 再開： 中断中のプロジェクトを再開し、ステータスが initialized になるまでポーリングします： POST cloud:/api/v1/serverless/projects/{type}/{id}/_resume。

更新フィールドとそのリスク。 対応する PATCH フィールド：name、alias、metadata.tags、traffic_filters、および Elasticsearch の場合は search_lake.search_power（28～3000）と search_lake.boost_window（1～180 日）、Security の場合はデータ保持期間の上限です。

• エイリアスを変更すると、すべてのエンドポイント URL が書き換えられ、既存のクライアントが動作しなくなります。変更前に警告してください。
• タグを指定すると、タグセット全体が置き換わります。 まず GET で現在のタグを読み取り、ユーザーが維持したいタグも含めてください。
• search_power はコストに影響します。 値が高いほど VCU 消費量が増加します。値を引き上げる前に警告し、確認してください（プリセット：28 はオンデマンド、100 は高性能、250 は高可用性）。
• 最大保持期間を短縮すると、新しい上限より古いデータは完全に削除されます。 短縮する前に警告し、確認してください。

---

トラフィックフィルター（ネットワークセキュリティ）

トラフィックフィルターは、Serverless プロジェクトへのネットワークアクセスを制限します。Elastic Cloud UI では ネットワークセキュリティと呼ばれますが、Cloud API では トラフィックフィルターと呼ばれます（パスでは traffic-filters、プロジェクト JSON では traffic_filters）。種類は IP フィルター（タイプ ip、許可リストに IP/CIDR を指定）と VPC フィルター（タイプ vpce、AWS PrivateLink エンドポイント ID を指定）の 2 つです。

AWS ではプライベート接続がデフォルトで許可されています。VPC フィルターが必要なのは、特定のエンドポイント ID にトラフィックを制限する場合のみです。プライベート接続だけが必要で、フィルタリングが不要な場合は、AWS で VPC エンドポイントと DNS レコードを作成してください。フィルターは必要ありません。AWS でエンドポイントを作成する前に、GET cloud:/api/v1/serverless/traffic-filters/metadata を使用してリージョンの PrivateLink サービス名を確認してください。

プロセス：フィルターを作成して関連付ける

1. コンポーネントを特定します。 フィルターの種類（IP または VPC）、対象リージョン、ソースルール（IP/CIDR または VPC エンドポイント ID）、およびフィルターを適用するプロジェクトを確認します。
2. 既存の状態を確認します。 GET cloud:/api/v1/serverless/traffic-filters で現在のフィルターを一覧表示します（必要に応じてリージョンを指定します）。同じソースを同じ目的でカバーするフィルターがすでにある場合は、それを再利用します。フィルターはリージョン単位で管理され、複数のプロジェクトに関連付けられます。
3. フィルターを作成します。 type、region、rules を指定して POST cloud:/api/v1/serverless/traffic-filters を呼び出します。レスポンスには生成されたフィルターの id が含まれます。
4. プロジェクトに関連付けます。 フィルターとプロジェクトの関連付けは、プロジェクトの PATCH エンドポイント（traffic_filters 配列を指定した PATCH cloud:/api/v1/serverless/projects/{type}/{id}）を通じて行います。フィルター ID の完全な一覧を指定してください。一覧から省略された ID は関連付けが解除されます。
5. 確認します。 フィルターを再度一覧表示するか、プロジェクトに GET を実行して変更が反映されたことを確認します。

フィルターのガイダンス： フィルターはリージョン単位で管理されます（フィルターを関連付けられるのは同じリージョンのプロジェクトのみです）。ルールを更新すると、ルールセット全体が置き換えられます。既存のルールをすべて含めたうえで、新しいルールを追加してください。プロジェクトに関連付けられているフィルターは削除できません。まず関連付けを解除してから、DELETE cloud:/api/v1/serverless/traffic-filters/{id} を実行してください。include_by_default を有効にすると、リージョン内のすべての新しいプロジェクトにフィルターが自動的に関連付けられます。慎重に使用してください。スキーマの詳細は、references/traffic-filters.md を参照してください。

---

ホステッドデプロイメント

Elastic Cloud Hosted デプロイメントは、デプロイメントテンプレートに基づいてサイズを設定するフルスタックのデプロイメントです（Elasticsearch、Kibana、およびオプションの APM／Integrations Server／Enterprise Search）。Serverless プロジェクトとは別のものです。Cloud API のデプロイメントエンドポイントを通じてライフサイクルを管理します。

プロセス：ホステッドデプロイメントを作成する

1. リージョンとテンプレートを選択します。 GET cloud:/api/v1/deployments/templates で対象リージョンのデプロイメントテンプレートを一覧表示し、テンプレートとスタックのバージョンをユーザーに確認します。リージョンは後から変更できません。
2. 設定を確認します（名前、リージョン、テンプレート、バージョン、サイズ設定）。作成前に、明示的な確認を得てください。
3. デプロイメントを作成します。 リソース定義（または template_id）を指定して POST cloud:/api/v1/deployments を呼び出します。レスポンスにはデプロイメント ID、一度だけ表示される elastic ユーザーのパスワード、およびエンドポイントが返されます。認証情報は CLI コンテキスト（キーチェーン）に保存し、チャットには決して記載しないでください。
4. 準備状況を確認し、スコープを限定したキーを作成します。 正常な状態になるまで GET cloud:/api/v1/deployments/{id} をポーリングし、その後 POST /_security/api_key でスコープを限定した Elasticsearch API キーを作成して、ブートストラップ用の elastic パスワードの使用を終了します。作成リクエスト本文とテンプレートスキーマについては、references/hosted-deployments.md を参照してください。

2 日目以降：取得、更新、シャットダウン、復元

• デプロイメントを一覧表示します：GET cloud:/api/v1/deployments。
• 1 つのデプロイメントを取得します：GET cloud:/api/v1/deployments/{id}。
• 更新します（サイズ変更、バージョンアップグレード、リソース変更）：PUT cloud:/api/v1/deployments/{id}。
• シャットダウンします（先に確認してください。デプロイメントが停止します）：POST cloud:/api/v1/deployments/{id}/_shutdown。
• シャットダウンしたデプロイメントを復元します：POST cloud:/api/v1/deployments/{id}/_restore。

ホステッドデプロイメントでは、Serverless のトラフィックフィルターとは別に管理される独自のトラフィックフィルタールールセットを使用します。両者を混在させないでください。references/hosted-deployments.md を参照してください。

---

例

「acme-search という名前の検索プロジェクトを作成して」 — タイプ elasticsearch を確認し、概要（名前 acme-search、リージョン gcp-us-central1、optimized_for general_purpose）を提示します。確認後、 POST cloud:/api/v1/serverless/projects/elasticsearch を呼び出し、initialized になるまで待って認証情報を 保存し、その後 POST /_security/api_key でスコープ付き API キーを作成します。

「セキュリティプロジェクトの一覧を表示して」 — GET cloud:/api/v1/serverless/projects/security を呼び出し、名前と ID を提示します。 読み取り専用の day-2 リクエストとして扱います。

「検索プロジェクト prod-search に接続して」 — Elasticsearch プロジェクトを一覧表示し、prod-search を照合して、 エンドポイントを取得するために GET を呼び出します。その後、データプレーンの操作を行う前に、スコープ付きの Elasticsearch API キーを確認するか、新たに作成します。

「検索プロジェクトの検索性能を 500 に上げて」 — コストが増加することを警告して確認を取り、その後 PATCH cloud:/api/v1/serverless/projects/elasticsearch/{id} で search_lake.search_power = 500 を設定します。

「us-east-1 のプロジェクトへの接続を、オフィスネットワーク 203.0.113.0/24 だけに許可して」 — us-east-1 の既存フィルターを一覧表示し、 POST cloud:/api/v1/serverless/traffic-filters で ip フィルター（ルールのソース 203.0.113.0/24）を作成してから、 対象プロジェクトに対して PATCH cloud:/api/v1/serverless/projects/{type}/{id} でフィルター ID を割り当てます。

「us-east-1 でホスト型デプロイメントを起動して」 — GET cloud:/api/v1/deployments/templates でテンプレートを一覧表示し、テンプレートとスタックのバージョンを確認してから、 POST cloud:/api/v1/deployments を呼び出します。正常な状態になるまで待ち、スコープ付き API キーを作成します。

ガイドライン

• まず Cloud コンテキストを検証します（環境設定を参照）。検証に失敗した場合は、 cloud-onboarding を使って設定します。
• パスワードや API キーをチャットに表示してはいけません。CLI コンテキスト（OS のキーチェーン）に保存し、 ブートストラップ管理者認証情報に頼らず、スコープ付き API キーを作成します。
• プロジェクトのタイプを暗黙に決めてはいけません。推定したうえで確認します。最適化は general_purpose、ティアは complete をデフォルトとし、明示的なリクエストがあった場合にのみ変更します。
• 作成後にリージョンを変更することはできません。また、削除やシャットダウンは取り消せません。実行前に確認します。
• トラフィックフィルターはリージョン単位です。ルールを更新するとルールセット全体が置き換えられます。削除する前に、すべてのプロジェクトからフィルターの関連付けを解除します。
• Serverless のトラフィックフィルターと Hosted デプロイメントのトラフィックフィルタールールセットは分けて扱います。これらは異なる API です。
• ユーザーアクセスの付与と Cloud API キーについては cloud-onboarding を、Elasticsearch データプレーンのキーのライフサイクルについては elasticsearch-authn を参照してください。

操作

HTTP API (shorthand)	elastic CLI command
GET cloud:/api/v1/serverless/regions	elastic cloud serverless regions list-regions
POST cloud:/api/v1/serverless/projects/elasticsearch	elastic cloud serverless projects search create --input-file <json> --wait --save-as <ctx>
POST cloud:/api/v1/serverless/projects/observability	elastic cloud serverless projects observability create --input-file <json> --wait --save-as <ctx>
POST cloud:/api/v1/serverless/projects/security	elastic cloud serverless projects security create --input-file <json> --wait --save-as <ctx>
GET cloud:/api/v1/serverless/projects/elasticsearch	elastic cloud serverless projects search list
GET cloud:/api/v1/serverless/projects/elasticsearch/{id}	elastic cloud serverless projects search get --id <id>
GET cloud:/api/v1/serverless/projects/elasticsearch/{id}/status	elastic cloud serverless projects search get-status --id <id>
PATCH cloud:/api/v1/serverless/projects/elasticsearch/{id}	elastic cloud serverless projects search patch --id <id> --input-file <json>
DELETE cloud:/api/v1/serverless/projects/elasticsearch/{id}	elastic cloud serverless projects search delete --id <id>
POST cloud:/api/v1/serverless/projects/elasticsearch/{id}/_reset-credentials	elastic cloud serverless projects search reset-credentials --id <id> --save-as <ctx>
POST cloud:/api/v1/serverless/projects/elasticsearch/{id}/_resume	elastic cloud serverless projects search resume --id <id>
GET cloud:/api/v1/serverless/traffic-filters	elastic cloud serverless traffic-filters list-traffic-filters --region <region>
POST cloud:/api/v1/serverless/traffic-filters	elastic cloud serverless traffic-filters create-traffic-filter --input-file <json>
GET cloud:/api/v1/serverless/traffic-filters/{id}	elastic cloud serverless traffic-filters get-traffic-filter --id <id>
PATCH cloud:/api/v1/serverless/traffic-filters/{id}	elastic cloud serverless traffic-filters patch-traffic-filter --id <id> --input-file <json>
DELETE cloud:/api/v1/serverless/traffic-filters/{id}	elastic cloud serverless traffic-filters delete-traffic-filter --id <id>
GET cloud:/api/v1/serverless/traffic-filters/metadata	elastic cloud serverless traffic-filters get-traffic-filter-metadata --region <region>
GET cloud:/api/v1/deployments/templates	elastic cloud hosted deployment-templates get-deployment-templates-v2
GET cloud:/api/v1/deployments	elastic cloud hosted deployments list-deployments
POST cloud:/api/v1/deployments	elastic cloud hosted deployments create-deployment --input-file <json>
GET cloud:/api/v1/deployments/{id}	elastic cloud hosted deployments get-deployment --deployment-id <id>
PUT cloud:/api/v1/deployments/{id}	elastic cloud hosted deployments update-deployment --deployment-id <id> --input-file <json>
POST cloud:/api/v1/deployments/{id}/_shutdown	elastic cloud hosted deployments shutdown-deployment --deployment-id <id>
POST cloud:/api/v1/deployments/{id}/_restore	elastic cloud hosted deployments restore-deployment --deployment-id <id>
GET /_security/_authenticate	elastic es security authenticate
POST /_security/api_key	elastic es security create-api-key --input-file <json>

可観測性およびセキュリティのプロジェクトタイプには、それぞれ対応する projects observability … ／ projects security … コマンドを使用してください。