一般的な AWS CDK 問題のトラブルシューティング - AWS Cloud Development Kit (AWS CDK) v2

これは AWS CDK v2 デベロッパーガイドです。古い CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

一般的な AWS CDK 問題のトラブルシューティング

このトピックでは、 に関する以下の問題のトラブルシューティング方法について説明します AWS CDK。

を更新した後 AWS CDK、 AWS CDK ツールキット (CLI) AWS は コンストラクトライブラリとの不一致を報告します。

Toolkit のバージョン AWS CDK ( cdk コマンドを提供) は、メインの Construct Library AWS モジュールのバージョン と少なくとも同じである必要がありますaws-cdk-lib。ツールキットは下位互換性を目的としています。ツールキットの最新の 2.x バージョンは、ライブラリの任意の 1.x または 2.x リリースで使用できます。このため、このコンポーネントをグローバルにインストールし、最新の状態に保つことをお勧めします。

npm update -g aws-cdk

複数のバージョンの AWS CDK Toolkit を使用する必要がある場合は、プロジェクトフォルダにローカルに特定のバージョンのツールキットをインストールします。

TypeScript または を使用している場合 JavaScript、プロジェクトディレクトリには CDK Toolkit のバージョン管理されたローカルコピーが既に含まれています。

別の言語を使用している場合は、 を使用して AWS CDK Toolkit をインストールnpmし、 -gフラグを省略して目的のバージョンを指定します。例:

npm install aws-cdk@2.0

ローカルにインストールされた AWS CDK Toolkit を実行するには、 npx aws-cdkだけでなく、 コマンドを使用しますcdk。例:

npx aws-cdk deploy MyStack

npx aws-cdk ローカルバージョンの AWS CDK Toolkit が存在する場合、 はそれを実行します。プロジェクトにローカルインストールがない場合、グローバルバージョンにフォールバックします。cdk 常にこの方法で が呼び出されるようにシェルエイリアスを設定すると便利な場合があります。

macOS/Linux
alias cdk="npx aws-cdk"
Windows
doskey cdk=npx aws-cdk $*

