これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。 翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # AWS CDK CLI リファレンス CDK Toolkit とも呼ばれる AWS Cloud Development Kit (AWS CDK) コマンドラインインターフェイス (AWS CDK CLI) は、 AWS CDK アプリを操作するための主要なツールです。アプリケーションを実行し、定義したアプリケーションモデルを調査し、 AWS CDK によって生成された AWS CloudFormation テンプレートを生成してデプロイします。また、 AWS CDK プロジェクトの作成や操作に役立つその他の機能も提供します。このトピックでは、CDK CLI の一般的なユースケースについて説明します。 CDK CLI は Node Package Manager と共にインストールされます。ほとんどの場合、グローバルにインストールすることが推奨されます。 ``` npm install -g aws-cdk # install latest version npm install -g aws-cdk@X.YY.Z # install specific version ``` **ヒント** AWS CDK の複数のバージョンを定期的に使用する場合は、個々の CDK プロジェクトに CDK CLI の一致するバージョンをインストールすることを検討してください。これを行うには、`npm install` コマンドから `-g` を省略します。次に、`npx aws-cdk` を使用してこれを呼び出します。これにより、ローカルバージョンが存在する場合はローカルバージョンが実行され、存在しない場合はグローバルバージョンに戻ります。 ## CDK CLI コマンド すべての CDK CLI コマンドは `cdk` で始まり、サブコマンド (`list`、`synthesize`、`deploy` など) が続きます。一部のサブコマンドには、同等の短いバージョン (`ls`、`synth` など) があります。オプションと引数は、任意の順序でサブコマンドの後に続きます。 すべてのサブコマンド、オプション、因数の説明については、「[AWS CDK CLI コマンドリファレンス](ref-cli-cmd.md)」を参照してください。 ## オプションとその値を指定する コマンドラインオプションは、2 つのハイフン (`--`) で始まります。よく使用されるオプションの中には、1 つのハイフンで始まる 1 文字のシノニムを持つものがあります (たとえば、`--app` には `-a` というシノニムがあります)。CDK CLI コマンドでは、オプションの順序は重要ではありません。 すべてのオプションは値を受け入れ、値はオプション名の後に記述する必要があります。値は、スペースまたは等号記号 (`=`) で名前と区切ることができます。以下の 2 つのオプションは同じ意味になります。 ``` --toolkit-stack-name MyBootstrapStack --toolkit-stack-name=MyBootstrapStack ``` 一部のオプションはフラグ (ブール値) です。値として `true` または `false` を指定できます。値を指定しない場合、値は `true` と見なされます。また、オプション名に `no-` を付け、`false` を暗示することもできます。 ``` # sets staging flag to true --staging --staging=true --staging true # sets staging flag to false --no-staging --staging=false --staging false ``` いくつかのオプション、具体的には `--context`、`--parameters`、`--plugin`、`--tags`、`--trust` というオプションでは、複数の値を指定するために複数回指定することができます。これらは、CDK CLI のヘルプでは `[array]` 型として記載されています。例えば、次のようになります。 ``` cdk bootstrap --tags costCenter=0123 --tags responsibleParty=jdoe ``` ## 組み込みヘルプ CDK CLI には統合ヘルプが用意されています。以下を実行することで、ユーティリティに関する一般的なヘルプと、提供されているサブコマンドのリストを確認できます。 ``` cdk --help ``` たとえば `deploy` など、特定のサブコマンドのヘルプを表示するには、`--help` フラグの前に指定します。 ``` cdk deploy --help ``` `cdk version` を発行すると、CDK CLI のバージョンが表示されます。サポートをリクエストするときは、この情報を入力します。 ## バージョンのレポート AWS CDK の使用方法を把握するために、 AWS CDK アプリケーションで使用されるコンストラクトは、 として識別されるリソースを使用して収集および報告されます` AWS::CDK::Metadata`。詳細については、[AWS 「CDK 使用状況データレポートの設定](usage-data.md)」を参照してください。 ## による認証 AWS 環境と利用可能なアクセスに応じて、 AWS リソースへのプログラムによる AWS アクセスを設定する方法はさまざまです。 認証方法を選択し、CDK CLI 用に設定するには、[AWS 「CDK CLI のセキュリティ認証情報を設定する](configure-access.md)」を参照してください。 雇用主から認証方法が与えられていない、ローカルで開発する新しいユーザーに推奨されるアプローチは、IAM Identity Center AWS をセットアップすることです。この方法には、設定を容易にし、 AWS アクセスポータルに定期的にサインインするための AWS CLI のインストールが含まれます。この方法を選択した場合、* AWS SDKs およびツールリファレンスガイド*の [IAM アイデンティティセンター認証](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html)の手順を完了した後、環境に次の要素が含まれている必要があります。 + アプリケーションを実行する前に AWS アクセスポータルセッションを開始するために使用する AWS CLI。 + AWS CDK [AWS から参照できる一連の設定値を持つプロファイルを持つ共有設定ファイル](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)。 `[default]`このファイルの場所を確認するには、 * AWS SDKs およびツールリファレンスガイド*[の共有ファイルの場所](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)を参照してください。 + 共有 `config` ファイルは[リージョン](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)設定を設定します。これにより、CDK および AWS CDK CLI が AWS リクエストに使用するデフォルトの AWS リージョンが設定されます。 + CDK CLI は、リクエストを AWSに送信する前に、プロファイルの [SSO トークンプロバイダー設定](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#feature-sso-credentials-profile)を使用して認証情報を取得します。IAM Identity Center アクセス許可セットに接続された IAM ロールである `sso_role_name`値は、アプリケーションで使用される AWS サービスへのアクセスを許可する必要があります。 次のサンプル `config` ファイルは、SSO トークンプロバイダー設定で設定されたデフォルトプロファイルを示しています。プロファイルの `sso_session` 設定は、指定された [`sso-session` セクション](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#section-session)を参照します。`sso-session` セクションには、 AWS アクセスポータルセッションを開始するための設定が含まれています。 ``` [default] sso_session = sso_account_id = <111122223333> sso_role_name = region = output = [sso-session ] sso_region = sso_start_url = sso_registration_scopes = sso:account:access ``` ### AWS アクセスポータルセッションを開始する AWS サービスにアクセスする前に、CDK CLI が IAM Identity Center 認証を使用して認証情報を解決するためのアクティブな AWS アクセスポータルセッションが必要です。設定したセッションの長さによっては、アクセスが最終的に期限切れになり、CDK CLI で認証エラーが発生します。CLI AWS で次のコマンドを実行して、 AWS アクセスポータルにサインインします。 ``` aws sso login ``` SSO トークンプロバイダー設定でデフォルトのプロファイルではなく名前付きプロファイルを使用している場合、コマンドは `aws sso login --profile ` です。`--profile` オプションまたは `AWS_PROFILE` 環境変数を使用して `cdk` コマンドを実行する場合は、このプロファイルも指定します。 アクティブなセッションが既にあるかどうかをテストするには、次の AWS CLI コマンドを実行します。 ``` aws sts get-caller-identity ``` このコマンドへの応答により、共有 `config` ファイルに設定されている IAM Identity Center アカウントとアクセス許可のセットが報告されます。 **注記** 既にアクティブな AWS アクセスポータルセッションがあり、 を実行している場合は`aws sso login`、認証情報を指定する必要はありません。 サインインプロセスでは、CLI AWS にデータへのアクセスを許可するように求められる場合があります。 AWS CLI は SDK for Python 上に構築されているため、アクセス許可メッセージには`botocore`名前のバリエーションが含まれている可能性があります。 ## リージョンおよびその他の設定を指定する CDK CLI は、デプロイ先の AWS リージョンと認証方法を知る必要があります AWS。これは、デプロイ操作および合成中のコンテキスト値の取得に必要です。アカウントとリージョンは、一緒に*環境*を構成します。 リージョンは、環境変数または設定ファイルで指定できます。これらは、 CLI や variousSDK AWS などの他の AWS ツールで使用される変数とファイルと同じです。 AWS SDKs CDK CLI は、この情報を次の順序で検索します。 + `AWS_DEFAULT_REGION` 環境変数。 + 標準 AWS `config`ファイルで定義され、 `cdk` コマンドの `--profile`オプションを使用して指定された名前付きプロファイル。 + 標準 AWS `config`ファイルの `[default]`セクション。 `[default]` セクションで AWS 認証とリージョンを指定するだけでなく、1 つ以上の`[profile ]`セクションを追加することもできます。ここで、 ``はプロファイルの名前です。名前付きプロファイルの詳細については、 SDK およびツールリファレンスガイドの[「共有設定ファイルと認証情報ファイル](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)」を参照してください。 * AWS SDKs * 標準 AWS `config`ファイルは、 `~/.aws/config` (macOS/Linux) または `%USERPROFILE%\.aws\config` (Windows) にあります。詳細と代替の場所については、「 SDK [およびツールリファレンスガイド」の「共有設定ファイルと認証情報ファイルの場所](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)」を参照してください。 * AWS SDKs * スタックの `env`プロパティを使用して AWS CDK アプリケーションで指定する環境は、合成中に使用されます。これは環境固有の AWS CloudFormation テンプレートを生成するために使用されます。デプロイ中に、前述の方法のいずれかで指定されたアカウントまたはリージョンを上書きします。詳細については、[AWS 「CDK の環境](environments.md)」を参照してください。 **注記** AWS CDK は、[AWS コマンドラインインターフェイス](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)を含む他の AWS ツールや SDKs と同じソースファイルからの認証情報を使用します。ただし、 AWS CDK の動作はこれらのツールと多少異なる場合があります。内部で AWS SDK for JavaScript を使用します。 AWS SDK for JavaScript の認証情報の設定の詳細については、[「認証情報の設定](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials.html)」を参照してください。 任意に `--role-arn` (または `-r`) オプションを使用して、デプロイに使用する IAM ロールの ARN を指定できます。このロールは、使用する AWS アカウントによって引き受け可能である必要があります。 ## アプリケーションコマンドを指定する CDK CLI の多くの機能では、1 つ以上の AWS CloudFormation テンプレートを合成する必要があります。合成するには、アプリケーションの実行が必要です。 AWS CDK は、さまざまな言語で記述されたプログラムをサポートしています。そのため、アプリケーションの実行に必要な正確なコマンドを指定するための設定オプションを使用します。このオプションは 2 つの方法で指定できます。 まず、最も一般的なのは、ファイル `cdk.json` 内の `app` キーを使用して指定することです。これは AWS CDK プロジェクトのメインディレクトリにあります。CDK CLI は、`cdk init` で新しいプロジェクトを作成する際に、適切なコマンドを提供します。たとえば、新規の TypeScript プロジェクトの `cdk.json` は以下のようになります。 ``` { "app": "npx ts-node bin/hello-cdk.ts" } ``` CDK CLI は、アプリの実行を試みる際は、現在の作業ディレクトリで `cdk.json` を検索します。このため、CDK CLI コマンドを実行するために、プロジェクトのメインディレクトリでシェルを開いたままにしておくとよいでしょう。 CDK CLI は、`./cdk.json` で見つからない場合、`~/.cdk.json` (つまりホームディレクトリ) でもアプリケーションキーを検索します。通常同じ言語で CDK コードを扱っている場合、アプリコマンドをここに追加しておくと便利です。 他のディレクトリにある場合、または `cdk.json` のコマンド以外のコマンドを使用してアプリを実行する場合は、`--app` (または `-a`) オプションを使用して指定します。 ``` cdk --app "npx ts-node bin/hello-cdk.ts" ls ``` デプロイ時に、`cdk.out` のような合成されたクラウドアセンブリを含むディレクトリを、`--app` の値として指定することもできます。指定されたスタックはこのディレクトリからデプロイされます。アプリは合成されません。 ## スタックを指定する 多くの CDK CLI コマンド (例: `cdk deploy`) は、アプリケーション内で定義されたスタックに対して動作します。アプリケーションに含まれているスタックが 1 つだけの場合、スタックを明示的に指定しなくても、CDK CLI はそのスタックを対象とみなします。 それ以外の場合は、作業対象のスタックを指定する必要があります。これは、コマンドライン上で目的のスタックを ID ごとに個別に指定することで行えます。ID は、スタックをインスタンス化するときに 2 番目の引数で指定された値であることを思い出してください。 ``` cdk synth PipelineStack LambdaStack ``` ワイルドカードを使用して、パターンに一致する ID を指定することもできます。 + `?` は、任意の 1 文字にマッチします + `*` は任意の数の文字にマッチします (`*` 単独ではすべてのスタックにマッチします) + `**` 階層内のすべてにマッチします `--all` オプションを使用してすべてのスタックを指定することもできます。 アプリケーションが [CDK Pipelines](cdk-pipeline.md) を使用している場合、CDK CLI はスタックとステージを階層として理解します。また、`--all` オプションと `*` ワイルドカードは最上位スタックのみに一致します。すべてのスタックにマッチするには、`**` を使用します。また、特定の階層以下のすべてのスタックを示す場合にも、`**` を使用します。 ワイルドカードを使用する場合は、パターンを引用符で囲むか、`\` でワイルドカードをエスケープします。そうしないと、シェルが現在のディレクトリ内のファイルの名前にパターンを展開しようとする可能性があります。良くても期待どおりには動作せず、最悪の場合は、意図していないスタックをデプロイしてしまう恐れがあります。Windows では `cmd.exe` がワイルドカードを展開しないため、厳密には必要ではありませんが、それでもなおこれは良い習慣です。 ``` cdk synth "*Stack" # PipelineStack, LambdaStack, etc. cdk synth 'Stack?' # StackA, StackB, Stack1, etc. cdk synth \* # All stacks in the app, or all top-level stacks in a CDK Pipelines app cdk synth '**' # All stacks in a CDK Pipelines app cdk synth 'PipelineStack/Prod/**' # All stacks in Prod stage in a CDK Pipelines app ``` **注記** スタックを指定する順序は、必ずしも処理される順序ではありません。CDK CLI は、スタックを処理する順序を決定する際に、スタック間の依存関係を考慮します。例えば、あるスタックが別のスタックによって生成された値 (2 番目のスタックで定義されたリソースの ARN など) を使用しているとします。この場合、この依存関係のため、2 番目のスタックは最初のスタックの前に合成されます。スタックの ` [addDependency()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#addwbrdependencytarget-reason) ` メソッドを使用して、スタック間に依存関係を手動で追加できます。 ## AWS 環境のブートストラップ CDK を使用してスタックをデプロイするには、特別な専用 AWS CDK リソースをプロビジョニングする必要があります。`cdk bootstrap` コマンドは、必要なリソースを作成します。これらの専用リソースを必要とするスタックをデプロイする場合にのみ、ブートストラップが必要です。詳細については、「[AWS CDK ブートストラップ](bootstrapping.md)」を参照してください。 ``` cdk bootstrap ``` ここに示すように、引数なしで発行された場合、`cdk bootstrap` コマンドは現在のアプリケーションを合成し、スタックがデプロイされる環境をブートストラップします。環境に依存しないスタックがアプリケーションに含まれ、環境を明示的に指定しない場合、デフォルトのアカウントとリージョンがブートストラップされるか、`--profile` を使用して指定された環境がブートストラップされます。 アプリケーションの外部では、ブートストラップする環境を明示的に指定する必要があります。また、アプリまたはローカル AWS プロファイルで指定されていない環境をブートストラップすることもできます。認証情報は、指定されたアカウントとリージョンに対して設定する必要があります (`~/.aws/credentials` など)。必要な認証情報を含むプロファイルを指定できます。 ``` cdk bootstrap / # e.g. cdk bootstrap 1111111111/us-east-1 cdk bootstrap --profile test 1111111111/us-east-1 ``` **重要** このようなスタックをデプロイする各環境 (アカウントとリージョンの組み合わせ) は、個別にブートストラップする必要があります。 AWS CDK がブートストラップされたリソースに保存するものに対して AWS 料金が発生する場合があります。さらに、 を使用する場合`--bootstrap-customer-key`、KMS AWS キーが作成され、環境ごとに料金が発生します。 **注記** ブートストラップテンプレートの以前のバージョンでは、デフォルトで KMS キーが作成されました。料金が発生しないようにするには、`--no-bootstrap-customer-key` を使用してブートストラップを再起動します。 **注記** CDK CLI v2 は、CDK v1 でデフォルトで使用されているレガシーテンプレートと呼ばれる元のブートストラップテンプレートをサポートしていません。 **重要** 最新のブートストラップテンプレートは、 が暗示するアクセス許可`--cloudformation-execution-policies`を`--trust`リスト内の任意の AWS アカウントに効果的に付与します。デフォルトでは、ブートストラップされたアカウントに任意のリソースへの読み取りおよび書き込みのアクセス許可が拡張されます。使い慣れたポリシーおよび信頼されたアカウントを使用して[ブートストラップスタックを設定](bootstrapping-customizing.md)することを確認してください。 ## 新しいエイリアスの作成 新しいアプリケーションを作成するには、そのアプリケーション用のディレクトリを作成し、ディレクトリ内で `cdk init` を実行します。 ``` mkdir my-cdk-app cd my-cdk-app cdk init