AWS

AWSの接続は、CloudFormationテンプレートに基づく自動化されたフローです。Polylaneがインフラへの書き込みアクセスを得ることはありません。スタックは、Polylaneがクロスアカウントで引き受ける読み取り専用ロールだけを付与します。

セットアップ

1. 12桁のAWS Account IDを入力します。
2. 接続するAWS Regionを選びます。
3. Deploy stack on AWSをクリックします。テンプレートが読み込まれた状態でCloudFormationコンソールにリダイレクトされます。
4. テンプレートを確認し、Create stackをクリックします。
5. スタックは、Polylaneが引き受ける読み取り専用アクセスのIAMロールを作成します。
6. Polylaneに戻ります。数分以内にリソースの同期が始まります。

CloudFormationテンプレートは公開されています。スタックを作成する前に、どの権限が付与されるかを正確に確認できます。

権限

IAMロールは厳密に読み取り専用です。

• AWS管理のReadOnlyAccessポリシー
• 書き込み、削除、変更の権限はなし
• PolylaneのAWSアカウントからのクロスアカウントでの引き受けのみ

アラームの調査

接続時に、アカウント内のCloudWatch AlarmsをPolylaneに購読させることができます。アラームが発火すると、Polylaneがそれを拾い上げて自動的に調査します。これは任意で、後から変更できます。

接続解除

AWSアカウントでCloudFormationスタックを削除します。これによりIAMロールと、スタックが作成した他のすべてのリソースが取り除かれます。Polylaneからアカウントを接続解除することもでき、その場合はすべての同期が停止します。

ガイド付きのフローは、誰かがAWSコンソールで開くCloudFormationのクイック作成リンクで終わります。AWSアカウントがコードレビューとパイプラインを通じてのみ変更されるなら、それをクリックする人はいません。同じ接続は完全にCIジョブの中に収まります。1回のAPI呼び出しが接続を作成してCloudFormationテンプレートを生成し、自分のツールがテンプレートをデプロイし、スタックが自らアカウントをPolylaneに登録します。

テンプレートのYAMLだけが必要な場合は、コンソールの接続ダイアログのAdvancedの下にも、CopyとDownloadボタン付きでインラインで表示されます。以下のフローにはコンソールはまったく必要ありません。

前提条件

• cloud_accounts:writeとcloud_accounts:readスコープを持つPolylane APIキー。APIキーとOAuthを参照してください。
• ws_で始まるワークスペースID。同じキーでGET /v1/workspacesから読み取ります。
• 接続するアカウントでCloudFormationスタックをデプロイし、IAMロールを作成できる、パイプライン内のAWS認証情報。

接続を作成する

curl -X POST https://api.polylane.com/v1/cloud_accounts \
  -H "x-api-key: $POLYLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws",
    "workspaceId": "ws_0abc123",
    "account": "123456789012",
    "regions": ["us-east-1", "eu-west-1"]
  }'

accountは12桁のAWSアカウントIDです。regionsはPolylaneが各同期でスキャンするリージョンを列挙します。nullを渡すと、アカウントで有効なすべてのリージョンを各同期時に解決してスキャンします。任意の2つの真偽値createMonitoringAlarmsとsubscribeToAlarmsは、クラウドで説明されているアラートの動作を制御し、既定はtrueです。

応答には、フローの残りに必要なものがすべて含まれます。

{
  "success": true,
  "result": {
    "provider": "aws",
    "url": "https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?...",
    "s3Url": "https://....s3.amazonaws.com/...?X-Amz-Expires=3600&...",
    "region": "us-east-1",
    "templateBody": "Description: This template creates the resources necessary for Polylane to observe your AWS Account\n..."
  }
}

• result.templateBodyは、この接続用に生成されたCloudFormationテンプレートをインラインで持つため、ジョブはそれを直接ファイルに書き出せます。
• result.s3Urlは同じテンプレートへの署名付きリンクです。1時間で期限が切れます。
• result.regionはスタックをデプロイするリージョンです。テンプレートはちょうどこのリージョン向けに生成されます。
• result.urlは、ガイド付きのフローが使うコンソールのクイック作成リンクです。ここでは無視してください。

409は、アカウントがすでに接続されていることを意味します。既存の接続のリージョンを変更するには、再接続する代わりにPATCH /v1/cloud_accounts/{workspaceId}/{id}を使います。