( のリストに戻る）

AWS CDK スタックをデプロイするときに NoSuchBucket エラーが表示される

AWS 環境はブートストラップされていないため、デプロイ中にリソースを保持する Amazon S3 バケットがありません。次のコマンドを使用して、ステージングバケットおよびその他の必要なリソースを作成できます。

cdk bootstrap aws://ACCOUNT-NUMBER/REGION

予想外の AWS 料金が発生しないように、 AWS CDK は環境を自動的にブートストラップしません。デプロイ先の各環境を明示的にブートストラップする必要があります。

デフォルトでは、ブートストラップリソースは、現在の AWS CDK アプリケーションのスタックで使用される 1 つまたは複数のリージョンに作成されます。または、ローカル AWS プロファイルで指定されたリージョン ( で設定aws configure) に、そのプロファイルのアカウントを使用して作成されます。次のように、コマンドラインで別のアカウントとリージョンを指定できます。（アプリの ディレクトリにない場合は、アカウントとリージョンを指定する必要があります）。

cdk bootstrap aws://ACCOUNT-NUMBER/REGION

詳細については、「ブートストラッピング」を参照してください。

( のリストに戻る）

AWS CDK スタックをデプロイするときに、 というforbidden: nullメッセージが表示されます。

ブートストラップリソースを必要とするスタックをデプロイしていますが、そのスタックに書き込むアクセス許可がない IAM ロールまたはアカウントを使用しています。（ステージングバケットは、アセットを含むスタックや 50K を超える AWS CloudFormation テンプレートを合成するスタックをデプロイするときに使用されます）。エラーメッセージに記載されているバケットs3:*に対してアクションを実行するアクセス許可を持つアカウントまたはロールを使用します。

( のリストに戻る）

AWS CDK スタックを合成するときに、 というメッセージが表示されます。 --app is required either in command-line, in cdk.json or in ~/.cdk.json

このメッセージは通常、 を発行したときに AWS CDK プロジェクトのメインディレクトリにないことを意味しますcdk synth。cdk init コマンドによって作成されたcdk.jsonこのディレクトリの ファイルには、 AWS CDK アプリケーションの実行 (および合成) に必要なコマンドラインが含まれています。例えば、 TypeScript アプリの場合、デフォルトは次のcdk.jsonようになります。

{
  "app": "npx ts-node bin/my-cdk-app.ts"
}

AWS CDK ツールキットがcdk.jsonそこで見つけてアプリケーションを正常に実行できるように、プロジェクトのメインディレクトリでのみcdkコマンドを発行することをお勧めします。

何らかの理由でこれが実用的でない場合、 AWS CDK ツールキットは他の 2 つの場所でアプリケーションのコマンドラインを探します。

  • ホームディレクトリcdk.jsonの 内

  • -a オプションを使用したcdk synthコマンド自体で

例えば、次のように TypeScript アプリケーションからスタックを合成できます。

cdk synth --app "npx ts-node my-cdk-app.ts" MyStack

( のリストに戻る）

AWS CDK スタックを合成するときに、テンプレートに含まれるリソースが多すぎるため AWS CloudFormation 、エラーが発生します。

は AWS CloudFormation templates AWS CDK を生成してデプロイします。 AWS CloudFormation スタックに含めることができるリソースの数には厳しい制限があります。を使用すると AWS CDK、この制限に対して予想よりも迅速に実行できます。

注記

この書き込みの AWS CloudFormation リソース制限は 500 です。現在のリソース制限のAWS CloudFormation クォータを参照してください。

AWS Construct Library の上位レベルのインテントベースのコンストラクトは、ログ記録、キー管理、認可、およびその他の目的に必要な補助リソースを自動的にプロビジョニングします。例えば、あるリソースへのアクセス権を別のリソースに付与すると、関連するサービスが通信するために必要な IAM オブジェクトが生成されます。

経験上、インテントベースのコンストラクトを実際に使用すると、コンストラクトごとに 1～5 AWS CloudFormation リソースになりますが、これは異なる場合があります。サーバーレスアプリケーションでは、API エンドポイントあたり 5～8 AWS リソースが一般的です。

より高いレベルの抽象化を表すパターンを使用すると、コードの数を減らしてさらに多くの AWS リソースを定義できます。例えばを使用した AWS Fargate サービスの作成 AWS CDK、 の AWS CDK コードは、3 つのコンストラクトのみを定義しながら 50 を超える AWS CloudFormation リソースを生成します。

AWS CloudFormation リソース制限を超えると、 AWS CloudFormation 合成中にエラーが発生します。スタックが制限の 80% を超えると AWS CDK 、警告が表示されます。スタックに maxResourcesプロパティを設定することで別の制限を使用することも、 を 0 maxResourcesに設定して検証を無効にすることもできます。

ヒント

次のユーティリティスクリプトを使用して、合成された出力内のリソースの正確な数を取得できます。（すべての AWS CDK デベロッパーには Node.js が必要なため、スクリプトは で記述されます） JavaScript。

// rescount.js - count the resources defined in a stack
// invoke with: node rescount.js <path-to-stack-json>
// e.g. node rescount.js cdk.out/MyStack.template.json
  
import * as fs from 'fs';
const path = process.argv[2];
  
if (path) fs.readFile(path, 'utf8', function(err, contents) {
  console.log(err ? `${err}` : 
  `${Object.keys(JSON.parse(contents).Resources).length} resources defined in ${path}`);
}); else console.log("Please specify the path to the stack's output .json file");

スタックのリソース数が制限に近づいたら、再設計してスタックに含まれるリソースの数を減らすことを検討してください。例えば、いくつかの Lambda 関数を組み合わせたり、スタックを複数のスタックに分割したりします。CDK はスタック 間の参照をサポートしているため、アプリの機能をさまざまなスタックに分割できます。

注記

AWS CloudFormation エキスパートは多くの場合、リソース制限のソリューションとしてネストされたスタックの使用を提案します。は、 NestedStackコンストラクトを介してこのアプローチ AWS CDK をサポートします。

( のリストに戻る）

Auto Scaling グループまたは VPC に 3 つ (またはそれ以上) のアベイラビリティーゾーンを指定しましたが、デプロイされたのは 2 つのみです

リクエストするアベイラビリティーゾーンの数を取得するには、スタックの envプロパティでアカウントとリージョンを指定します。両方を指定しない場合、 は AWS CDKデフォルトでスタックを環境に依存しないものとして合成します。その後、 を使用してスタックを特定のリージョンにデプロイできます AWS CloudFormation。一部のリージョンには 2 つのアベイラビリティーゾーンしかないため、環境に依存しないテンプレートでは 2 つ以上のアベイラビリティーゾーンを使用しません。

注記

以前は、リージョンは 1 つのアベイラビリティーゾーンのみで起動していました。環境に依存しない AWS CDK スタックをそのようなリージョンにデプロイすることはできません。ただし、この記事では、すべての AWS リージョンに少なくとも 2 つの AZs。

スタックの availablilityZones (Python: availability_zones) プロパティを上書きして、使用するゾーンを明示的に指定することで、この動作を変更できます。

スタックのアカウントとリージョンを合成時に指定し、どのリージョンにもデプロイできる柔軟性を維持する方法の詳細については、「」を参照してください環境。

( のリストに戻る）

S3 バケット、DynamoDB テーブル、またはその他のリソースが問題発生時に削除されない cdk destroy

デフォルトでは、ユーザーデータを含むことができるリソースには removalPolicy (Python: removal_policy) プロパティ がありRETAIN、スタックが破棄されてもリソースは削除されません。代わりに、リソースはスタックから孤立します。その後、スタックが破棄されたら、リソースを手動で削除する必要があります。これを行うまでは、スタックの再デプロイは失敗します。これは、デプロイ中に作成される新しいリソースの名前が、孤立したリソースの名前と競合するためです。

リソースの削除ポリシーを に設定した場合DESTROY、スタックが破棄されると、そのリソースは削除されます。

TypeScript
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';
  
export class CdkTestStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
  
    const bucket = new s3.Bucket(this, 'Bucket', {
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });
  }
}
JavaScript
const cdk = require('aws-cdk-lib');
const s3 = require('aws-cdk-lib/aws-s3');
  
class CdkTestStack extends cdk.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);
  
    const bucket = new s3.Bucket(this, 'Bucket', {
      removalPolicy: cdk.RemovalPolicy.DESTROY
    });
  }
}

module.exports = { CdkTestStack }
Python
import aws_cdk as cdk
from constructs import Construct
import aws_cdk.aws_s3 as s3

class CdkTestStack(cdk.stack):
    def __init__(self, scope: Construct, id: str, **kwargs):
        super().__init__(scope, id, **kwargs)
        
        bucket = s3.Bucket(self, "Bucket",
            removal_policy=cdk.RemovalPolicy.DESTROY)
Java
software.amazon.awscdk.*;
import software.amazon.awscdk.services.s3.*;
import software.constructs;

public class CdkTestStack extends Stack {
    public CdkTestStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public CdkTestStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);

        Bucket.Builder.create(this, "Bucket")
                .removalPolicy(RemovalPolicy.DESTROY).build();
    }
}
C#
using Amazon.CDK;
using Amazon.CDK.AWS.S3;

public CdkTestStack(Construct scope, string id, IStackProps props) : base(scope, id, props)
{
    new Bucket(this, "Bucket", new BucketProps {
        RemovalPolicy = RemovalPolicy.DESTROY
    });
}
注記

AWS CloudFormation は空でない Amazon S3 バケットを削除することはできません。Amazon S3 バケットの削除ポリシーを に設定しDESTROY、データが含まれている場合、バケットを削除できないため、スタックを破棄しようとすると失敗します。バケットの autoDeleteObjectsprop を に設定することで、破棄を試みる前にバケット内のオブジェクト AWS CDK を削除できますtrue。

( のリストに戻る）