Skip to content

Latest commit

 

History

History
378 lines (258 loc) · 17.5 KB

how-to.md

File metadata and controls

378 lines (258 loc) · 17.5 KB
Raw

HowTo

リポジトリの README に戻る

ここでは各種設定の HowTo について記載します。

Visual Studio Code のセットアップ

テキストエディタの選択は任意ですが、ここでは VSCode を使用した場合のセットアップ手順を記述します。他のテキストエディタを使用する場合、以下のツールと連携可能なものを使用することを強く推奨します。

NOTE:

コード補完や定義箇所へのジャンプなどはVSCode のビルトイン機能を使って実現されています。他のテキストエディタで同等の機能を使用したい場合は、 Language Server Protocol (LSP) をサポートするテキストエディタまたはそのプラグインの利用をご検討ください。

VSCode のインストールと初期設定

Visual Studio Code よりインストールしてください。

macOS の場合、 Running Visual Studio Code on macOS の手順に従い、 code コマンドがシェルから実行できるように設定してください。Windows では自動で設定されます。

VSCode Extension のインストール

後続の手順でこのリポジトリを clone して VSCode で開くと、推奨 Extension のインストールを促されます。ここで Install をクリックします。

VSCode-Recommended-Extensions

この推奨 Extension は .vscode/extensions.json で定義されています。この機能の詳細は Managing Extensions in Visual Studio Code をご参照ください。

VSCode Extension の設定

Ctrl + Shift + p (macOS: Command + Shift + p) を押してコマンドパレットを表示し、 Preferences: Open Settings (JSON) を選択します。以下の設定を追加します。 これによって保存時にコードの Linting、フォーマッティング等が行われるようになります。

    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true
    },
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true,
    "prettier.useEditorConfig": true,

Git の pre-commit hook のセットアップ

simple-git-hooks のセットアップ

BLEA ソースコードのトップディレクトリで以下のコマンドを実行します。

# BLEAのトップディレクトリで
npx simple-git-hooks

Git の hook が設定され(.git/hooks/pre-commit) コミット前に lint-staged が実行されるようになります。

git-secrets のインストールと設定

lint-staged では eslint と prettier によるチェックに加え、git-secrets によるチェックが実行されるよう設定されています(package.json)。

awslabs/git-secrets - GitHub を README に従いインストールしてください。その後、以下のコマンドを実行して git コマンドと連携させます。

git secrets --register-aws --global

次に、ダミーの値として許可される認証情報のリストを登録します。 ~/.gitconfig を編集し、上述のコマンドによって生成された [secrets] セクションを探して以下を追記します。これらは BLEA のソースコード内でダミーとして使用しているアカウント ID です。

    # Fictitious AWS Account ID
    allowed = 111122223333
    allowed = 444455556666
    allowed = 123456789012
    allowed = 777788889999
    allowed = 000000000000
    allowed = 111111111111
    allowed = 222222222222
    allowed = 333333333333

NOTE:

git secrets install は実行しないでください。本プロジェクトでは simple-git-hooksを使用して pre-commit をフックし、ここから git-secrets を呼び出しています。 git secrets install を実行するとフックが競合します。

デプロイ時の承認をスキップしロールバックさせない

cdk コマンドにオプションを指定することで、デプロイ時の挙動をコントロールできます。ここではよく利用される便利な設定について記載します。

デプロイ時の承認をスキップする

通常、CDK によるデプロイを行う場合、承認を求めるプロンプトが表示されますが、cdk のコマンドラインに --require-approval never オプションを指定することで確認のプロンプトが表示されなくなります（ただし利用にはご注意ください！）。

デプロイに失敗してもロールバックさせない

CDK は CloudFormation を使ってデプロイしますが、通常デプロイ時にエラーが発生すると対象スタックはロールバックされ、デプロイを開始する前の状態にまで戻ります。cdk のコマンドラインに-Rまたは--no-rollbackオプションを指定すると、デプロイエラーになったときもロールバックされず、エラーになった時点でデプロイの処理が停止します。エラー内容を修正して再度デプロイすると処理が停止した時点から再開されます。設定の試行錯誤を行う場合に便利です。

cdk.json に設定する方法

