diff --git a/doc/DeployToControlTower.md b/doc/DeployToControlTower.md index a2bc9cbaf..1ea0085ff 100644 --- a/doc/DeployToControlTower.md +++ b/doc/DeployToControlTower.md @@ -111,6 +111,10 @@ Registers a hook to perform checks by Linter, Formatter, and Git-Secrets when co Permanent credentials are also available, but AWS SSO is recommended for ControlTower environments. AWS SSO allows you to log in to the Management Console and run the AWS CLI with SSO authentication. +> NOTE: +> +> Starting with CDK v2.18.0, you can use AWS SSO profiles to deploy the CDK directly, eliminating the need to use wrapping in the authentication process within the profile. + #### 4-1. Check the version of the AWS CLI AWS CLI - To use the AWS SSO integration, you must use AWS CLIv2. @@ -129,83 +133,53 @@ Verify that the output is version 2 or higher aws-cli/2.3.0 Python/3.8.8 Darwin/20.6.0 exe/x86_64 prompt/off ``` -#### 4-2. Introduce aws2-wrap +#### 4-2. Configure an AWS CLI Profile for Audit Account Deployment -AWS CLI - To use AWS SSO integration from a CDK, an open source tool, aws2-wrap ([https://github.com/linaro-its/aws2-wrap]) to the environment where you want to run the CDK - -```sh -pip3 install aws2-wrap -``` - -#### 4-3. Configure an AWS CLI Profile for Audit Account Deployment - -Next, configure a CLI profile for deploying to the Audit account in Control Tower. Here, the ID of the management account is `11111111111` and the ID of the Audit account is `2222222222`. +Next, configure a CLI profile for deploying to the Audit account in Control Tower. Here, the ID of the Audit account is `2222222222`. ~/.aws/config ```text -# for Management Account Login -[profile ct-management-sso] +# for Audit Account +[profile ct-audit] sso_start_url = https://d-90xxxxxxxx.awsapps.com/start#/ sso_region = ap-northeast-1 -sso_account_id = 1111111111111 +sso_account_id = 222222222222 sso_role_name = AWSAdministratorAccess region = ap-northeast-1 - -# Accessing with AWSControlTowerExecution Role on Audit Account -[profile ct-audit-exec-role] -role_arn = arn:aws:iam::222222222222:role/AWSControlTowerExecution -source_profile = ct-management-sso -region = ap-northeast-1 - -# for CDK access to ct-audit-exec-role -[profile ct-audit-exec] -credential_process = aws2-wrap --process --profile ct-audit-exec-role -region = ap-northeast-1 ``` > NOTE: > -> According to the ControlTower specification, in order to deploy to the Audit account, you must first use the `AWSAdministratorAccess` role of the management account You must log in and switch to the `AWSControlTowerExecution` role in the Audit account to perform the action. -> By SSO logging in with the `ct-management-sso`profile, you can use the `ct-audit-exec-role` profile to perform operations on the Audit account It's possible. To access this from the CDK, use the wrapped profile `ct-audit-exec`. +> According to the ControlTower specification, in order to modify the resouces created by ControlTower in the Audit account, you must first use the `AWSAdministratorAccess` role of the management account You must log in and switch to the `AWSControlTowerExecution` role in the Audit account to perform the action. +> BLEA doen't modify resources created by ControlTower, so we use AWSAdministratorAccess role in the Audit account directly. -#### 4-4. Configure an AWS CLI Profile for Guest Account Deployment +#### 4-3. Configure an AWS CLI Profile for Guest Account Deployment Configure an AWS CLI profile for deploying to the guest account. Here, the ID of the guest account is `123456789012`. ~/.aws/config ```text -# for Guest Account Login -[profile ct-guest-sso] +# for Guest Account +[profile ct-guest] sso_start_url = https://d-90xxxxxxxx.awsapps.com/start#/ sso_region = ap-northeast-1 sso_account_id = 123456789012 sso_role_name = AWSAdministratorAccess region = ap-northeast-1 - -# for CDK access to ct-guest-sso -[profile ct-guest] -credential_process = aws2-wrap --process --profile ct-guest-sso -region = ap-northeast-1 ``` -> NOTE: -> -> SSO login to the guest account with the `ct-guest-sso` profile. To access this from the CDK, we use the wrapped profile `ct-guest`. - -#### 4-5. CLI login using AWS SSO +#### 4-4. CLI login using AWS SSO -Log in to AWS SSO with the following command: Here is an example of logging in with `ct-guest-sso`profile. +Log in to AWS SSO with the following command: Here is an example of logging in with `ct-guest`profile. ```sh -aws sso login --profile ct-guest-sso +aws sso login --profile ct-guest ``` This command launches a browser and displays the AWS SSO login screen. If you have entered the guest account administrator username (email address) and password correctly, the screen will return to the terminal, where you can use the AWS CLI to work with the guest account. -> Notes: The `ct-guest` profile authenticates via aws2-warp and is used when running a CDK. - ### 5. Set a baseline for notifications in the Audit account (Local) The Audit account has an SNS Topic created by ControlTower that sends all AWS Config change notifications. Set a baseline to notify Slack of this content. @@ -238,7 +212,7 @@ usecases/base-ct-audit/cdk.json "dev-audit": { "description": "Context samples for ControlTower Audit Account - Specific account & region", "env": { - "account": "333333333333", + "account": "222222222222", "region": "ap-northeast-1" }, "slackNotifier": { @@ -271,24 +245,22 @@ The contents of this setting are as follows. Log in to your management account using AWS SSO with the following command: -> Audit accounts can only be set up with the `AWSControlTowerExecution` role in the management account (ControlTower specification) - ```sh -aws sso login --profile ct-management-sso +aws sso login --profile ct-audit ``` Bootstrap a bucket for CDK to the Audit account (first time only) ```sh cd usecases/base-ct-audit -npx cdk bootstrap -c environment=dev-audit --profile ct-audit-exec +npx cdk bootstrap -c environment=dev-audit --profile ct-audit ``` Deploy a governance base to the Audit account ```sh cd usecases/base-ct-audit -npx cdk deploy --all -c environment=dev-audit --profile ct-audit-exec +npx cdk deploy --all -c environment=dev-audit --profile ct-audit ``` You should now be notified of all AWS Config change events for accounts managed by this ControlTower. @@ -333,7 +305,7 @@ usecases/base-ct-guest/cdk.json "stage": { "description": "Context samples for Staging - Specific account & region ", "env": { - "account": "111111111111", + "account": "123456789012", "region": "ap-northeast-1" }, "envName": "Staging", @@ -364,7 +336,7 @@ The contents of this setting are as follows. Log in to your guest account using AWS SSO. ```sh -aws sso login --profile ct-guest-sso +aws sso login --profile ct-guest ``` Bootstrap a bucket for CDK (first time only). @@ -441,7 +413,7 @@ Configure the Context using the same steps as in the Standalone version. (If you are not logged in) Log in to your guest account using AWS SSO. ```sh -aws sso login --profile ct-guest-sso +aws sso login --profile ct-guest ``` Deploy a guest application. diff --git a/doc/DeployToControlTower_ja.md b/doc/DeployToControlTower_ja.md index 527d13ba3..e432584d2 100644 --- a/doc/DeployToControlTower_ja.md +++ b/doc/DeployToControlTower_ja.md @@ -111,6 +111,10 @@ Git に Commit する際に Linter, Formatter, git-secrets によるチェック 恒久的な認証情報も利用可能ですが、ControlTower 環境では AWS SSO の利用を推奨します。AWS SSO によって、マネジメントコンソールへのログインおよび SSO 認証による AWS CLI の実行が可能です。 +> NOTE: +> +> CDK v2.18.0 以降、AWS SSO のプロファイルを使って CDK を直接デプロイできるようになり、プロファイル内の認証プロセスでラッピングを使う必要がなくなりました。 + #### 4-1. AWS CLI のバージョンを確認する AWS CLI - AWS SSO 統合を使うためには、AWS CLIv2 を使う必要があります。 @@ -129,84 +133,52 @@ aws --version aws-cli/2.3.0 Python/3.8.8 Darwin/20.6.0 exe/x86_64 prompt/off ``` -#### 4-2. aws2-wrap を導入する +#### 4-2. Audit アカウントデプロイ用の AWS CLI プロファイルを設定する -AWS CLI - AWS SSO 統合を CDK から使用するため、オープンソースのツールである aws2-wrap ([https://github.com/linaro-its/aws2-wrap]) を CDK を実行する環境にインストールします - -```sh -pip3 install aws2-wrap -``` - -#### 4-3. Audit アカウントデプロイ用の AWS CLI プロファイルを設定する - -次に、Control Tower の Audit アカウントにデプロイするための CLI プロファイルを設定します。ここではマネジメントアカウントの ID を `1111111111111`, Audit アカウントの ID を `222222222222` としています。 +次に、Control Tower の Audit アカウントにデプロイするための CLI プロファイルを設定します。ここでは Audit アカウントの ID を `222222222222` としています。 ~/.aws/config ```text -# for Management Account Login -[profile ct-management-sso] +# for Audit Account +[profile ct-audit] sso_start_url = https://d-90xxxxxxxx.awsapps.com/start#/ sso_region = ap-northeast-1 -sso_account_id = 1111111111111 +sso_account_id = 222222222222 sso_role_name = AWSAdministratorAccess region = ap-northeast-1 - -# Accessing with AWSControlTowerExecution Role on Audit Account -[profile ct-audit-exec-role] -role_arn = arn:aws:iam::222222222222:role/AWSControlTowerExecution -source_profile = ct-management-sso -region = ap-northeast-1 - -# for CDK access to ct-audit-exec-role -[profile ct-audit-exec] -credential_process = aws2-wrap --process --profile ct-audit-exec-role -region = ap-northeast-1 ``` > NOTE: > -> ControlTower の仕様により、Audit アカウントにデプロイするためには、まずマネジメントアカウントの `AWSAdministratorAccess` ロールでログインし、Audit アカウントの`AWSControlTowerExecution`ロールにスイッチして処理を実行する必要があります。 -> -> `ct-management-sso`プロファイルで SSO ログインすることで、`ct-audit-exec-role`プロファイルを使って Audit アカウント上での操作が可能です。これに CDK からアクセスするため、ラッピングされたプロファイルである `ct-audit-exec` を使用します。 +> ControlTower の仕様により、ControlTower が Audit アカウントにデプロイしたリソースを変更する場合は、まずマネジメントアカウントの `AWSAdministratorAccess` ロールでログインし、Audit アカウントの`AWSControlTowerExecution` ロールにスイッチして処理を実行する必要があります。BLEA は ControlTower が作成したリソースを変更しないため、直接 Audit アカウントの AWSAdministratorAccess ロールを使用しています -#### 4-4. ゲストアカウントデプロイ用の AWS CLI プロファイルを設定する +#### 4-3. ゲストアカウントデプロイ用の AWS CLI プロファイルを設定する ゲストアカウントにデプロイするための AWS CLI プロファイルを設定します。ここではゲストアカウントの ID を`123456789012`としています。 ~/.aws/config ```text -# for Guest Account Login -[profile ct-guest-sso] +# for Guest Account +[profile ct-guest] sso_start_url = https://d-90xxxxxxxx.awsapps.com/start#/ sso_region = ap-northeast-1 sso_account_id = 123456789012 sso_role_name = AWSAdministratorAccess region = ap-northeast-1 - -# for CDK access to ct-guest-sso -[profile ct-guest] -credential_process = aws2-wrap --process --profile ct-guest-sso -region = ap-northeast-1 ``` -> NOTE: -> -> `ct-guest-sso`プロファイルで ゲストアカウントに SSO ログインします。これに CDK からアクセスするため、ラッピングされたプロファイルである `ct-guest` を使用します。 - -#### 4-5. AWS SSO を使った CLI ログイン +#### 4-4. AWS SSO を使った CLI ログイン -次のコマンドで AWS SSO にログインします。ここでは`ct-guest-sso`プロファイルでログインする例を示します。 +次のコマンドで AWS SSO にログインします。ここでは`ct-guest`プロファイルでログインする例を示します。 ```sh -aws sso login --profile ct-guest-sso +aws sso login --profile ct-guest ``` このコマンドによって ブラウザが起動し、AWS SSO のログイン画面が表示されます。ゲストアカウントの管理者ユーザー名（メールアドレス）とパスワードを正しく入力すると画面がターミナルに戻り、 AWS CLI で ゲストアカウントでの作業が可能になります。 -> Notes: `ct-guest`プロファイルは aws2-warp を経由した認証を行なっており、CDK を実行する場合に使用します。 - ### 5. Audit アカウントに通知用のベースラインを設定する(Local) Audit アカウントには ControlTower が作成した、すべての AWS Config の変更通知が送られる SNS Topic があります。この内容を Slack に通知するようベースラインを設定します。 @@ -239,7 +211,7 @@ usecases/base-ct-audit/cdk.json "dev-audit": { "description": "Context samples for ControlTower Audit Account - Specific account & region", "env": { - "account": "333333333333", + "account": "222222222222", "region": "ap-northeast-1" }, "slackNotifier": { @@ -271,24 +243,22 @@ usecases/base-ct-audit/cdk.json 以下のコマンドで AWS SSO を使ってマネジメントアカウントにログインします。 -> Audit アカウントは マネジメントアカウントの `AWSControlTowerExecution` ロールでのみセットアップが可能です（ControlTower の仕様） - ```sh -aws sso login --profile ct-management-sso +aws sso login --profile ct-audit ``` Audit アカウントに CDK 用バケットをブートストラップします(初回のみ) ```sh cd usecases/base-ct-audit -npx cdk bootstrap -c environment=dev-audit --profile ct-audit-exec +npx cdk bootstrap -c environment=dev-audit --profile ct-audit ``` Audit アカウントにガバナンスベースをデプロイします ```sh cd usecases/base-ct-audit -npx cdk deploy --all -c environment=dev-audit --profile ct-audit-exec +npx cdk deploy --all -c environment=dev-audit --profile ct-audit ``` 以上で、この ControlTower 管理下にあるアカウントのすべての AWS Config 変更イベントが通知されるようになります。 @@ -332,7 +302,7 @@ usecases/base-ct-guest/cdk.json "stage": { "description": "Context samples for Staging - Specific account & region ", "env": { - "account": "111111111111", + "account": "123456789012", "region": "ap-northeast-1" }, "envName": "Staging", @@ -363,7 +333,7 @@ usecases/base-ct-guest/cdk.json AWS SSO を使ってゲストアカウントにログインします。 ```sh -aws sso login --profile ct-guest-sso +aws sso login --profile ct-guest ``` CDK 用バケットをブートストラップします(初回のみ)。 @@ -439,7 +409,7 @@ Standalone 版と同じ手順で Context を設定します。 （ログインしていない場合）AWS SSO を使ってゲストアカウントにログインします。 ```sh -aws sso login --profile ct-guest-sso +aws sso login --profile ct-guest ``` ゲストアプリケーションをデプロイします。 diff --git a/doc/PipelineDeployment.md b/doc/PipelineDeployment.md index f612006cd..b00a17e88 100644 --- a/doc/PipelineDeployment.md +++ b/doc/PipelineDeployment.md @@ -47,7 +47,7 @@ You can also deploy applications directly from your local environment without pi ### Prerequisities - Bootstrapped account (Tools account (ID: `222222222222`)) and region to which the pipeline will be deployed -- An AWS CLI profile with credentials to access the Tools account with Administrator privileges (referred to as `blea-pipeline-tool-exec` in this document) +- An AWS CLI profile with credentials to access the Tools account with Administrator privileges (referred to as `blea-pipeline-tool` in this document) > **Note** we recommend that you use administrative credentials to an account only to bootstrap it and provision the initial pipeline. Otherwise, access to administrative credentials should be dropped as soon as possible. (Reference : [CDK Pipelines Doc](https://docs.aws.amazon.com/cdk/api/v1/docs/pipelines-readme.html)) @@ -232,40 +232,36 @@ When adding account information, you have to edit `cdk.json` as following Prerequisity: Profile of Prod Account is set like following ``` -[profile blea-pipeline-prod-sso] +[profile blea-pipeline-prod] sso_start_url = https://xxxxxxxxxxxx.awsapps.com/start#/ sso_region = ap-northeast-1 sso_account_id = 333333333333 sso_role_name = AWSAdministratorAccess region = ap-northeast-1 - -[profile blea-pipeline-prod-exec] -credential_process = aws2-wrap --process --profile blea-pipeline-prod-sso -region = ap-northeast-1 ``` 1. Login to Prod Account via SSO ```sh -aws sso login --profile blea-pipeline-prod-sso +aws sso login --profile blea-pipeline-prod ``` 2. Bootstrap Prod Account ```sh -npx cdk bootstrap --profile blea-pipeline-prod-exec --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess --trust 222222222222 aws://333333333333/ap-northeast-1 -c environment=prod +npx cdk bootstrap --profile blea-pipeline-prod --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess --trust 222222222222 aws://333333333333/ap-northeast-1 -c environment=prod ``` 3. Bootstrap Tools Account ```sh -npx cdk bootstrap -c environment=dev --profile blea-pipeline-tool-exec --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess aws://222222222222/ap-northeast-1 +npx cdk bootstrap -c environment=dev --profile blea-pipeline-tool --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess aws://222222222222/ap-northeast-1 ``` 4. Deploy pipeline to Tools account ```sh -npx cdk deploy -c environment=dev --profile blea-pipeline-tool-exec +npx cdk deploy -c environment=dev --profile blea-pipeline-tool ``` ## Appendix B - Deploy copy of application stack to Development Account @@ -298,16 +294,12 @@ When actually developing a system using the CDK, it is necessary to deploy the s ``` ``` -[profile blea-pipeline-dev-sso] +[profile blea-pipeline-dev] sso_start_url = https://xxxxxxxxxxxx.awsapps.com/start#/ sso_region = ap-northeast-1 sso_account_id = xxxxxxxxxxxx sso_role_name = AWSAdministratorAccess region = ap-northeast-1 - -[profile blea-pipeline-dev-exec] -credential_process = aws2-wrap --process --profile blea-pipeline-dev-sso -region = ap-northeast-1 ``` ### Deploy Stack itself directly to the Development environment @@ -315,7 +307,7 @@ region = ap-northeast-1 For example, if you want to deploy with `BLEA-ECSApp` defined in `BLEA-Dev-Stage`, deploy to the Dev account with the following command ``` -npx cdk deploy BLEA-Dev-Stage/BLEA-ECSApp -c environment=dev --profile=blea-pipeline-dev-exec +npx cdk deploy BLEA-Dev-Stage/BLEA-ECSApp -c environment=dev --profile=blea-pipeline-dev ``` In addition, you can check the list of stacks (e.g. `BLEA-Dev-Stage/BLEA-ECSApp` in the above command) that can be deployed by the following command diff --git a/doc/PipelineDeployment_ja.md b/doc/PipelineDeployment_ja.md index 4308c06b5..a567669ef 100644 --- a/doc/PipelineDeployment_ja.md +++ b/doc/PipelineDeployment_ja.md @@ -47,7 +47,7 @@ CodePipeline がソースコードを取得するために必要な設定を実 ### 前提条件 - パイプラインのデプロイ先のアカウント（以下、 Tools アカウント（ID: `222222222222`））およびリージョンで CDK をブートストラップ済みであること -- Tools アカウントに Administrator 権限でアクセスする認証情報を AWS CLI プロファイルとして設定済みであること（本ドキュメントでは `blea-pipeline-tool-exec` プロファイルを使用） +- Tools アカウントに Administrator 権限でアクセスする認証情報を AWS CLI プロファイルとして設定済みであること（本ドキュメントでは `blea-pipeline-tool` プロファイルを使用） > **Note** Administrator 権限は CDK のブートストラップを行う際と、パイプラインをデプロイする際に必要な権限となります。セキュリティの観点から、パイプラインのデプロイが完了したら Administrator 権限を外すことが推奨されます（ [CDK Pipelines のドキュメント](https://docs.aws.amazon.com/cdk/api/v1/docs/pipelines-readme.html) より）。 @@ -155,9 +155,9 @@ const prodStack = new BLEAPipeline.BLEAPipelineStack(app, `${pjPrefix}-Prod-Pipe ```sh npm ci cd usecase/guest-webapp-sample/ -npx cdk bootstrap -c environment=dev --profile blea-pipeline-tool-exec # If you haven't bootstrapped target account +npx cdk bootstrap -c environment=dev --profile blea-pipeline-tool # If you haven't bootstrapped target account -npx cdk deploy -c environment=dev --profile blea-pipeline-tool-exec +npx cdk deploy -c environment=dev --profile blea-pipeline-tool ``` ### 4. BLEA のコードを更新し変更を Push することで、デプロイを実行する @@ -243,16 +243,12 @@ new BLEAPipelineStack(app, `${pjPrefix}-Pipeline`, { 以下のような形で、Prod アカウントの Profile が設定されているとします。 ``` -[profile blea-pipeline-prod-sso] +[profile blea-pipeline-prod] sso_start_url = https://xxxxxxxxxxxx.awsapps.com/start#/ sso_region = ap-northeast-1 sso_account_id = 333333333333 sso_role_name = AWSAdministratorAccess region = ap-northeast-1 - -[profile blea-pipeline-prod-exec] -credential_process = aws2-wrap --process --profile blea-pipeline-prod-sso -region = ap-northeast-1 ``` 次のとおり手順を実施することで、Tools アカウントから Prod アカウントに対してクロスアカウントなアプリケーションのデプロイを実施することが可能になります。 @@ -260,25 +256,25 @@ region = ap-northeast-1 1. Prod アカウントに SSO でログインする ```sh -aws sso login --profile blea-pipeline-prod-sso +aws sso login --profile blea-pipeline-prod ``` 2. Prod アカウントのブートストラップを実施する ```sh -npx cdk bootstrap --profile blea-pipeline-dev-exec --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess --trust 222222222222 aws://333333333333/ap-northeast-1 -c environment=prod +npx cdk bootstrap --profile blea-pipeline-prod --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess --trust 222222222222 aws://333333333333/ap-northeast-1 -c environment=prod ``` 3. Tools アカウントのブートストラップを実施する ```sh -npx cdk bootstrap -c environment=dev --profile blea-pipeline-tool-exec --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess aws://222222222222/ap-northeast-1 +npx cdk bootstrap -c environment=dev --profile blea-pipeline-tool --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess aws://222222222222/ap-northeast-1 ``` 4. Tools アカウントに対してパイプラインをデプロイする ```sh -npx cdk deploy -c environment=dev --profile blea-pipeline-tool-exec +npx cdk deploy -c environment=dev --profile blea-pipeline-tool ``` この Tools アカウントにデプロイされたパイプラインによりアプリケーションがビルド・デプロイされます。 @@ -308,16 +304,12 @@ npx cdk deploy -c environment=dev --profile blea-pipeline-tool-exec ``` ``` -[profile blea-pipeline-dev-sso] +[profile blea-pipeline-dev] sso_start_url = https://xxxxxxxxxxxx.awsapps.com/start#/ sso_region = ap-northeast-1 sso_account_id = xxxxxxxxxxxx sso_role_name = AWSAdministratorAccess region = ap-northeast-1 - -[profile blea-pipeline-dev-exec] -credential_process = aws2-wrap --process --profile blea-pipeline-dev-sso -region = ap-northeast-1 ``` ### 開発環境にスタックを直接デプロイする @@ -325,7 +317,7 @@ region = ap-northeast-1 例えば、`BLEA-Dev-Stage` 中で定義されている `BLEA-ECSApp` を指定してデプロイしたい場合は以下のコマンドによって Dev アカウントにデプロイすることができます。 ``` -npx cdk deploy BLEA-Dev-Stage/BLEA-ECSApp -c environment=dev --profile=blea-pipeline-dev-exec +npx cdk deploy BLEA-Dev-Stage/BLEA-ECSApp -c environment=dev --profile=blea-pipeline-dev ``` なお、以下のようなコマンドによってデプロイできるスタック (上記コマンドにおける`BLEA-Dev-Stage/BLEA-ECSApp`に相当するもの) の一覧を確認することができます