cdk deploy - AWS Cloud Development Kit (AWS CDK) v2
使用引数オプション例

これは AWS CDK v2 開発者ガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。

cdk deploy

AWS 環境に 1 つ以上の AWS CDK スタックをデプロイします。

デプロイ中、CDK CLI は AWS CloudFormation コンソールから観察できるものと同様の進行状況インジケータを出力します。

AWS 環境がブートストラップされていない場合、アセットがなくて合成されたテンプレートが 51,200 バイト未満のスタックのみが正常にデプロイされます。

使用

$ cdk deploy <arguments> <options>

引数

CDK スタック ID

デプロイするアプリからの CDK スタックのコンストラクト ID。

タイプ: 文字列

必須: いいえ

オプション

すべての CDK CLI コマンドで動作するグローバルオプションのリストについては、「グローバルオプション」を参照してください。

--all <BOOLEAN>

CDK アプリにすべてのスタックをデプロイします。

デフォルト値: false

--asset-parallelism <BOOLEAN>

アセットを並行して構築および公開するかどうかを指定します。

--asset-prebuild <BOOLEAN>

最初のスタックをデプロイする前に、すべてのアセットを構築するかどうかを指定します。このオプションは、Docker のビルドが失敗する場合に役立ちます。

デフォルト値: true

--build-exclude, -E <ARRAY>

指定された ID でアセットを再構築しないでください。

このオプションは 1 つのコマンドで複数回指定できます。

デフォルト値: []

--change-set-name <STRING>

作成する AWS CloudFormation の変更セットの名前。

このオプションは --method='direct' と互換性がありません。

--concurrency <NUMBER>

スタック間の依存関係を考慮しながら、複数のスタックを並行してデプロイします。このオプションを使用してデプロイを高速化します。この場合も、AWS CloudFormation やその他の AWS アカウントのレート制限を考慮する必要があります。

実行する同時デプロイ (依存関係がある場合) の最大数を指定する数値を指定します。

デフォルト値: 1

--exclusively, -e <BOOLEAN>

要求されたスタックのみをデプロイし、依存関係を含めないでください。

--force, -f <BOOLEAN>

デプロイして既存のスタックを更新すると、CDK CLI はデプロイされたスタックのテンプレートおよびタグを、デプロイされるスタックと比較します。変更が検出されない場合、CDK CLI はデプロイをスキップします。

変更が検出されない場合でも、この動作を上書きしてスタックを常にデプロイするには、このオプションを使用します。

デフォルト値: false

--help, -h <BOOLEAN>

cdk deploy コマンドのコマンドリファレンス情報を表示します。

--hotswap <BOOLEAN>

開発を高速化するためのホットスワップデプロイ。可能な場合、このオプションはより高速なホットスワップデプロイの実行を試みます。例えば、CDK アプリで Lambda 関数のコードを変更した場合、CDK CLI は CloudFormation デプロイを実行するのではなく、サービス API を介してリソースを直接更新します。

CDK CLI がホットスワップをサポートしていない変更を検出した場合、それらの変更は無視されてメッセージが表示されます。完全な CloudFormation デプロイをフォールバックとして実行する場合、代わりに --hotswap-fallback を使用します。

CDK CLI は、現在の AWS 認証情報を使用して API コールを実行します。@aws-cdk/core:newStyleStackSynthesis 機能フラグが true に設定されている場合でも、ブートストラップスタックからロールを引き受けることはありません。CloudFormation を使用しない場合、これらのロールには AWS リソースを直接更新するために必要なアクセス許可がありません。そのため、認証情報がホットスワップデプロイを実行しているスタックの AWS アカウントと同じであり、リソースを更新するために必要な IAM アクセス許可があることを確認してください。