以下のようにrequireApprovalとrollbackを cdk.json に設定することで、コマンドで都度設定する必要が無くなります。

{
  "app": "npx ts-node --prefer-ts-exts bin/blea-guest-ecsapp-sample.ts",
  "requireApproval": "never",
  "rollback": false,
  "context": {
    "dev": {

cdk.context.json による個人環境の管理

cdk.json と同じディレクトリに cdk.context.json を置くことで、自分の開発環境のパラメータを指定することができます。このファイルはリポジトリにはコミットされません。このファイルは CDK によって自動的に作成されている場合があります。その場合は既存の設定を残したまま自分自身の Context 定義を追加してください。

cdk.context.json の例

{
  "@aws-cdk/core:enableStackNameDuplicates": "true",
  "aws-cdk:enableDiffNoFail": "true",
  "@aws-cdk/core:stackRelativeExports": "true",
  "my": {
    "description": "Personal Environment variables for blea-guest-*-samples.ts",
    "envName": "Personal",
    "vpcCidr": "10.100.0.0/16",
    "monitoringNotifyEmail": "[email protected]",
    "dbUser": "personaluser",
    "slackNotifier": {
      "workspaceId": "T8XXXXXXXXX",
      "channelIdMon": "C02YYYYYYYY"
    }
  }
}

CloudShell によるデプロイメント

CloudShell を使い、マネジメントコンソールからこのテンプレートをデプロイすることが可能です。 ただし ClouShell は 120 日間使用しないとセットアップした環境のデータを削除することに注意してください。

See: [https://docs.aws.amazon.com/cloudshell/latest/userguide/limits.html]

1. CloudShell を起動する

  • AWS マネジメントコンソールの [>_] アイコンをクリックして CloudShell を起動する (画面右上のアカウント名の隣) OpenConsole

2. CDK の実行環境をセットアップする

See: [https://docs.aws.amazon.com/ja_jp/cdk/latest/guide/getting_started.html]

  • npm をアップデートする
sudo npm -g install npm

3. CDK コードをアップロードする

  1. デプロイ対象の CDK コードをダウンロードし、zip 等でアーカイブする。

  2. CloudShell の画面から [Action]-[Upload File] をクリックし、アーカイブしたファイルをアップロードする UploadFiles

  3. アップロードしたファイルを展開する

  • リモートリポジトリにアクセスできる場合は、CloudShell で git clone して CDK コードを取得することも可能です

4. デプロイ

cd path/to/source
npm ci
# デプロイしたいusecaseのディレクトリに移動する
cd usecases/guest-webapp-sample
npx cdk deploy --all -c environment=dev --profile prof_dev

NOTE:

ビルドは cdk.json に記載されている"app": "npx ts-node --prefer-ts-exts bin/bleadeploy.ts"によって、npx cdk deploy実行時に行われます

依存パッケージの最新化

最新の CDK を使用する場合は、依存する NPM パッケージをアップデートする必要があります。アップデートの手順は次の通りです。これは BLEA のトップディレクトリで行います。

# BLEAのトップディレクトリで
npm update --workspaces

NOTE:

ここで依存パッケージのバージョン不整合が発生した場合、適宜 package.json を修正します。例えば、jest はこのプロジェクトのテストツールとして使用されているため、 package.json に devDependencies として記載されています。aws-cdk も同様に jest に依存しており、 ncu -u によって package.json に記載された jest のバージョンが aws-cdk が必要とするバージョンと一致しなくなるおそれがあります。

環境別のパラメータを切り替えて CDK Stack をデプロイする仕組み

環境別のパラメータは bin/parameter.ts ファイルで管理し、CDK コード（bin/*.ts）の中で次のようにアクセスしています。

import { PjPrefix, DevParameter, StageParameter, ProdParameter } from './parameter';

env: DevParameter.env,

notifyEmail: ProdParameter.securityNotifyEmail,

Application 内で環境別に複数の CDK Stack を準備しているため、デプロイ時に環境を切り替えたい場合はスタック名を指定することでデプロイ対象を絞ることができます。

npx cdk deploy BLEAFSI-Base-Dev --profile prof_dev
npx cdk deploy BLEAFSI-CoreBanking-Prod --profile prof_prod

  • --app を指定しない場合は cdk.json の app で指定している Application がデプロイされます。

  • デプロイする際のプロファイル（認証情報）を指定するには --profile xxxxx を指定します

  • profile で指定する認証情報のアカウントおよびリージョンと、 パラメータファイル の env で指定する、アカウントおよびリージョンは一致している必要があります。これによって誤ったアカウントへデプロイすることを防ぐほか、どのアカウントにどの 環境でデプロイしたのかを記録しておくことにもなります。できるだけ context にはenvを指定することをお勧めします。

  • 開発環境のように開発者ごとに利用するアカウントが違う場合は、パラメータファイル でenvに環境変数を指定する方法があります。この場合は、profile で指定する認証情報のアカウントおよびリージョンにデプロイされます。

通常の開発の流れ

一度デプロイしたあと、 CDK コードを編集してビルド、デプロイする流れは次のようになります。

1. ユースケースディレクトリに移動する

cd usecases/guest-webapp-sample

2. 手元の環境をクリーンナップする

npm run clean

3. CDK コードを編集する

任意のエディタで CDK コードを編集します。（Visutal Studio Code を推奨します）

4. 必要なら追加パッケージをインストールする

CDK コードで追加のパッケージが必要になった場合は、以下のようにインストールします。ここでは @aws-cdk/aws-kms をインストールしています。

# BLEAのルートディレクトリで実行
npm i -P @aws-cdk/aws-kms --workspace usecases/guest-webapp-sample

5. テストする

# linting
npm run lint
# formatting
npm run format
# snapshot test (See NOTE)
npm run test

NOTE:

CDK コードを変更した場合、以前とは異なるテンプレートが生成されるため、スナップショットテスト (npm run test) が失敗します テンプレートが正しく生成されているならば、次のようにスナップショットの更新が必要です。

# Update snapshot
npm run test -- -u

全てのユースケースをテストするには workspaces を使用して次のように実行します。

# BLEAのルートディレクトリで実行
npm ci
npm run lint
npm run format
npm run clean --workspaces
npm run test --workspaces -- -u      # update snaphosts
npm run test --workspaces

個別のユースケースを workspaces を使用してテストするには次のように実行します。workspaces と workspace の違いに注意してください。

# BLEAのルートディレクトリで実行
npm run test --workspace usecases/base-standalone

6. Synth/Diff する

CDK Asset を作成し、現在の環境との差分を確認します。

npx cdk synth --all --app "npx ts-node --prefer-ts-exts bin/blea-guest-ecsapp-sample.ts" -c environment=dev --profile prof_dev --require-approval never --no-rollback
npx cdk diff --all --app "npx ts-node --prefer-ts-exts bin/blea-guest-ecsapp-sample.ts" -c environment=dev --profile prof_dev --require-approval never --no-rollback

7. Deploy する

デプロイします。ここでは承認をスキップし、ロールバックさせないオプションを追加しています。

npx cdk deploy --all --app "npx ts-node --prefer-ts-exts bin/blea-guest-ecsapp-sample.ts" -c environment=dev --profile prof_dev --require-approval never --no-rollback

セキュリティ指摘事項の修復

ガバナンスベースをデプロイした後でも、Security Hub のベンチマークレポートで 重要度が CRITICAL あるいは HIGH のレベルでレポートされる検出項目があります。これらに対しては手動で対応が必要です。

オプション: Security Hub の 検出項目を無効化することもできます（推奨しません。無効化する場合はセキュリティリスクを十分に評価した上で実施して下さい）。

1. ルートユーザに対して MFA を有効化する

ルートユーザに対する MFA の設定は手動で実施する必要があります。ルートユーザとはマネジメントコンソールにログインする際に、E メールアドレスを使ってログインするユーザのことです。

MFA に関連する Security Hub コントロール（CRITICAL レベル）

修復方法

1. Organizations メンバアカウントのルートユーザにアクセスする
2. ルートユーザに対してハードウェア MFA を有効化する

2. EC2 のメタデータアクセスに IMDSv2 を使う

EC2 インスタンスのメタデータアクセスには IDMSv2 のみを使用することが推奨されています。修復については以下のドキュメントを参照してください。