cloud-onboarding

Cloud のオンボーディング

Elastic Cloud 組織へのアクセスを最初から最後まで設定します。elastic CLI を構成してコントロールプレーンを操作できるようにし、ユーザーの招待、Serverless プロジェクトへの定義済みロールまたはカスタムロールの割り当て、Cloud API キーの管理といった、ID とアクセスの管理を行います。プロジェクトとデプロイメントの作成および運用には、cloud-provisioning スキルを使用してください。

環境設定

このスキルは elastic CLI 自体を構成するため、セットアップ手順をここに記載しています。elastic CLI がインストールされていない場合は、何に必要なのかをユーザーに伝えてください。

Cloud コントロールプレーンへのアクセスには、Elastic Cloud API キー（組織スコープ）を使用して認証します。このキーは CLI のコンテキストに保存します。シークレットをチャットに貼り付けるようユーザーに求めることなく、登録してください。

• Cloud API キーを作成できるのは組織のオーナーのみです。サーバーレスプロジェクトを管理できるよう、Project Admin 以上の権限を付与して、Elastic Cloud API キーでキーを生成するよう案内してください。
• ユーザーが Elastic Cloud アカウントを持っていない場合は、無料のElastic Cloud トライアル（14 日間、クレジットカード不要）を提案してください。登録後、キーの生成に進んでください。
• コンテキストにキーを追加します（シークレットは OS のキーチェーンに保存され、表示されません）。 elastic config context add cloud --cloud-url https://api.elastic-cloud.com --cloud-api-key <KEY>。続けて、elastic config current-context set cloud でアクティブにします。

認証情報を推測したり、CLI を迂回して HTTP API を直接呼び出したり、キーを明かすようユーザーに求めたりしないでください。このスキルでは、コントロールプレーンの操作を cloud: プレフィックス付きの HTTP 短縮形式（例：GET cloud:/api/v1/organizations）で記載しています。操作の表で、それぞれに対応する elastic cloud コマンドを確認できます。

API スキーマの詳細（ロール割り当て、Cloud API キー、カスタムロール）については、references/api-reference.mdを参照してください。Cloud ロールを超える Elasticsearch レベルのロール管理（ネイティブユーザー、ロールマッピング、DLS/FLS）については、elasticsearch-authzを参照してください。

実行するタスク

• Cloud コンテキストを構成して検証し、後でプロジェクトを作成する際のデフォルトリージョンを設定する
• ユーザーを招待して Serverless プロジェクトのロールを割り当てる。メンバーとそのロールを一覧表示し、アクセス権を更新または削除する
• Cloud API キーを作成、一覧表示、取り消す。必要に応じて、プロジェクトで Elasticsearch/Kibana API アクセスを付与する
• Serverless プロジェクトでカスタムロールを作成し、Cloud API の application_roles を通じて割り当てる
• 自然言語によるアクセス要求を、招待、ロール、API キーに関するタスクに変換する

手順：環境を検証する

1. Cloud コンテキストを検証します。 GET cloud:/api/v1/organizations を呼び出し、アクティブなコンテキストからコントロールプレーンにアクセスできることを確認します。成功すると、キーに関連付けられた組織の一覧が返され、ほかの手順で必要となる組織 ID がわかります。認証エラーが返された場合、コンテキストが設定されていないか、キーが無効または期限切れです。環境設定に戻り、有効なキーを登録してください。検証が成功するまでは先に進まず、組織 ID をユーザーに尋ねないでください。ここで確認します。

2. デフォルトリージョンを設定します（任意）。 ユーザーがプロジェクトの作成を予定している場合は、GET cloud:/api/v1/serverless/regions で利用可能なリージョンを一覧表示し、デフォルトを確認します。ユーザーから別の指定がない限り、gcp-us-central1 をデフォルトにしてください。新しいプロジェクトを作成できるのは、project_creation_enabled: true のリージョンのみです。プロジェクトごとにリージョンの選択は変更できないため、早い段階で明示してください。

権限

このスキルではロールを事前確認せず、操作を試みて、認可の判定を API に委ねます。403 が返された場合は処理を中止し、API キーの権限を確認するようユーザーに依頼してください。

操作	必要な権限
メンバーの招待／削除	組織オーナー（organization-admin）
ロールの割り当て／削除	組織オーナー（organization-admin）
Cloud API キーの作成／失効	組織オーナー（organization-admin）
メンバー、招待、キーの一覧表示	組織の任意のメンバー
カスタムロールの作成／削除	プロジェクトの ES エンドポイントに対する manage_security クラスター権限

定義済みロール

定義済みロールを優先し、必要な細かさの権限が得られない場合にのみカスタムロールを作成してください。

組織： organization-admin（完全な管理者）、billing-admin（請求のみ）。

サーバーレスプロジェクトのロール（招待時、またはロール割り当ての更新で割り当てます）：

ロール	role_id	利用可能な対象
管理者	admin	Search、Obs、Security
開発者	developer	Search
閲覧者	viewer	Search、Obs、Security
編集者	editor	Obs、Security
アナリスト	t1_analyst、t2_analyst、t3_analyst、soc_manager、rule_author	Security