現在、ホットスワップは次の変更でサポートされています。

  • Lambda 関数のコードアセット (Docker イメージおよびインラインコードを含む)、タグの変更、設定の変更 (説明変数および環境変数のみをサポート)。

  • Lambda バージョンおよびエイリアスの変更。

  • AWS Step Functions ステートマシンの定義の変更。

  • Amazon ECS サービスのコンテナアセットの変更。

  • Amazon S3 バケットデプロイのウェブサイトアセットの変更。

  • AWS CodeBuild プロジェクトのソースおよび環境の変更。

  • AWS AppSync リゾルバーおよび関数の VTL マッピングテンプレートの変更。

  • AWS AppSync GraphQL API のスキーマの変更。

特定の CloudFormation 組み込み関数の使用は、ホットスワップデプロイの一部としてサポートされています。具体的には次のとおりです。

  • Ref

  • Fn::GetAtt – 部分的にのみサポートされています。サポートされているリソースおよび属性については、この実装を参照してください。

  • Fn::ImportValue

  • Fn::Join

  • Fn::Select

  • Fn::Split

  • Fn::Sub

このオプションは、ネストされたスタックとも互換性があります。

注記

  • このオプションは、デプロイを高速化するために CloudFormation スタックに意図的にドリフトを導入します。このため、開発目的にのみ使用してください。本番環境のデプロイにはこのオプションを使用しないでください。

  • このオプションは実験的と考えられており、今後は大幅な変更行われる場合があります。

  • 特定のパラメータのデフォルトは、ホットスワップパラメータとは異なる場合があります。例えば、Amazon ECS サービスの最小正常率は、現在 0 に設定されます。これが発生した場合、必要に応じてソースを確認してください。

デフォルト値: false

--hotswap-fallback <BOOLEAN>

このオプションは --hotswap に似ています。違いは、必要な変更が検出された場合、--hotswap-fallback は CloudFormation の完全なデプロイを実行するためにフォールバックすることです。

このオプションの詳細については、「--hotswap」を参照してください。

デフォルト値: false

--ignore-no-stacks <BOOLEAN>

CDK アプリにスタックが含まれていない場合でも、デプロイを実行してください。

このオプションは次のシナリオで役立ちます。dev や prod など、複数の環境を持つアプリある場合があります。開発を開始すると、本番環境アプリにリソースがないか、リソースがコメントアウトされている場合があります。アプリにスタックがないことを示すメッセージを含むデプロイエラーが発生します。--ignore-no-stacks を使用してこのエラーをバイパスします。

デフォルト値: false

--import-existing-resources <BOOLEAN>

AWS アカウントから、既存の管理されていない AWS CloudFormation リソースをインポートします。

このオプションを使用すると、同じアカウントの既存の管理されていないリソースと同じカスタム名を持つ合成された AWS CloudFormation テンプレートのリソースが、スタックにインポートされます。

このオプションを使用して、既存のリソースを新規または既存のスタックにインポートできます。

既存のリソースをインポートし、同じ cdk deploy コマンドで新しいリソースをデプロイできます。

カスタム名の詳細については、「AWS CloudFormation ユーザーガイド」の「名前タイプ」を参照してください。

ImportExistingResources CloudFormation パラメータの詳細については、「AWS CloudFormation が ChangeSet の新しいパラメータを使用してリソースのインポートを簡素化」を参照してください。

このオプションの使用の詳細については、「aws-cdk-cli GitHub リポジトリ」の「既存のリソースをインポートする」を参照してください。

--logs <BOOLEAN>

選択したスタック内のすべてのリソースによるすべてのイベントについて、標準出力 (stdout) で Amazon CloudWatch Logs を表示します。

このオプションは --watch とのみ互換性があります。

デフォルト値: true

--method, -m <STRING>

メソッドを設定してデプロイを実行します。

  • change-set – デフォルトのメソッド。CDK CLI はデプロイされる変更を使用して CloudFormation 変更セットを作成したら、デプロイを実行します。

  • direct – 変更セットを作成しないでください。代わりに、すぐに変更を適用してください。これは通常、変更セットを作成するよりもすばやく実行できますが、CLI 出力のデプロイ進行状況の詳細が失われます。

  • prepare-change-set – 変更セットを作成しますが、デプロイは実行しません。変更セットを検査する外部ツールがある場合、あるいは変更セットの承認プロセスがある場合に便利です。

