일반적인 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 Toolkit (CLI) 에서 구성 라이브러리와의 불일치를 보고합니다. AWS

cdk명령을 제공하는 AWS CDK 툴킷의 버전은 최소한 기본 AWS 구성 라이브러리 모듈의 버전과 같아야 합니다. aws-cdk-lib 이 툴킷은 이전 버전과 호환되도록 만들어졌습니다. 최신 2.x 버전의 툴킷은 라이브러리의 모든 1.x 또는 2.x 릴리스와 함께 사용할 수 있습니다. 따라서 이 구성 요소를 전역적으로 설치하고 최신 상태로 유지하는 것이 좋습니다.

npm update -g aws-cdk

여러 버전의 AWS CDK 툴킷을 사용해야 하는 경우 프로젝트 폴더에 로컬로 특정 버전의 툴킷을 설치하십시오.

TypeScript 또는 JavaScript 를 사용하는 경우 프로젝트 디렉토리에는 이미 버전이 지정된 툴킷 로컬 사본이 들어 있습니다. CDK

다른 언어를 사용하는 경우 -g 플래그를 npm 생략하고 원하는 버전을 지정하여 AWS CDK 툴킷을 설치할 때 사용하십시오. 예:

npm install aws-cdk@2.0

로컬에 설치된 AWS CDK 툴킷을 실행하려면 only 대신 명령을 npx aws-cdk 사용하십시오. cdk 예:

npx aws-cdk deploy MyStack

npx aws-cdk AWS CDK 툴킷의 로컬 버전이 있는 경우 해당 버전을 실행합니다. 프로젝트에 로컬 설치가 없는 경우 글로벌 버전으로 폴백됩니다. 가 항상 이런 방식으로 호출되도록 셸 별칭을 설정하는 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 또는 로컬 AWS 프로필 (설정 기준aws configure) 에 지정된 지역에서 해당 프로필의 계정을 사용하여 만들 수도 있습니다. 다음과 같이 명령줄에서 다른 계정 및 지역을 지정할 수 있습니다. (앱 디렉터리에 없는 경우 계정 및 지역을 지정해야 합니다.)

cdk bootstrap aws://ACCOUNT-NUMBER/REGION

자세한 내용은 AWS CDK 부트스트래핑 단원을 참조하십시오.

(목록으로 돌아가기)

AWS CDK 스택을 배포할 때 메시지를 받습니다. forbidden: null

부트스트랩 리소스가 필요한 스택을 배포하고 있지만 쓰기 권한이 없는 IAM 역할이나 계정을 사용하고 있습니다. (스테이징 버킷은 자산을 포함하거나 5만 개 이상의 템플릿을 합성하는 스택을 배포할 때 사용됩니다.) AWS CloudFormation 오류 메시지에 언급된 버킷에 s3:* 대해 작업을 수행할 권한이 있는 계정 또는 역할을 사용하십시오.

(목록으로 돌아가기)

AWS CDK 스택을 합성할 때 다음과 같은 메시지가 나타납니다. --app is required either in command-line, in cdk.json or in ~/.cdk.json

이 메시지는 일반적으로 문제가 cdk synth 발생할 때 AWS CDK 프로젝트의 기본 디렉터리에 있지 않다는 의미입니다. 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 툴킷은 다른 두 위치에서 앱의 명령줄을 찾습니다.

  • 홈 cdk.json 디렉터리에서

  • cdk synth명령 자체에서 -a 옵션을 사용하여

예를 들어 다음과 같이 TypeScript 앱에서 스택을 합성할 수 있습니다.

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

(목록으로 돌아가기)

AWS CDK 스택을 합성할 때 AWS CloudFormation 템플릿에 너무 많은 리소스가 포함되어 있어서 오류가 발생합니다.

는 AWS CDK 템플릿을 생성하고 배포합니다. AWS CloudFormation AWS CloudFormation 스택에 포함할 수 있는 리소스 수에는 엄격한 제한이 있습니다. 를 AWS CDK사용하면 예상보다 더 빨리 이 한도에 도달할 수 있습니다.