role_assignments の完全なスキーマ（組織、デプロイメント、プロジェクトのスコープ）と Security のロール一覧については、references/api-reference.md を参照してください。

プロセス：アクセス要求を分解する

ユーザーが自然言語でアクセスを要求した場合（例：「Alice を検索プロジェクトに開発者として追加して」）、実行前に内容を分解してください。

1. 要素を特定します。 対象者（新規招待か既存メンバーか）、対象（プロジェクトまたは組織レベル）、アクセスレベル（定義済みロールかカスタムロールか）、API キーも必要かどうかを確認します。

2. まず既存の状態を確認します。 GET cloud:/api/v1/organizations/{org_id}/members でメンバーを一覧表示し、キーの要求がある場合は GET cloud:/api/v1/users/auth/keys で既存のキーを確認します。ユーザーがすでにメンバーの場合は、招待するのではなくロールを更新してください。同じ目的に使用するアクティブなキーがあり、適切なロールが設定され、十分な有効期間が残っている場合は、それを再利用してください。

3. 必要最小限の変更を実行します。

   • 新しいメンバーを招待するには、POST cloud:/api/v1/organizations/{org_id}/invitations を使用します（プロジェクトのロール割り当てを含めるか、後でカスタムロールを割り当てる場合はロールなしで招待します）。
   • 既存メンバーのロールを更新するには、POST cloud:/api/v1/users/{user_id}/role_assignments を使用します。削除には DELETE 版を使用します。
   • メンバーを削除するには、DELETE cloud:/api/v1/organizations/{org_id}/members/{user_ids} を使用します（先に確認してください）。
   • Cloud API キーを作成するには、POST cloud:/api/v1/users/auth/keys を使用します。失効には DELETE cloud:/api/v1/users/auth/keys を使用します（先に確認してください）。メンバーの削除やキーの失効など、破壊的な操作は実行前にユーザーに確認してください。

4. 確認します。 メンバーまたはキーを再度一覧表示し、変更が反映されたことを確認します。

カスタムロール（Serverless）

事前定義済みのロールでは粒度が足りない場合は、Elasticsearch のセキュリティ API を使ってプロジェクト内にカスタムロールを作成し、Cloud API の application_roles で割り当てます。

1. PUT /_security/role/{name} でプロジェクト内にロールを作成します（プロジェクトの Elasticsearch エンドポイントに対して実行し、manage_security が必要です）。ロール名は英字または数字で始まり、英字、数字、_、-、. のみを含める必要があります。Serverless では Run-as 権限は使用できません。
2. 必要に応じてユーザーを招待します。プロジェクトロールの割り当ては行いません（プロジェクトへのアクセスはカスタムロールで処理します）。
3. プロジェクトスコープのロール割り当て（POST cloud:/api/v1/users/{user_id}/role_assignments）で application_roles を設定し、カスタムロールを割り当てます。このとき role_id には、プロジェクトタイプに対応する Viewer（elasticsearch-viewer、observability-viewer、security-viewer）を設定します。

同じプロジェクトに事前定義済みの Cloud ロールも割り当てないでください。 カスタムロールだけで Viewer レベルの Cloud アクセスが付与されます。viewer（または別の事前定義済みロール）を追加すると、両方の権限がユーザーに付与され、カスタムロールの意図を超えてアクセス範囲が広がります。

スタックアクセス権を持つ Cloud API キー

Cloud API キーは、role_assignments に application_roles を含めることで、Serverless プロジェクトの Elasticsearch API と Kibana API も呼び出せます。ユーザーとは異なり、API キーは role_id からスタックロールを継承しません。application_roles がない場合、キーは Cloud API のみにアクセスでき、ES／Kibana の呼び出しでは 403 が返されます。

• キーが指定したプロジェクト、または指定タイプのすべてのプロジェクトにのみアクセスできるよう、プロジェクトスコープの割り当て（project キー）をデフォルトにします。
• 組織スコープの割り当て（organization キー）は、現在および将来のすべてのプロジェクトへの ES／Kibana アクセスを許可し、データプレーンの範囲が最も広くなります。プロジェクトを横断する自動化が本当に必要な場合に限って使用し、必ず事前にユーザーに確認してください。
• application_roles 内のカスタムロール名は、対象となる各プロジェクトに存在する必要があります。存在しない場合、そのキーは該当プロジェクトへのアクセス権を付与されません。事前定義済みのロール（admin、developer、viewer）は、デフォルトですべてのプロジェクトに存在します。

例

「Cloud 環境をセットアップして」 — Cloud コンテキストが存在することを確認し、GET cloud:/api/v1/organizations で検証します。失敗した場合は、組織レベルの Cloud API キーを生成してコンテキストとして登録する手順をユーザーに案内します（チャットには決して記載しません）。その後、再度検証し、見つかった組織を報告します。

「EU リージョンに Cloud をセットアップして」 — コンテキストを検証した後、GET cloud:/api/v1/serverless/regions でリージョンを一覧表示し、EU リージョン（例：aws-eu-west-1）を選びます。以降のプロジェクト作成でデフォルトとして使用するリージョンを確認します。