有効な値:change-set 、direct、prepare-change-set

デフォルト値: change-set

--notification-arns <ARRAY>

CloudFormation がスタック関連イベントについて通知する Amazon SNS トピックの ARN。

--outputs-file, -O <STRING>

デプロイからのスタック出力が書き込まれるパス。

デプロイ後、スタック出力は JSON 形式で指定された出力ファイルに書き込まれます。

このオプションは、プロジェクトの cdk.json ファイルまたはローカル開発マシンの ~/.cdk.jsonで設定できます。

{
   "app": "npx ts-node bin/myproject.ts",
   // ...
   "outputsFile": "outputs.json"
}

複数のスタックがデプロイされている場合、出力は同じ出力ファイルに書き込まれ、スタック名を表すキーで整理されます。

--parameters <ARRAY>

デプロイ中に追加のパラメータを CloudFormation に渡します。

このオプションは、STACK:KEY=VALUE の形式の配列を受け入れます。

  • STACK – パラメータを関連付けるスタックの名前。

  • KEY – スタックのパラメータの名前。

  • VALUE – デプロイ時に渡す値。

スタック名が指定されていない場合、あるいは * がスタック名として指定されている場合、パラメータはデプロイされるすべてのスタックに適用されます。スタックがパラメータを活用しない場合、デプロイは失敗します。

パラメータはネストされたスタックには伝達されません。ネストされたスタックにパラメータを渡すには、 NestedStack コンストラクトを使用します。

デフォルト値: {}

--previous-parameters <BOOLEAN>

既存のパラメータに以前の値を使用します。

このオプションが false に設定されているとき、すべてのデプロイにすべてのパラメータを指定する必要があります。

デフォルト値: true

--progress <STRING>

CDK CLI がデプロイの進行状況を表示する方法を設定します。

  • bar – リソースのイベントが現在デプロイされている状態で、スタックデプロイイベントを進行状況バーとして表示します。

  • events – すべての CloudFormation イベントを含む完全な履歴を提供します。

このオプションは、プロジェクトの cdk.json ファイルまたはローカル開発マシンの ~/.cdk.json で設定することもできます。

{
   "progress": "events"
}

有効な値:bar 、events

デフォルト値: bar

--require-approval <STRING>

手動承認が必要なセキュリティ上機密性の高い変更を指定します。

  • any-change – スタックへの変更に手動承認が必要です。

  • broadening – 変更に許可やセキュリティグループルールの拡大を伴う場合、手動承認が必要です。

  • never – 承認は必要ありません。

有効な値:any-change 、broadening、never

デフォルト値: broadening

--rollback | --no-rollback, -R

デプロイ中にリソースの作成または更新に失敗した場合、CDK CLI が戻る前にデプロイは最新の安定状態にロールバックします。その時点までに行われたすべての変更は元に戻されます。作成されたリソースは削除され、更新プログラムはロールバックされます。

--no-rollback を指定してこの動作をオフにします。リソースの作成または更新に失敗した場合、CDK CLI はその時点までに行われた変更をそのままにして戻ります。デプロイは失敗した一時停止状態になります。ここからはコードを更新し、デプロイを再試行できます。すばやく反復する開発環境に役立ちます。

--no-rollback で実行されたデプロイが失敗し、デプロイをロールバックすることを決定した場合、cdk rollback コマンドを使用できます。詳細については、「cdk ロールバック」を参照してください。

注記

--no-rollback では、リソースの置き換えの原因となるデプロイは常に失敗します。このオプション値は、新しいリソースを更新または作成するデプロイにのみ使用できます。

デフォルト値: --rollback

--toolkit-stack-name <STRING>