テンプレートをファイルに書き出す

result.templateBodyをファイルに書き出すか、署名付きリンクからダウンロードします。

curl -o polylane-connector.yaml "<result.s3Url>"

テンプレートはデプロイできる状態で届きます。そのExternalParameterパラメーターの既定値は、この接続用に生成された外部IDです。これはスタックが作成するロールのsts:ExternalId条件になり、Polylaneはそのロールを引き受けるたびに同じIDを提示します。ファイルは生成されたとおりにデプロイし、パラメーターの既定値には触れないでください。外部IDを編集したスタックはデプロイ自体は成功しますが、決して登録できません。

その外部IDがあるからこそ、このファイルは認証情報として扱う価値があります。コミットしたりビルドアーティファクトとして公開したりせず、パイプラインの実行の中にとどめてください。

デプロイ前に署名付きリンクの期限が切れた場合は、接続エンドポイントをもう一度呼び出して新しいテンプレートを取得します。アカウントが登録されるまでは呼び出しを繰り返しても安全です。登録後は409を返します。

スタックをデプロイする

aws cloudformation deploy \
  --stack-name PolylaneConnector \
  --template-file polylane-connector.yaml \
  --capabilities CAPABILITY_IAM \
  --region us-east-1

手順1のregionを使います。CAPABILITY_IAMは、スタックが作成するIAMロールを承認します。ロール自体は無名で、名前付きのインラインポリシーにはCAPABILITY_NAMED_IAMは不要なため、CAPABILITY_IAMで十分です。

スタックは、Polylaneが引き受けるロール（読み取り専用アクセスに加え、polylaneプレフィックス付きリソースに対する操作）、そのインラインポリシー、新しいS3バケットに書き込むCloudTrailのトレイル、トレイルとアラームの通知用のSNSトピック、そしてレポーターのカスタムリソースを作成します。レポーターが接続を登録するものです。スタックの作成中にPolylaneへロールのARNを渡すため、設定するコールバックも、他に実行するものもありません。

Terraformから同じデプロイを行う場合は次のとおりです。

resource "aws_cloudformation_stack" "polylane_connector" {
  name          = "PolylaneConnector"
  template_body = file("${path.module}/polylane-connector.yaml")
  capabilities  = ["CAPABILITY_IAM"]
}

プロバイダー、またはプロバイダーのエイリアスを手順1のregionに向けます。s3Urlをtemplate_urlに渡すのではなく、保存したファイルをtemplate_bodyで参照してください。署名付きリンクは1時間も、次のplanまでも持たないため、テンプレートの取得はそれを適用する同じ実行の中で行います。

アカウントがオンラインになるのを確認する

アカウントは、スタックのレポーターがPolylaneに到達すると表示されます。通常はスタックの完了直後です。自然キーでポーリングしてください。登録が届くまでは404、その後は200を返します。

until curl -sf "https://api.polylane.com/v1/cloud_accounts/ws_0abc123/aws/123456789012/us-east-1" \
  -H "x-api-key: $POLYLANE_API_KEY" > /dev/null; do
  sleep 15
done

失敗したデプロイがジョブを止めたままにするのではなく失敗させるように、ループに期限を設けてください。アカウントが存在するようになると、そのstatusフィールドが最初の同期を追跡します。登録時はnew、リソースが流れ込んでいる間はsyncing、最初の同期が完了するとreadyです。

curl -s "https://api.polylane.com/v1/cloud_accounts/ws_0abc123/aws/123456789012/us-east-1" \
  -H "x-api-key: $POLYLANE_API_KEY" | jq -r '.result.status'

ここからは、アカウントはコンソールから接続したものとまったく同じように動作します。リソースはトポロジーに同期され、Polylaneは自ら最初のチェックを実行し、アカウントページが埋まっていきます。

APIから接続解除する

接続を削除すると、アカウント内のCloudFormationスタックも削除されます。この呼び出しにはcloud_accounts:deleteスコープが必要です。

curl -X DELETE https://api.polylane.com/v1/cloud_accounts/ws_0abc123/<cloud-account-id> \
  -H "x-api-key: $POLYLANE_API_KEY"

ロール、そのポリシー、CloudTrailのS3バケットはDeletionPolicy: Retainを持つため、スタックの削除後も残ります。AWSアカウントを完全にきれいにしたい場合は、自分で取り除いてください。