「検索プロジェクトに [email protected] を読み取り専用で追加して」 — GET cloud:/api/v1/organizations/{org_id}/members でメンバーを確認します。Alice が新規ユーザーの場合は、Elasticsearch プロジェクトに対するプロジェクトスコープの viewer ロールを指定して、POST cloud:/api/v1/organizations/{org_id}/invitations を実行します。

「検索プロジェクトにインデックスを作成できる、30 日間有効な CI キーを作成して」 — 重複を避けるため、GET cloud:/api/v1/users/auth/keys でキーを一覧表示します。その後、application_roles: ["developer"] と expiration: "30d" を含むプロジェクトスコープの developer ロール割り当てを指定して、POST cloud:/api/v1/users/auth/keys を実行します。シークレットが表示されるのは 1 回だけです。チャットで再度表示してはいけません。

「検索プロジェクトで marketing-* に読み取り専用アクセスできるよう、[email protected] に権限を付与して」 — PUT /_security/role/marketing-reader でカスタムロール（marketing-* に対する読み取り権限）を作成し、プロジェクトロールを付与せずに Bob を招待します。その後、POST cloud:/api/v1/users/{user_id}/role_assignments で application_roles を使ってカスタムロールを割り当てます。viewer も割り当ててはいけません。

「組織に誰がアクセスできるか教えて」 — GET cloud:/api/v1/organizations/{org_id}/members を実行し、各メンバーの ID、メールアドレス、ロールを提示します。

ガイドライン

• まず Cloud のコンテキストを検証します。GET cloud:/api/v1/organizations から組織 ID を確認してください。ユーザーに尋ねてはいけません。
• チャットで認証情報を受け取ったり、繰り返したり、ログに記録したりしてはいけません。 Cloud API キーは CLI コンテキストに登録し、シークレットが OS のキーチェーンに保存されるようにしてください。ユーザーがキーを貼り付けようとした場合は断り、代わりにコンテキストへの登録を案内します。作成したキーのシークレットが表示されるのは一度だけです。ユーザーに安全な場所へ保管するよう伝え、決して繰り返してはいけません。
• デフォルトのリージョンは gcp-us-central1 です。 ユーザーから別のリージョンを指定された場合にのみ変更してください。
• 破壊的な操作（メンバーの削除、キーの失効）を実行する前に、確認してください。
• 事前定義ロールを優先し、必要な場合にのみカスタムロールを使用してください。同じプロジェクトで事前定義の Cloud ロールとカスタムロールを併用してはいけません。
• API キーの管理: キーを作成する前に既存のキーを確認し、タスクの期間に合わせて expiration を設定してください。不要になったキーの失効をユーザーに促してください。各組織で有効化できるキーは最大 500 個です。デフォルトの有効期限は 3 か月です。招待のデフォルトの有効期限は 72 時間です。Cloud API キーは作成時のロールを継承し、後から更新できません。ロールを変更するには、キーを失効させて再作成してください。
• プロジェクト、トラフィックフィルター、デプロイメントの作成と運用については cloud-provisioning を、ES レベルのロール管理については elasticsearch-authz を参照してください。

Operations

HTTP API (shorthand)	elastic CLI command
GET cloud:/api/v1/organizations	elastic cloud orgs list-organizations
GET cloud:/api/v1/serverless/regions	elastic cloud serverless regions list-regions
GET cloud:/api/v1/organizations/{org_id}/members	elastic cloud orgs list-organization-members --organization-id <org_id>
POST cloud:/api/v1/organizations/{org_id}/invitations	elastic cloud orgs create-organization-invitations --organization-id <org_id> --input-file <json>
GET cloud:/api/v1/organizations/{org_id}/invitations	elastic cloud orgs list-organization-invitations --organization-id <org_id>
DELETE cloud:/api/v1/organizations/{org_id}/invitations/{tokens}	elastic cloud orgs delete-organization-invitations --organization-id <org_id> --invitation-tokens <csv>
DELETE cloud:/api/v1/organizations/{org_id}/members/{user_ids}	elastic cloud orgs delete-organization-memberships --organization-id <org_id> --user-ids <csv>
POST cloud:/api/v1/users/{user_id}/role_assignments	elastic cloud users add-role-assignments --user-id <user_id> --input-file <json>
DELETE cloud:/api/v1/users/{user_id}/role_assignments	elastic cloud users remove-role-assignments --user-id <user_id> --input-file <json>
POST cloud:/api/v1/users/auth/keys	elastic cloud auth create-api-key --input-file <json>
GET cloud:/api/v1/users/auth/keys	elastic cloud auth get-api-keys
DELETE cloud:/api/v1/users/auth/keys	elastic cloud auth delete-api-keys --input-file <json>
PUT /_security/role/{name}	elastic es security put-role --name <name> --input-file <json>
GET /_security/role	elastic es security get-role
DELETE /_security/role/{name}	elastic es security delete-role --name <name>