既存の CDK Toolkit スタックの名前。

デフォルトでは、cdk bootstrap は指定された AWS 環境に CDKToolkit という名前のスタックをデプロイします。このオプションを使用し、ブートストラップスタックに別の名前を指定します。

CDK CLI はこの値を使用してブートストラップスタックのバージョンを検証します。

--watch <BOOLEAN>

CDK プロジェクトファイルを継続的に監視し、変更が検出されると指定されたスタックを自動的にデプロイします。

このオプションはデフォルトで --hotswap を暗示します。

このオプションには同等の CDK CLI コマンドがあります。詳細については、「cdk ウォッチ」を参照してください。

例

MyStackName という名前のスタックのデプロイ

$ cdk deploy MyStackName --app='node bin/main.js'

アプリに複数のスタックのデプロイ

cdk list を使用してスタックを一覧表示します。

$ cdk list
CdkHelloWorldStack
CdkStack2
CdkStack3

すべてのスタックをデプロイするには、--all オプションを使用します。

$ cdk deploy --all

デプロイするスタックを選択するには、スタック名を引数として指定します。

$ cdk deploy CdkHelloWorldStack CdkStack3

パイプラインスタックのデプロイ

cdk list を使用してスタック名をパスとして表示し、パイプライン階層内の場所を示します。

$ cdk list
PipelineStack
PiplelineStack/Prod
PipelineStack/Prod/MyService

--all オプションまたはワイルドカード * を使用し、すべてのスタックをデプロイします。上記のスタックの階層がある場合、--all および * は最上位のスタックのみに一致します。階層内のすべてのスタックを一致させるには、** を使用します。

これらのパターンを組み合わせることができます。次の内容は、Prod ステージ内のすべてのスタックをデプロイします。

$ cdk deploy PipelineStack/Prod/**

デプロイ時にパラメータを渡す

CDK スタックでパラメータを定義します。次の内容は、Amazon SNS トピックに TopicNameParam という名前のパラメータを作成する例です。

new sns.Topic(this, 'TopicParameter', {
    topicName: new cdk.CfnParameter(this, 'TopicNameParam').value.toString()
});

parameterized のパラメータ値を指定するには、次の内容を実行します。

$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterized"

--force オプションを使用してパラメータ値を上書きできます。次の内容は、以前のデプロイからトピック名を上書きする例です。

$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterName" --force

デプロイ後にスタック出力のファイル書き込み

CDK スタックファイルに出力を定義します。次の内容は、関数 ARN 用に出力を作成する例です。

const fn = new lambda.Function(this, "fn", {
  handler: "index.handler",
  code: lambda.Code.fromInline(`exports.handler = \${handler.toString()}`),
  runtime: lambda.Runtime.NODEJS_LATEST
});

new cdk.CfnOutput(this, 'FunctionArn', {
  value: fn.functionArn,
});

スタックをデプロイし、出力を outputs.json に書き込みます。

$ cdk deploy --outputs-file outputs.json

次の内容は、デプロイ後の outputs.json の例です。

{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  }
}

この例では、 キーCfnOutput は FunctionArn インスタンスの論理 IDに対応します。

次の内容は、複数のスタックがデプロイされたとき、デプロイ後の outputs.json 例です。

{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  },
  "AnotherStack": {
    "VPCId": "vpc-z0mg270fee16693f"
  }
}

デプロイ方法の変更

変更セットを使用せずに迅速にデプロイするには、--method='direct' を使用します。

$ cdk deploy --method='direct'

変更セットを作成してもデプロイしない場合、--method='prepare-change-set' を使用します。デフォルトでは、cdk-deploy-change-set という名前の変更セットが作成されます。この名前が付いた以前の変更セットが存在する場合、上書きされます。変更が検出されない場合でも、空の変更セットが作成されます。

変更セットに名前を付けることもできます。以下に例を示します。

$ cdk deploy --method='prepare-change-set' --change-set-name='MyChangeSetName'