참고

이 글을 쓰는 시점에서 AWS CloudFormation 리소스 한도는 500입니다. 현재 리소스 AWS CloudFormation 한도는 할당량을 참조하십시오.

AWS Construct Library의 상위 수준 인텐트 기반 구조는 로깅, 키 관리, 권한 부여 및 기타 목적에 필요한 모든 보조 리소스를 자동으로 제공합니다. 예를 들어 한 리소스에 다른 리소스에 대한 액세스 권한을 부여하면 관련 서비스가 통신하는 데 필요한 모든 IAM 객체가 생성됩니다.

경험에 따르면 실제 환경에서 인텐트 기반 구문을 사용하면 구성당 1~5개의 AWS CloudFormation 리소스가 발생하지만 이는 다를 수 있습니다. 서버리스 애플리케이션의 경우 일반적으로 엔드포인트당 5~8개의 리소스가 사용됩니다. AWS API

더 높은 수준의 추상화를 나타내는 패턴을 사용하면 더 적은 코드로 더 많은 AWS 리소스를 정의할 수 있습니다. 예를 예: 를 사용하여 AWS Fargate 서비스 생성 AWS CDK 들어 의 AWS CDK 코드는 구문을 세 개만 정의하면서 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 전문가들은 종종 리소스 제한에 대한 해결책으로 중첩 스택을 사용할 것을 제안합니다. 는 구문을 통해 이 접근 방식을 AWS CDK 지원합니다. NestedStack

(목록으로 돌아가기)

Auto Scaling 그룹 또는 에 대해 세 개 (또는 VPC 그 이상) 의 가용 영역을 지정했지만 두 개에만 배포되었습니다.

요청한 가용 영역 수를 알아보려면 스택의 env 속성에 계정과 지역을 지정하십시오. 둘 다 지정하지 않으면 기본적으로 스택이 AWS CDK환경에 구애받지 않는 것으로 합성됩니다. 그런 다음 를 사용하여 스택을 특정 지역에 배포할 수 있습니다. AWS CloudFormation일부 지역에는 가용 영역이 두 개뿐이므로 환경에 구애받지 않는 템플릿은 가용 영역을 두 개 이상 사용하지 않습니다.

참고

과거에는 가용 영역이 하나뿐인 지역이 출시되는 경우가 있었습니다. 환경에 구애받지 않는 AWS CDK 스택은 이러한 지역에 배포할 수 없습니다. 하지만 이 글을 쓰는 시점에는 모든 AWS 지역에 최소 두 개 이상이 있습니다. AZs

스택의 availablilityZones(Python:availability_zones) 속성을 재정의하여 사용하려는 영역을 명시적으로 지정하여 이 동작을 변경할 수 있습니다.

모든 지역에 배포할 수 있는 유연성을 유지하면서 합성 시 스택의 계정 및 지역을 지정하는 방법에 대한 자세한 내용은 을 참조하십시오. 를 위한 환경 AWS CDK

(목록으로 돌아가기)

발급 시 S3 버킷, DynamoDB 테이블 또는 기타 리소스가 삭제되지 않음 cdk destroy

기본적으로 사용자 데이터를 포함할 수 있는 리소스의 RETAIN 속성은 removalPolicy (Python:removal_policy) 이며 스택이 파괴되어도 리소스는 삭제되지 않습니다. 대신 리소스는 스택에서 분리됩니다. 그런 다음 스택이 파괴된 후 리소스를 수동으로 삭제해야 합니다. 그렇게 하기 전까지는 스택 재배포가 실패합니다. 이는 배포 중에 생성되는 새 리소스의 이름이 분리된 리소스의 이름과 충돌하기 때문입니다.

리소스의 제거 정책을 로 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 설정하고 여기에 데이터가 포함되어 있는 경우, 버킷을 삭제할 수 없으므로 스택 제거 시도가 실패합니다. 버킷의 autoDeleteObjects prop을 로 설정하여 제거를 시도하기 전에 버킷의 객체를 AWS CDK 삭제하도록 할 수 있습니다. true

(목록으로 돌아가기)