cdk deploy - AWS Cloud Development Kit (AWS CDK) v2
사용량인수옵션예시

v AWS CDK 2 개발자 안내서입니다. 이전 CDK v1은 2022년 6월 1일에 유지 관리에 들어갔으며 2023년 6월 1일에 지원을 종료했습니다.

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

cdk deploy

AWS 환경에 AWS CDK 스택을 하나 이상 배포합니다.

배포하는 동안 CDK CLI는 AWS CloudFormation 콘솔에서 볼 수 있는 것과 유사한 진행률 표시기를 출력합니다.

AWS 환경이 부트스트랩되지 않은 경우 자산이 없고 합성 템플릿이 5만 1,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로 자산을 다시 빌드하지 않습니다.

이 옵션은 단일 명령에서 여러 번 지정할 수 있습니다.

기본값: []

--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

--logs BOOLEAN

선택한 스택의 모든 리소스에서 발생한 모든 이벤트에 대한 표준 출력(stdout)에 Amazon CloudWatch 로그를 표시합니다.

이 옵션은 --watch와만 호환됩니다.

기본값: true

--method, -m STRING

배포를 수행하도록 메서드를 구성합니다.

  • change-set - 기본 메서드입니다. CDK CLI는 배포될 변경 사항으로 CloudFormation 변경 세트를 생성한 다음 배포를 수행합니다.

  • direct – 변경 세트를 생성하지 않습니다. 대신 변경 사항을 즉시 적용합니다. 이는 일반적으로 변경 세트를 생성하는 것보다 빠르지만 진행 상황 정보가 손실됩니다.

  • 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 rollback 단원을 참조하십시오.

참고

--no-rollback을 사용하면 리소스 교체를 유발하는 배포는 항상 실패합니다. 이 옵션 값은 새 리소스를 업데이트하거나 생성하는 배포에만 사용할 수 있습니다.

기본값: --rollback

--toolkit-stack-name STRING

기존 CDK Toolkit 스택의 이름입니다.

기본적으로 cdk bootstrap은 지정된 AWS 환경에 CDKToolkit이라는 스택을 배포합니다. 부트스트랩 스택에 다른 이름을 지정하려면 이 옵션을 사용합니다.

CDK CLI는 이 값을 사용하여 부트스트랩 스택 버전을 확인합니다.

--watch BOOLEAN

CDK 프로젝트 파일을 지속적으로 관찰하고, 변경 사항이 탐지되면 지정된 스택을 자동으로 배포합니다.

이 옵션은 기본적으로 --hotswap을 의미합니다.

이 옵션에는 이에 상응하는 CDK CLI 명령이 있습니다. 자세한 내용은 cdk watch 단원을 참조하십시오.

예시

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"
  }
}

이 예에서 키 FunctionArn은 CfnOutput 인스턴스의 논리적 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'