OpenAPI を使用して AWS クラウドアカウントを接続する¶
OpenAPI を使用すると、AWS アカウントのロール認可設定の作成、IAM 信頼関係の設定、認可の検証と保存を実行できます。複数アカウントのシナリオでは、AWS アカウントごとに同じ手順を繰り返し実行できます。
準備¶
- OpenAPI サイト一覧 から、ワークスペースが存在するサイトの Endpoint を選択します。
- 対象ワークスペースの API Key を準備します。作成、照会、変更、削除にはクラウドアカウント管理権限
cloudAccount.accountManageが必要です。これら4つのエンドポイントは無料プランのワークスペースでは利用できません。 - 顧客の AWS アカウントの 12 桁のアカウント ID、パーティション、対象の IAM Role 名を準備します。例では国際リージョン(
area=intl、パーティションaws)およびcollection/CloudCollectionを使用します。中国リージョンではarea=cn、パーティションはaws-cnを使用します。 - 実行プログラムが顧客から認可され、対象の AWS アカウントで Role を作成し、収集に必要な権限を追加できることを確認します。AWS CLI の例では、現在の AWS アイデンティティがそのアカウント内の認可済みアイデンティティとして設定されていることを前提としています。
以下の例では、環境変数 API_BASE と DF_API_KEY を使用します。それぞれ Endpoint(末尾スラッシュなし)と、セキュアストレージから読み込んだワークスペース API Key を表します。
1. クラウドアカウント設定の作成¶
AWS Role クラウドアカウントの作成 を呼び出します。config.accountId には顧客自身の AWS アカウント ID を指定します。Role のパスと名前は、次の手順で実際に作成する Role と一致している必要があります。
curl -sS -X POST "$API_BASE/api/v1/cloud_account/do/add" \
-H "DF-API-KEY: $DF_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"provider":"aws","config":{"authType":"assume_role","area":"intl","accountId":"123456789012","roleName":"collection/CloudCollection","accountName":"AWS collection"}}'
content.creationResult.status が created の場合は、以下のフィールドの実際の戻り値を保存します。
| フィールド | 用途 |
|---|---|
content.uuid |
以降の照会、検証、変更、削除に使用するクラウドアカウント識別子 |
content.externalId |
Guance が現在の設定用に生成した External ID |
content.platformAccountId |
IAM 信頼ポリシー内の Guance プラットフォーム AWS アカウント ID |
設定の作成と認可の検証では、それぞれ結果が返されます。初回呼び出し時には Role がまだ作成されていない可能性があり、その場合は creationResult.status=created と validationResult.status=failed が同時に返されることがあります。保存済みの UUID と External ID を使用して、AWS の設定を続行します。
2. IAM Role の作成と信頼ポリシーの設定¶
顧客の AWS アカウントで Role を作成します。以下の JSON を trust-policy.json として保存し、パーティション、プラットフォーム AWS アカウント ID、External ID を置き換えます。信頼ポリシー内のアカウント ID には、前の手順で返された platformAccountId を使用します。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:<partition>:iam::<platformAccountId>:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "<externalId>"
}
}
}
]
}
設定は AWS コンソール、AWS CLI、またはデプロイテンプレートを使用して完了できます。AWS CLI を使用する場合、collection/CloudCollection は Role 名 CloudCollection および IAM パス /collection/ に対応します。
aws iam create-role \
--role-name CloudCollection \
--path /collection/ \
--assume-role-policy-document file://trust-policy.json
aws iam put-role-policy \
--role-name CloudCollection \
--policy-name CloudCollectionRead \
--policy-document file://collection-policy.json
collection-policy.json は顧客の承認済みの収集権限ポリシーです。AWS クラウド統合のロール認可設定 の収集権限 JSON を参照し、実際に収集するサービスに合わせて設定します。信頼ポリシーは誰が Role を引き受けられるかを制御し、権限ポリシーは Role を引き受けた後にアクセスできる AWS リソースを制御します。
一括接続時は、AWS アカウントごとに固有の UUID、パーティション、Role のパス、External ID を管理します。デプロイテンプレートを再利用する場合は、各レコードに対応する値を注入します。同名の Role が既に存在する場合は、アカウント、パス、その Role の用途を確認してから、顧客の IAM 変更プロセスに従って信頼関係と収集権限を更新します。
3. 認可の検証と保存¶
CLOUD_ACCOUNT_UUID に作成時に返された UUID を設定し、AWS Role クラウドアカウントの変更または検証 を呼び出します。
curl -sS -X POST "$API_BASE/api/v1/cloud_account/$CLOUD_ACCOUNT_UUID/do/modify" \
-H "DF-API-KEY: $DF_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"config":{},"dryRun":true}'
dryRun=true では検証のみを実行し、content.saved=false が想定される結果です。content.validationResult.status を読み取ります。結果が passed の場合は、同じ URL に {"config":{},"dryRun":false} を送信します。正式な保存では再検証が行われ、今回のレスポンスで content.saved=true と content.validationResult.status=passed の両方を満たした場合にのみ、認可設定が正常に検証され保存されたことを示します。
検証に失敗した場合は、パーティション、Role のパス、プラットフォームアカウント、External ID を確認します。信頼ポリシーは、External ID がない、または誤った External ID を含む引き受けリクエストを拒否する必要があります。IAM 設定を更新した直後である場合は、同じ UUID で有限回数のバックオフ再試行を実行できます。STS 検証に成功した後、必要に応じて クラウド統合コレクター を設定し、実際の収集権限を検証します。
4. 設定の照会、復元、変更¶
AWS Role クラウドアカウントの照会 を使用して uuid で完全一致検索するか、accountId でページ単位に絞り込みます。一覧のエントリは content.data に、ページ情報はレスポンスのトップレベル pageInfo にあります。
curl -sS --get "$API_BASE/api/v1/cloud_account/do/list" \
-H "DF-API-KEY: $DF_API_KEY" \
--data-urlencode "uuid=$CLOUD_ACCOUNT_UUID"
作成時のレスポンスを失った場合は、まず既存のレコードを照会します。AWS アカウント ID のみを把握している場合、accountId はあいまいフィルタ条件であるため、ページごとに content.data[].config.accountId を完全一致で照合する必要があります。重複作成で ft.CloudAccountAKRepeat が返された場合は、content.existingCloudAccountUUIDs を使用してレコードを特定できます。復元後は、引き続き config.externalId とそのレコードの platformAccountId を使用します。プラットフォーム認可状態が unavailable の場合は、対応するブランドとパーティションのプラットフォーム設定が復元されるのを待ってから、プラットフォームアカウント ID を照会します。
作成時に旧認証情報の競合 ft.CloudAccountLegacyCredentialsConflict が発生した場合は、返された旧レコードの UUID を確認し、関連するコレクターを評価してから、元の設定を処理します。変更インターフェースでは、エイリアス、Role 名、タグをサポートしています。アカウント ID、パーティション、認証タイプ、External ID は既存のレコードによって決まります。タグを更新する際に extraTags を省略すると元の値が保持され、[] を渡すとクリアされます。既存のコレクターは正式保存時に再同期される場合があります。
5. 設定の削除または一時認証情報の取得¶
接続を停止する場合は、対象の UUID と関連するコレクターを確認してから、AWS Role クラウドアカウントの削除 に {} を送信します。削除すると、プラットフォーム設定と関連するコレクター、タスクがクリーンアップされます。顧客の AWS 側の Role は顧客が管理し、過去のオブザーバビリティデータは保持されます。プライベート Func を使用している場合は、アンインストールタスクの実行完了も確認する必要があります。その後で再作成すると、新しい UUID と External ID が生成されるため、新しい値で IAM 信頼ポリシーを設定する必要があります。
アプリケーションで一時認証情報が必要な場合は、cloudAccount.temporaryCredentialsRead 権限を持つ API Key を使用して、AWS 一時認証情報の取得 を呼び出します。このインターフェースは、呼び出しのたびに保存済みの認可をリアルタイムで検証し、有効期限付きの認証情報を返します。認証情報の有効期限に従って使用し、認証情報をログに書き込まないでください。