cloud-manage-project

Serverless プロジェクトの管理

Serverless REST API を使用して、Elastic Cloud Serverless プロジェクトに対する day-2 運用を実行します。

前提条件と権限

• EC_API_KEY が設定されていることを確認してください。設定されていない場合は、先に cloud-setup スキルを実行してください。
• プロジェクト設定を更新するには、対象プロジェクトで Admin または Editor ロールが必要です。
• このスキルでは、ロールの事前確認は個別に行いません。要求された操作を試し、API による認可に任せてください。API が認可エラー（例：403 Forbidden）を返した場合は、処理を中止し、提供された API キーの権限を確認するようユーザーに依頼してください。

手動セットアップの代替手段（cloud-setup を利用できない場合）

このスキルが単独でインストールされていて、cloud-setup を利用できない場合は、コマンドを実行する前に Cloud 環境変数を手動で設定するようユーザーに案内してください。API キーをチャットに貼り付けるようユーザーに求めてはいけません。

変数	必須	説明
EC_API_KEY	はい	プロジェクト管理操作に使用する Elastic Cloud API キーです。
EC_BASE_URL	いいえ	Cloud API のベース URL です（デフォルト：https://api.elastic-cloud.com）。

注： EC_API_KEY が設定されていない場合、またはユーザーがまだ Cloud API キーを持っていない場合は、Elastic Cloud API keys でキーを生成し、以下の手順に従ってローカルで設定するよう案内してください。

推奨方法（エージェントに適しています）：プロジェクトのルートに .env ファイルを作成します。

EC_API_KEY=your-api-key
EC_BASE_URL=https://api.elastic-cloud.com

