AWS CDK v2 개발자 안내서입니다. 구형 CDK v1은 2022년 6월 1일에 유지 보수에 들어갔고 2023년 6월 1일에 지원이 종료되었습니다.
기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
AWS CDK v1에서 v2로 마이그레이션 AWS CDK
버전 2는 선호하는 프로그래밍 언어로 인프라를 코드로 쉽게 작성할 수 있도록 설계되었습니다. AWS Cloud Development Kit (AWS CDK) 이 항목에서는 v1과 v2 사이의 변경 사항에 대해 설명합니다. AWS CDK
v1에서 v2로의 주요 변경 사항은 다음과 같습니다. AWS CDK CDK
-
AWS CDK v2는 코어 라이브러리를 포함한 AWS 구성 라이브러리의 안정적인 부분을 단일 패키지로 통합합니다.
aws-cdk-lib
개발자는 더 이상 자신이 사용하는 개별 AWS 서비스에 대한 추가 패키지를 설치할 필요가 없습니다. 또한 이 단일 패키지 접근 방식을 사용하면 다양한 CDK 라이브러리 패키지의 버전을 동기화할 필요가 없습니다.에서 AWS CloudFormation사용할 수 있는 정확한 리소스를 나타내는 L1 (CfnXXXX) 구문은 항상 안정적인 것으로 간주되므로 에 포함됩니다.
aws-cdk-lib
-
아직 커뮤니티와 협력하여 새로운 L2 또는 L3 구조를 개발하고 있는 실험용 모듈은 포함되지 않습니다.
aws-cdk-lib
대신 개별 패키지로 배포됩니다. 실험용 패키지의 이름은alpha
접미사와 시맨틱 버전 번호로 지정됩니다. 시맨틱 버전 번호는 호환되는 AWS Construct Library의 첫 번째 버전과 일치하며 접미사도 붙습니다.alpha
구문은 안정 버전으로 지정된aws-cdk-lib
후 안으로 이동하므로 기본 구성 라이브러리는 엄격한 시맨틱 버전 관리를 준수할 수 있습니다.안정성은 서비스 수준에서 지정됩니다. 예를 들어, 이 글을 쓰는 시점에는 L1 구조만 있는 AppFlow Amazon용 L2 구문을 하나 이상 생성하기 시작하면 이 구문은 라는 모듈에 먼저 나타납니다.
@aws-cdk/aws-appflow-alpha
그러다가 새 구조가 고객의aws-cdk-lib
기본적인 요구를 충족한다고 판단되는 시점으로 넘어갑니다.모듈이 안정적인 것으로 지정되어
aws-cdk-lib
통합되면 다음 글머리 기호에 설명된 “BetAn” 규칙을 사용하여 새 APIs 모듈이 추가됩니다.가 출시될 때마다 각 실험 모듈의 새 버전이 릴리스됩니다. AWS CDK하지만 대부분의 경우 동기화된 상태로 유지할 필요가 없습니다. 언제든지
aws-cdk-lib
업그레이드하거나 실험용 모듈을 사용할 수 있습니다. 단, 관련된 두 개 이상의 실험 모듈이 서로 종속되어 있는 경우에는 동일한 버전이어야 합니다. -
새 기능이 추가되는 안정 모듈의 경우 작업이 진행되는 동안 새 모듈 APIs (완전히 새로운 구조이든 기존 구문의 새로운 메서드 또는 속성이든) 에는
Beta1
접미사가 붙습니다. (주요 변경 사항이 필요한 경우 뒤에Beta2
Beta3
, 등이 붙습니다.) 가 스테이블로 API 지정되면 접미사가 API 없는 의 버전이 추가됩니다. 그러면 최신 메서드 (베타 또는 최종) 를 제외한 모든 메서드는 더 이상 사용되지 않습니다.예를 들어 구문에 새
grantPower()
메서드를 추가하면 처음에는 로 표시됩니다.grantPowerBeta1()
주요 변경 사항이 필요한 경우 (예: 새 필수 매개 변수 또는 속성) 메서드의 다음 버전 이름이grantPowerBeta2()
지정되는 식입니다. 작업이 완료되어 작업이 완료되면 접미사 없이grantPower()
메서드가 추가되고 BetAn 메서드는 더 이상 사용되지 않습니다. API모든 베타는 다음 메이저 버전 (3.0) 릴리스까지 Construct Library에 APIs 남아 있으며 시그니처는 변경되지 않습니다. 사용할 경우 지원 중단 경고가 표시되므로 최대한 빠른 API 시일 내에 최종 버전으로 이동해야 합니다. 그러나 향후 AWS CDK 2.x 릴리스에서는 애플리케이션이 손상되지 않습니다.
-
Construct
클래스가 관련 형식과 함께 에서 별도의 라이브러리로 추출되었습니다. AWS CDK 이는 Construct Programming Model을 다른 도메인에 적용하려는 노력을 지원하기 위한 것입니다. 직접 구문을 작성하거나 관련 APIs 구문을 사용하는 경우constructs
모듈을 종속 항목으로 선언하고 임포트를 약간 변경해야 합니다. CDK앱 라이프사이클에 연결하는 등의 고급 기능을 사용하는 경우 추가 변경이 필요할 수 있습니다. 자세한 내용은 를 참조하십시오. RFC -
AWS CDK v1.x 및 해당 구성 라이브러리에서 더 이상 사용되지 않는 속성, 메서드, 형식이 v2에서 완전히 제거되었습니다. CDK API 지원되는 대부분의 언어에서 v1.x에서는 경고 메시지가 표시되므로 이미 대체 언어로 마이그레이션했을 수 있습니다. APIs APIs APIsv1.x에서 더 이상 사용되지 않는 전체 목록은
에서 CDK 확인할 수 있습니다. GitHub -
AWS CDK v1.x에서 기능 플래그에 의해 제한되었던 동작은 v2에서 기본적으로 활성화됩니다. CDK 이전 기능 플래그는 더 이상 필요하지 않으며 대부분의 경우 지원되지 않습니다. 매우 특정한 상황에서 CDK v1 동작으로 되돌릴 수 있는 몇 가지 기능이 아직 남아 있습니다. 자세한 내용은 기능 플래그 업데이트 단원을 참조하십시오.
-
CDKv2에서는 배포하는 환경을 최신 부트스트랩 스택을 사용하여 부트스트랩해야 합니다. 레거시 부트스트랩 스택 (v1의 기본값) 은 더 이상 지원되지 않습니다. CDK또한 v2에는 새 버전의 최신 스택이 필요합니다. 기존 환경을 업그레이드하려면 다시 부트스트랩하세요. 더 이상 최신 부트스트랩 스택을 사용하기 위해 기능 플래그 또는 환경 변수를 설정할 필요가 없습니다.
중요
최신 부트스트랩 템플릿은 에서 암시하는 권한을 목록에 있는 모든 AWS 계정에 효과적으로 부여합니다. --cloudformation-execution-policies
--trust
기본적으로 이렇게 하면 부트스트랩된 계정의 모든 리소스에 대한 읽기 및 쓰기 권한이 확장됩니다. 마음에 드는 정책 및 신뢰할 수 있는 계정으로 부트스트래핑 스택을 구성해야 합니다.
새 사전 요구 사항
v2의 요구 사항 대부분은 AWS CDK v1.x와 동일합니다. AWS CDK 추가 요구 사항은 여기에 나열되어 있습니다.
-
TypeScript 개발자의 경우 TypeScript 3.8 이상이 필요합니다.
-
v2와 함께 CDK 사용하려면 새 버전의 CDK 툴킷이 필요합니다. 이제 CDK v2를 정식 버전으로 사용할 수 있으므로 CDK 툴킷 설치 시 기본 버전은 v2입니다. v1 프로젝트와 이전 버전과 호환되므로 CDK v1 프로젝트를 만들려는 경우가 아니면 이전 버전을 계속 설치하지 않아도 됩니다. CDK 업그레이드하려면 를 실행하세요.
npm install -g aws-cdk
AWS CDK v2 개발자 프리뷰에서 업그레이드
CDKv2 개발자 프리뷰를 사용하는 경우 프로젝트에 릴리스 후보 버전 (예:) 이 AWS CDK종속되어 있는 것입니다. 2.0.0-rc1
이를 로 2.0.0
업데이트한 다음 프로젝트에 설치된 모듈을 업데이트하십시오.
종속성을 업데이트한 후 CDK 툴킷을 릴리스 버전으로 npm update -g aws-cdk
업데이트하도록 실행하십시오.
v1에서 v2로 AWS CDK 마이그레이션 CDK
앱을 AWS CDK v2로 마이그레이션하려면 먼저 기능 플래그를 업데이트하세요. cdk.json
그런 다음 앱이 작성된 프로그래밍 언어에 맞게 필요에 따라 앱의 종속성 및 가져오기를 업데이트하세요.
최신 v1으로 업데이트
많은 고객이 한 번에 이전 버전의 AWS CDK v1을 최신 버전의 v2로 업그레이드하는 것을 목격하고 있습니다. 물론 가능하긴 하지만, 수년에 걸친 변경에 따른 업그레이드 (안타깝게도 모두 현재 진행 중인 에볼루션 테스트 양이 같지는 않을 수도 있음) 뿐만 아니라 새 기본값과 다른 코드 구성을 사용하여 버전 간에 업그레이드해야 할 수도 있습니다.
가장 안전하게 업그레이드하고 예상치 못한 변경의 원인을 더 쉽게 진단하려면 먼저 최신 v1 버전으로 업그레이드한 다음 나중에 v2로 전환하는 두 단계를 구분하는 것이 좋습니다.
기능 플래그 업데이트
다음 v1 기능 플래그가 있는 cdk.json
경우 제거하세요. v2에서는 기본적으로 모두 활성화되기 때문입니다. AWS CDK 이전 효과가 인프라에 중요한 영향을 미치는 경우 소스 코드를 변경해야 합니다. 자세한 GitHub내용은 플래그 목록을
-
@aws-cdk/core:enableStackNameDuplicates
-
aws-cdk:enableDiffNoFail
-
@aws-cdk/aws-ecr-assets:dockerIgnoreSupport
-
@aws-cdk/aws-secretsmanager:parseOwnedSecretName
-
@aws-cdk/aws-kms:defaultKeyPolicies
-
@aws-cdk/aws-s3:grantWriteWithoutAcl
-
@aws-cdk/aws-efs:defaultEncryptionAtRest
특정 AWS CDK v1 동작으로 되돌리기 위해 몇 가지 v1 기능 플래그를 설정할 수 있습니다. 전체 참조는 아래 목록을 참조하십시오v1 동작으로 되돌리기. false
GitHub
두 유형의 플래그 모두에 대해 cdk diff
명령을 사용하여 합성된 템플릿의 변경 사항을 검사하여 이러한 플래그에 대한 변경 사항이 인프라에 영향을 미치는지 확인하십시오.
CDK툴킷 호환성
CDKv2에는 v2 이상의 CDK 툴킷이 필요합니다. 이 버전은 v1 앱과 이전 버전과 호환됩니다. CDK 따라서 v1을 사용하든 v2를 사용하든 관계없이 전 세계적으로 설치된 단일 버전의 CDK 툴킷을 모든 AWS CDK 프로젝트에 사용할 수 있습니다. 단, CDK 툴킷 v2는 v2 프로젝트만 생성하는 CDK 경우는 예외입니다.
v1 및 v2 CDK 프로젝트를 모두 생성해야 하는 경우 CDK툴킷 v2를 전역적으로 설치하지 마십시오. (이미 설치한 경우 제거:.npm remove -g aws-cdk
) CDK툴킷을 호출하려면 를 사용하여 원하는 npx 대로 툴킷 v1 또는 v2를 실행합니다. CDK
npx aws-cdk@1.x init app --language typescript npx aws-cdk@2.x init app --language typescript
작은 정보
cdk및 명령을 사용하여 원하는 버전의 툴킷을 호출할 수 있도록 cdk1 명령줄 별칭을 설정합니다. CDK
종속성 업데이트 및 가져오기
앱의 종속성을 업데이트한 다음 새 패키지를 설치합니다. 마지막으로 코드에서 임포트를 업데이트하세요.
배포하기 전에 마이그레이션된 앱을 테스트하세요.
스택을 배포하기 전에 리소스에 예상치 못한 변경 사항이 있는지 확인하는 cdk diff
데 사용합니다. 논리적 변경 IDs (리소스 대체 원인) 은 예상되지 않습니다.
예상 변경에는 다음이 포함되지만 이에 국한되지는 않습니다.
-
CDKMetadata
리소스 변경. -
자산 해시가 업데이트되었습니다.
-
새로운 스타일의 스택 합성과 관련된 변경 사항. 앱이 v1의 레거시 스택 신시사이저를 사용한 경우에 적용됩니다. (CDKv2는 레거시 스택 신시사이저를 지원하지 않습니다.)
-
CheckBootstrapVersion
규칙 추가.
예상치 못한 변경은 일반적으로 AWS CDK v2로 업그레이드 자체로 인해 발생하지 않습니다. 일반적으로 이러한 오류는 이전에 기능 플래그로 인해 변경된 지원 중단된 동작의 결과입니다. 이는 약 1.85.x CDK 이전 버전에서 업그레이드할 때 나타나는 증상입니다. 최신 v1.x 릴리스로 업그레이드해도 동일한 변경 사항을 확인할 수 있습니다. 일반적으로 다음과 같이 하면 이 문제를 해결할 수 있습니다.
-
앱을 최신 v1.x 릴리스로 업그레이드하세요.
-
기능 플래그 제거
-
필요에 따라 코드를 수정하세요.
-
Deploy
-
v2로 업그레이드
앱에 스택을 배포할 준비가 되면 테스트할 수 있도록 먼저 사본을 배포해 보세요. 가장 쉬운 방법은 다른 지역에 배포하는 것입니다. 하지만 IDs 스택을 변경할 수도 있습니다. 테스트 후에는 를 사용하여 테스트 사본을 삭제해야 합니다. cdk destroy
문제 해결
TypeScript 'from' expected
또는 임포트 중 ';' expected
오류가 발생했습니다.
TypeScript 3.8 이상으로 업그레이드.
'cdk 부트스트랩'을 실행합니다.
다음과 같은 오류가 표시되는 경우:
❌ MyStack failed: Error: MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html) at CloudFormationDeployments.validateBootstrapStackVersion (.../aws-cdk/lib/api/cloudformation-deployments.ts:323:13) at processTicksAndRejections (internal/process/task_queues.js:97:5) MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)
AWS CDK v2에는 업데이트된 부트스트랩 스택이 필요하며, 모든 v2 배포에는 부트스트랩 리소스가 필요합니다. (v1을 사용하면 부트스트래핑 없이 간단한 스택을 배포할 수 있습니다.) 자세한 내용은 AWS CDK 부트스트래핑 섹션을 참조하세요.
v1 스택 찾기
CDK애플리케이션을 v1에서 v2로 마이그레이션할 때 v1을 사용하여 만든 배포된 AWS CloudFormation 스택을 식별하는 것이 좋습니다. 이렇게 하려면 다음 명령어를 실행하세요.
npx awscdk-v1-stack-finder
사용에 대한 자세한 내용은 README