すべての cloud/* スクリプトは、作業ディレクトリの .env を自動的に読み込みます。

代替方法：ターミナルで直接エクスポートします。

export EC_API_KEY="<your-cloud-api-key>"
export EC_BASE_URL="https://api.elastic-cloud.com"

別のシェルセッションで実行されるサンドボックス化されたエージェントからは、ターミナルでエクスポートした値が参照できない場合があります。そのため、エージェントを使用する場合は .env を推奨します。

重要な原則

• チャットにシークレットを表示してはいけません。 API キー、パスワード、認証情報を会話メッセージやエージェントの思考内でエコー、ログ出力、または繰り返してはいけません。代わりに .elastic-credentials ファイルを参照するようユーザーに案内してください。管理者パスワードは、API キーの作成に使用する場合であっても、チャット履歴、思考のトレース、エージェントの出力に決して含めてはいけません。エコーせず、シェル変数の置換を通じて直接渡してください。
• 破壊的な操作の前に確認してください。 プロジェクトの削除や認証情報のリセットを行う前に、必ずユーザーに確認してください。
• 認証情報はファイルに保存されます。 認証情報をリセットすると、スクリプトは新しいパスワードを .elastic-credentials に自動的に書き込みます。パスワードは標準出力では伏せられます。チャットで .elastic-credentials の内容を読み取ったり表示したりしてはいけません。
• 管理者認証情報は API キーの作成にのみ使用してください。 create-project と reset-credentials によって保存される admin パスワードは、スコープ付き API キーを初期作成する目的に限られます。Elasticsearch の直接操作には決して使用しないでください。load-credentials はデフォルトで管理者認証情報を除外します。キーの作成時に限り --include-admin を渡してください。
• 常に API キーを優先してください。 ELASTICSEARCH_API_KEY が設定されるまでは、Elasticsearch の操作を進めないでください。管理者認証情報しかない場合は、elasticsearch-authn を使用してスコープ付き API キーを作成してください。そのスキルがインストールされていない場合は、インストールするか、Kibana > Stack Management > API keys で手動作成するようユーザーに依頼してください。
• プロジェクトは種類と ID で識別してください。 すべてのコマンドで --type と --id の両方が必要です（--type のみが必要な list を除きます）。
• API キーには 2 種類あります。 このスキルでは、プロジェクト管理操作（list、get、update、delete）に Cloud API キー（EC_API_KEY）を使用します。Elasticsearch の操作には、プロジェクトの Elasticsearch エンドポイントに対して認証を行う別個の Elasticsearch API キー（ELASTICSEARCH_API_KEY）が必要です。この 2 つを混同しないでください。

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

現在のセッションでエージェントが作成していないプロジェクトをクエリまたは管理するようユーザーから依頼された場合は、このワークフローを使用します。プロジェクトを特定し、エンドポイントを保存したうえで、作業を進める前に有効な Elasticsearch 認証情報があることを確認します。

このワークフローは、Elastic Cloud Serverless プロジェクトにのみ適用されます。ユーザーの Elasticsearch インスタンスがセルフマネージドまたは Elastic Cloud Hosted の場合、このスキルは適用されないため、関連するスキルに直接進みます。 不明な場合は、ユーザーに尋ねます：「お使いの Elasticsearch インスタンスは Elastic Cloud Serverless プロジェクトですか？」

Connect to Existing Project:
- [ ] Step 1: Resolve the project
- [ ] Step 2: Get project details and load credentials
- [ ] Step 3: Acquire Elasticsearch credentials

ステップ 1：プロジェクトを特定する

プロジェクト名がまだ指定されていない場合は、ユーザーに尋ねます。ユーザーの依頼からプロジェクトタイプを推測します：

ユーザーの表現	--type
「search project」、「elasticsearch project」、ベクトル検索	elasticsearch
「observability project」、「o11y」、ログ、メトリクス、トレース、APM	observability
「security project」、「SIEM」、検出、エンドポイント保護	security

タイプが曖昧な場合は、プロジェクトを探すために3つのタイプすべてを一覧表示します。

python3 skills/cloud/manage-project/scripts/manage-project.py list \
  --type elasticsearch

ユーザーが指定した情報（名前、名前の一部、またはエイリアス）を一覧表示された結果と照合します。複数のプロジェクトが一致する場合、または一致するものがない場合は、候補を提示してユーザーに選択を求めます。

ステップ 2：プロジェクトの詳細を取得して認証情報を読み込む

プロジェクトを1つに特定したら、.elastic-credentials にこのプロジェクトのエントリがすでにあるか（以前のセッションで保存されたものか）確認します。ある場合は、load-credentials で読み込みます：

eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
  --name "<project-name>")

これにより、プロジェクトの保存済み環境変数（エンドポイントと、以前に作成した Elasticsearch API キー）が、1つのコマンドですべて設定されます。管理者の認証情報（ELASTICSEARCH_USERNAME／ELASTICSEARCH_PASSWORD）は意図的に除外されます。同じプロジェクトの後続セクションは以前の値を自動的に上書きするため、常に最新の認証情報が使用されます。

load-credentials で一致するエントリがないと報告された場合は、API からプロジェクトの詳細を取得し、エンドポイントを手動でエクスポートします：

python3 skills/cloud/manage-project/scripts/manage-project.py get \
  --type elasticsearch \
  --id <project-id>

次に、レスポンスからエンドポイント URL をエクスポートします。利用可能なエンドポイントはプロジェクトタイプによって異なります。

すべてのプロジェクトタイプ：

export ELASTICSEARCH_URL="<elasticsearch_endpoint>"
export KIBANA_URL="<kibana_endpoint>"

Observability プロジェクト（追加分）：

export APM_URL="<apm_endpoint>"
export INGEST_URL="<ingest_endpoint>"

Security プロジェクト（追加分）：

export INGEST_URL="<ingest_endpoint>"

ステップ 3：Elasticsearch の認証情報を取得する

load-credentials によって ELASTICSEARCH_API_KEY が設定されている場合は、認証情報が有効か確認します。

curl -H "Authorization: ApiKey ${ELASTICSEARCH_API_KEY}" \
  "${ELASTICSEARCH_URL}/_security/_authenticate"

続行する前に、応答に有効な username と "authentication_type": "api_key" が含まれていることを確認してください。 認証の確認に成功した場合は、このステップの残りをスキップします。

認証情報が読み込まれていない場合、または確認に失敗した場合は、ユーザーに 「このプロジェクト用の既存の Elasticsearch API キーはありますか？」 と尋ねます。

ある場合 — ユーザーに .elastic-credentials へ追加してもらいます（「認証情報ファイルの形式」を参照）。チャットでキーを受け取らないでください。 再読み込みして確認します。

eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
  --name "<project-name>")
curl -H "Authorization: ApiKey ${ELASTICSEARCH_API_KEY}" \
  "${ELASTICSEARCH_URL}/_security/_authenticate"

ない場合 — 次の復旧手順に従います。

1. ユーザーに確認してから、管理者のブートストラップ認証情報をリセットします。

   python3 skills/cloud/manage-project/scripts/manage-project.py reset-credentials \
     --type elasticsearch \
     --id <project-id>
   

   新しいパスワードは、ヘッダーにプロジェクト名を含めて .elastic-credentials に保存されます。ユーザーにはそのファイルを確認するよう案内してください — 内容を表示してはいけません。

2. API キーの作成に管理者パスワードを使用できるよう、--include-admin を指定して認証情報を読み込みます。

   eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
     --name "<project-name>" --include-admin)
   

   管理者認証情報を使用して、利用可能であれば elasticsearch-authn 経由でスコープを限定した Elasticsearch API キーを作成します。その スキルがインストールされていない場合は、ユーザーにインストールするか、Kibana > Stack Management > API keys で手動作成するよう依頼します。キーの権限は、ユーザーが必要とするものだけに限定してください。

3. API キーの作成後、プロジェクト固有のヘッダー形式を使用して .elastic-credentials に保存します（下記の 「認証情報ファイルの形式」を参照）。その後、--include-admin を指定せずに再読み込みし、環境から管理者認証情報を削除して確認します。

   eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
     --name "<project-name>")
   curl -H "Authorization: ApiKey ${ELASTICSEARCH_API_KEY}" \
     "${ELASTICSEARCH_URL}/_security/_authenticate"
   

続行する前に、応答に有効な username と "authentication_type": "api_key" が表示されていることを確認してください。

認証情報ファイルの形式

形式の完全な仕様については、references/credential-file-format.md を参照してください。

ワークフロー：プロジェクトの認証情報を読み込む

eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
  --name "<project-name>")

または、プロジェクト ID を指定します。

eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
  --id <project-id>)

.elastic-credentials を解析し、一致するプロジェクトのすべてのセクションを統合して、export 文を出力します。管理者認証情報（ELASTICSEARCH_USERNAME／ELASTICSEARCH_PASSWORD）はデフォルトで除外され、エンドポイントと API キーのみがエクスポートされます。API キーの作成に管理者認証情報が必要な場合は、--include-admin を追加します。

ワークフロー：プロジェクトを一覧表示する

python3 skills/cloud/manage-project/scripts/manage-project.py list \
  --type elasticsearch

ほかの種類のプロジェクトを一覧表示するには、--type observability または --type security を使用します。

ワークフロー：プロジェクトの詳細を取得する

python3 skills/cloud/manage-project/scripts/manage-project.py get \
  --type elasticsearch \
  --id <project-id>

ワークフロー：プロジェクトを更新する

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type elasticsearch \
  --id <project-id> \
  --name "new-project-name"

指定したフィールドのみが更新されます（PATCH セマンティクス）。サポートされているフィールド：--name、--alias、--tag、 --search-power、--boost-window、--max-retention-days、--default-retention-days。

エイリアス

エイリアスは RFC-1035 ドメインラベル（小文字の英数字とハイフン、最大 50 文字）で、プロジェクトのエンドポイント URL の一部になります。エイリアスを変更すると、すべてのエンドポイント URL が変わるため、古い URL を参照している既存のクライアントは動作しなくなります。変更を適用する前に、ユーザーにこのことを警告してください。

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type elasticsearch \
  --id <project-id> \
  --alias "prod-search"

タグ

タグは、チームによる追跡、コストの割り当て、組織管理に使用するキーと値のメタデータです。タグごとに --tag KEY:VALUE を指定します。1 回の更新で複数のタグを設定できます。

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type elasticsearch \
  --id <project-id> \
  --tag env:prod \
  --tag team:search

タグは API リクエストの metadata.tags として送信されます。タグを設定すると、プロジェクトの既存のタグはすべて置き換えられます。ユーザーが保持したい既存のタグも含めてください。

Elasticsearch search_lake 設定

Elasticsearch プロジェクトでは、Search AI Lake のクエリパフォーマンスとデータキャッシュを制御する 2 つのフィールドがあります。取り込まれたデータは、コスト効率の高い汎用ストレージに保存されます。その上のキャッシュレイヤーにより、最近のデータや頻繁にクエリされるデータを高速に検索できます。このキャッシュされたデータは、検索可能な状態と見なされます。

フラグ	範囲	説明
--search-power	28–3000	クエリパフォーマンスレベル。値を大きくするとパフォーマンスが向上しますが、コストも増加します
--boost-window	1–180	キャッシュ強化の対象となるデータの日数（デフォルト：7）

Search Power

Search Power は、クエリリソースを増減させて検索速度を制御します。一般的なプリセット（Cloud UI に対応）は次のとおりです。

値	プリセット	動作
28	On-demand	ベースラインを低く抑えて自動スケーリングします。レイテンシーの変動が大きくなり、最大スループットは低下します
100	Performant	一貫して低レイテンシーを維持し、中程度の高スループットに対応して自動スケーリングします
250	High availability	高スループットのシナリオ向けに最適化され、大量のデータでも低レイテンシーを維持します

ユーザーがプリセット名を指定した場合は、対応する値に変換してください。28～3000 の範囲内であれば、カスタム値も有効です。

search_power を更新する前に、コストへの影響をユーザーに警告してください。値を大きくすると VCU の消費量が増え、請求額が高くなる可能性があります。適用する前に、新しい値をユーザーに確認してください。

Search Boost Window

時系列以外のデータは常に検索可能な状態です。ブーストウィンドウは、どれだけの時系列データ（@timestamp フィールドを持つドキュメント）を高速キャッシュレイヤーに保持するかを決定します。ウィンドウを広げると、検索可能な状態になる時系列データが増え、最近のデータのクエリ速度が向上しますが、検索可能なデータ量も増加します。

セキュリティデータの保持設定

セキュリティプロジェクトでは、Search AI Lake でデータを保持する期間を制御する 2 つのフィールドがあります。保持期間はデータストリームごとに設定しますが、プロジェクトレベルのこれらの設定によって全体の境界が適用されます。

フラグ	単位	説明
--max-retention-days	日	プロジェクト内のすべてのデータストリームに対する最大保持期間
--default-retention-days	日	カスタム保持期間が設定されていないデータストリームに適用されるデフォルトの保持期間

• 最大保持期間 — すべてのデータストリームに対して上限を適用します。値を小さくすると、現在その期間を超えているすべてのストリームの保持期間が置き換えられます。新しい上限より古いデータは完全に削除されます。
• デフォルトの保持期間 — カスタム保持期間が設定されていないデータストリームに自動的に適用されます。既存のカスタム保持期間が設定されているストリームには影響しません。

max-retention-days を短縮する前に、ユーザーに警告してください。最大値を小さくすると、新しい上限より古いデータが完全に削除されます。適用する前に、新しい値をユーザーに確認してください。

ワークフロー：プロジェクトの認証情報をリセットする

リセットする前に、必ずユーザーに確認してください。

python3 skills/cloud/manage-project/scripts/manage-project.py reset-credentials \
  --type elasticsearch \
  --id <project-id>

新しいパスワードは .elastic-credentials に自動的に保存されます。そのファイルを開くようユーザーに伝えてください。チャットに内容を表示してはいけません。

ワークフロー：プロジェクトを削除する

削除する前に、必ずユーザーに確認してください。

python3 skills/cloud/manage-project/scripts/manage-project.py delete \
  --type elasticsearch \
  --id <project-id>

ワークフロー：一時停止中のプロジェクトを再開する

試用期間が終了すると、プロジェクトは自動的に一時停止されることがあります。次のコマンドで再開します。

python3 skills/cloud/manage-project/scripts/manage-project.py resume \
  --type elasticsearch \
  --id <project-id>

再開後、フェーズが initializing から initialized に変わるまで、プロジェクトのステータスをポーリングしてください。

例

すべてのセキュリティプロジェクトを一覧表示する

python3 skills/cloud/manage-project/scripts/manage-project.py list --type security

Elasticsearch プロジェクトの検索パワーを更新する

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type elasticsearch \
  --id abc123def456abc123def456abc12345 \
  --search-power 500

セキュリティプロジェクトのデータ保持期間を設定する

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type security \
  --id abc123def456abc123def456abc12345 \
  --max-retention-days 396 \
  --default-retention-days 396

プロジェクトのエイリアスを変更する

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type elasticsearch \
  --id abc123def456abc123def456abc12345 \
  --alias "prod-search"

コスト追跡用のタグをプロジェクトに付ける

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type observability \
  --id abc123def456abc123def456abc12345 \
  --tag env:prod \
  --tag team:platform

オブザーバビリティプロジェクトの名前を変更する

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type observability \
  --id abc123def456abc123def456abc12345 \
  --name "production-logs"

既存のプロジェクトに接続する（認証情報が保存済み）

User: I want to run a query against my search project "prod-search"
Agent: Let me find that project.
       [runs: list --type elasticsearch]
       I found "prod-search" (ID: abc123...). Loading saved credentials...
       [runs: eval $(load-credentials --name prod-search)]
       Credentials loaded. Verifying...
       [runs: curl -H "Authorization: ApiKey ..." "${ELASTICSEARCH_URL}/_security/_authenticate"]
       Verified — authenticated as user "my-service" via API key. You're all set.

プロジェクトに接続する（保存済みの認証情報がない場合）

User: let's ingest some logs into my o11y project "siem-prod"
Agent: Let me find that project.
       [runs: list --type observability]
       Found "siem-prod" (ID: def456...). No saved credentials found for this project.
       [runs: get --type observability --id def456...]
       Endpoints set. Since there are no Elasticsearch credentials on file, I can reset the
       admin bootstrap password to get initial access. Shall I proceed?
User: yes
Agent: [runs: reset-credentials --type observability --id def456...]
       Credentials saved to .elastic-credentials — open that file to retrieve the password.
       [runs: eval $(load-credentials --name siem-prod --include-admin)]
       Admin credentials loaded for API key creation. Creating a scoped Elasticsearch API key
       now — what access does it need?
User: read-only on logs-*
Agent: [creates scoped API key via elasticsearch-authn using admin credentials]
       [appends API key to .elastic-credentials with project header]
       [runs: eval $(load-credentials --name siem-prod)]
       [verifies against ELASTICSEARCH_URL]
       API key created and verified. Admin credentials removed from environment.

確認後にプロジェクトを削除する

User: delete my elasticsearch project abc123...
Agent: Are you sure you want to delete project abc123...? This cannot be undone.
User: yes

python3 skills/cloud/manage-project/scripts/manage-project.py delete \
  --type elasticsearch \
  --id abc123def456abc123def456abc12345

ガイドライン

• EC_API_KEY が設定されていない場合は、最初に cloud-setup スキルを実行します。
• 新しいプロジェクトの作成には cloud-create-project スキルを使用します。このスキルは既存のプロジェクトのみを対象としています。
• エージェントが作成していないプロジェクトについてユーザーから言及があった場合は、「既存のプロジェクトに接続する」ワークフローに従います。
• 削除は取り消せません。必ず実行前にユーザーに確認します。
• 認証情報をリセットした後は、保存済みのパスワードや環境変数を更新するようユーザーに伝えます。
• search_power を増やす前に、コストへの影響を警告します。新しい値は事前にユーザーに確認します。
• max-retention-days を減らす前に、データ損失の可能性を警告します。新しい上限を超える古いデータは完全に削除されます。
• プロジェクトのエイリアスを変更すると、すべてのエンドポイント URL が変わり、既存のクライアントが動作しなくなることをユーザーに警告します。
• タグを設定すると、既存のタグがすべて置き換えられます。まず get で現在のタグを取得し、ユーザーが残したいタグも含めます。

スクリプトのリファレンス

コマンド	説明
list	タイプ別にプロジェクトを一覧表示します
get	ID を指定してプロジェクトの詳細を取得します
update	プロジェクト名、エイリアス、タグ、または search_lake の設定を更新します
reset-credentials	プロジェクトの認証情報をリセットします（新しいパスワード）
delete	プロジェクトを削除します
resume	一時停止中のプロジェクトを再開します
load-credentials	.elastic-credentials に保存されたプロジェクトの認証情報を読み込みます

フラグ	コマンド	説明
--type	list, get, update, reset-credentials, delete, resume	プロジェクトタイプ：elasticsearch、observability、security
--id	get, update, reset-credentials, delete, resume, load-credentials	プロジェクト ID
--name	update, load-credentials	プロジェクト名（update：新しい名前、load-credentials：検索）
--alias	update	新しいプロジェクトエイリアス
--tag	update	KEY:VALUE 形式のタグ（繰り返し指定可能。すべてのタグを置き換えます）
--search-power	update	検索パワー 28～3000（elasticsearch のみ）
--boost-window	update	ブースト期間 1～180 日（elasticsearch のみ）
--max-retention-days	update	データ保持期間の上限（日数）（security のみ）
--default-retention-days	update	デフォルトのデータ保持期間（日数）（security のみ）
--include-admin	load-credentials	管理者のユーザー名／パスワードを含めます（API キーのブートストラップのみ）
--wait-seconds	reset-credentials	認証情報の反映を待機する秒数（スキップする場合は 0）

環境変数

変数	必須	説明
EC_API_KEY	はい	Elastic Cloud API キー（プロジェクト管理操作用）
EC_BASE_URL	いいえ	Cloud API のベース URL（デフォルト：https://api.elastic-cloud.com）
ELASTICSEARCH_URL	出力	Elasticsearch URL（後続のスキルでプロジェクトを解決した後に設定されます）
KIBANA_URL	出力	Kibana URL（後続のスキルでプロジェクトを解決した後に設定されます）
APM_URL	出力	APM エンドポイント（observability プロジェクトのみ）
INGEST_URL	出力	OTLP 取り込みエンドポイント（observability および security プロジェクト）
ELASTICSEARCH_API_KEY	出力	Elasticsearch API キー（スタックレベルの操作用）

追加リソース

• API の詳細、リクエスト／レスポンスのスキーマ、プロジェクトタイプのオプションについては、 Serverless Projects APIを参照してください。
• Search AI Lake の設定、データ保持、プロジェクト機能に関する公式ドキュメントについては、 プロジェクト設定を参照してください。