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

AWS CDK와 함께 사용할 환경을 부트스트래팅

AWS 환경을 부트스트랩하여 AWS Cloud Development Kit (AWS CDK) 스택 배포를 준비합니다.

환경을 부트스트래핑하는 방법

AWS CDK Command Line Interface(AWS CDK CLI) 또는 선호하는 AWS CloudFormation 배포 도구를 사용하여 환경을 부트스트래핑할 수 있습니다.

CDK CLI 사용

CDK CLI cdk bootstrap 명령을 사용하여 환경을 부트스트래핑할 수 있습니다. 부트스트래핑을 크게 수정할 필요가 없는 경우 권장되는 방법입니다.

cdk bootstrap 명령과 지원되는 옵션에 대한 자세한 내용은 cdk bootstrap 섹션을 참조하세요.

모든 AWS CloudFormation 도구 사용

aws-cdk GitHub 리포지토리에서 부트스트랩 템플릿을 복사하거나 cdk bootstrap --show-template 명령으로 템플릿을 가져올 수 있습니다. 그런 다음 AWS CloudFormation 도구를 사용하여 템플릿을 환경에 배포합니다.

이 방법으로 AWS CloudFormation StackSets 또는 AWS Control Tower를 사용할 수 있습니다. AWS CloudFormation 콘솔 또는 AWS Command Line Interface(AWS CLI)를 사용할 수도 있습니다. 템플릿을 배포하기 전에 수정할 수 있습니다. 이 방법은 더 유연하고 대규모 배포에 적합할 수 있습니다.

다음은 --show-template 옵션을 사용하여 부트스트랩 템플릿을 검색하고 로컬 시스템에 저장하는 예입니다.

macOS/Linux

$ cdk bootstrap --show-template > bootstrap-template.yaml

Windows

Windows에서는 PowerShell을 사용하여 템플릿의 인코딩을 보존해야 합니다.

powershell "cdk bootstrap --show-template | Out-File -encoding utf8 bootstrap-template.yaml"

CDK CLI를 사용하여 이 템플릿을 배포하려면 다음을 실행합니다.

$ cdk bootstrap --template bootstrap-template.yaml

다음은 AWS CLI를 사용하여 템플릿을 배포하는 예입니다.

macOS/Linux

aws cloudformation create-stack \
  --stack-name CDKToolkit \
  --template-body file://path/to/bootstrap-template.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --region us-west-1

Windows

aws cloudformation create-stack ^
  --stack-name CDKToolkit ^
  --template-body file://path/to/bootstrap-template.yaml ^
  --capabilities CAPABILITY_NAMED_IAM ^
  --region us-west-1

CloudFormation StackSets를 사용하여 여러 환경을 부트스트래핑하는 방법에 대한 자세한 내용은 AWS Cloud Operations & Migrations Blog의 Bootstrapping multiple AWS 계정 for AWS CDK using CloudFormation StackSets를 참조하세요.

환경을 부트스트래핑해야 하는 경우

AWS 환경에 배포하기 전에 각 환경을 부트스트래핑해야 합니다. 사용하려는 각 환경을 사전에 부트스트래핑하는 것이 좋습니다. CDK 앱을 환경에 실제로 배포하기 전에 이 작업을 수행할 수 있습니다. 환경을 사전에 부트스트래핑하면 Amazon S3 버킷 이름 충돌 또는 부트스트래핑되지 않은 환경에 CDK 앱 배포와 같은 잠재적인 향후 문제를 방지할 수 있습니다.

환경을 두 번 이상 부트스트래핑해도 괜찮습니다. 환경이 이미 부트스트래핑된 경우 필요에 따라 부트스트랩 스택이 업그레이드됩니다. 그렇지 않으면 아무 일도 일어나지 않습니다.

부트스트래핑되지 않은 환경에 CDK 스택을 배포하려고 하면 다음과 같은 오류가 표시됩니다.

$ cdk deploy

✨  Synthesis time: 2.02s

 ❌ Deployment failed: Error: BootstrapExampleStack: 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)

부트스트랩 스택 업데이트

정기적으로 CDK 팀은 부트스트랩 템플릿을 새 버전으로 업데이트합니다. 이 경우 부트스트랩 스택을 업데이트하는 것이 좋습니다. 부트스트랩 프로세스를 사용자 지정하지 않은 경우 원래 환경을 부트스트랩할 때와 동일한 단계를 수행하여 부트스트랩 스택을 업데이트할 수 있습니다. 자세한 내용은 부트스트랩 템플릿 버전 기록 단원을 참조하십시오.

부트스트래핑 중 생성된 기본 리소스

부트스트래핑 중 생성된 IAM 역할

기본적으로 부트스트래핑은 환경에서 다음 AWS Identity and Access Management(IAM) 역할을 프로비저닝합니다.

부트스트래핑 중 생성된 리소스 ID

기본 부트스트랩 템플릿을 배포하면 부트스트랩 리소스의 물리적 ID가 cdk-qualifier-description-account-ID-Region 구문을 사용하여 생성됩니다.

cdk-hnb659fds-assets-012345678910-us-west-1은 부트스트래핑 중 생성된 Amazon S3 스테이징 버킷의 물리적 ID 예입니다.

환경을 부팅할 때 사용할 권한

AWS 환경을 부트스트래핑할 때 부트스트래핑을 수행하는 IAM ID에는 최소한 다음 권한이 있어야 합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:*",
                "ecr:*",
                "ssm:*",
                "s3:*",
                "iam:*"
            ],
            "Resource": "*"
        }
    ]
}

시간이 지남에 따라 생성된 리소스와 필요한 권한을 포함한 부트스트랩 스택이 변경될 수 있습니다. 향후 변경 시 환경을 부트스트래핑하는 데 필요한 권한을 수정해야 할 수 있습니다.

부트스트래핑 사용자 지정

기본 부트스트랩 템플릿이 요구 사항에 맞지 않는 경우 다음과 같은 방법으로 환경에 리소스의 부트스트래핑을 사용자 지정할 수 있습니다.

부트스트래핑 사용자 지정에 대한 자세한 내용은 AWS CDK 부트스트래핑 사용자 지정 섹션을 참조하세요.

CDK Pipelines로 부트스트래핑

CDK Pipelines를 사용하여 다른 계정의 환경에 배포하는 경우 다음과 같은 메시지가 표시됩니다.

Policy contains a statement with one or more invalid principals

이 오류 메시지는 다른 환경에 적절한 IAM 역할이 존재하지 않음을 의미합니다. 가능성이 가장 높은 원인은 환경이 부트스트래핑되지 않았기 때문입니다. 환경을 부트스트래핑하고 다시 시도하세요.

부트스트랩 스택이 삭제되지 않도록 보호

부트스트랩 스택이 삭제되면 CDK 배포를 지원하기 위해 환경에서 원래 프로비저닝된 AWS 리소스도 삭제됩니다. 이렇게 하면 파이프라인이 작동하지 않습니다. 이 경우 일반적인 복구 솔루션은 없습니다.

환경이 부트스트래핑된 후에는 환경의 부트스트랩 스택을 삭제하고 다시 생성하지 마세요. 대신 cdk bootstrap 명령을 다시 실행하여 부트스트랩 스택을 새 버전으로 업데이트해 보세요.

부트스트랩 스택이 실수로 삭제되는 것을 방지하려면 cdk bootstrap 명령과 함께 --termination-protection 옵션을 제공하여 종료 방지를 활성화하는 것이 좋습니다. 신규 또는 기존 부트스트랩 스택에서 종료 방지를 활성화할 수 있습니다. 종료 방지 활성화에 대한 지침은 부트스트랩 스택에 대한 종료 방지 활성화를 참조하세요.

부트스트랩 템플릿 버전 기록

부트스트랩 템플릿은 버전이 관리되고 AWS CDK 자체와 함께 시간이 지남에 따라 발전합니다. 자체 부트스트랩 템플릿을 제공하는 경우 정규 기본 템플릿을 사용하여 최신 상태로 유지하세요. 모든 CDK 기능에서 템플릿이 계속 작동하는지 확인해야 할 수 있습니다.

이 섹션에는 각 버전의 변경 사항 목록이 포함되어 있습니다.

레거시에서 최신 부트스트랩 템플릿으로 업그레이드

AWS CDK v1은 레거시와 최신의 두 부트스트래핑 템플릿을 지원했습니다. CDK v2는 최신 템플릿만 지원합니다. 참고로 이 두 템플릿 간의 주요 차이점은 다음과 같습니다.

* 필요에 따라 부트스트랩 템플릿에 리소스를 추가할 예정입니다.

레거시 템플릿을 사용하여 부트스트래핑된 환경은 재부트스트래핑을 통해 CDK v2에 대한 최신 템플릿을 사용하도록 업그레이드해야 합니다. 레거시 버킷을 삭제하기 전에 환경의 모든 AWS CDK 애플리케이션을 한 번 이상 다시 배포합니다.

Security Hub 조사 결과 확인

AWS Security Hub를 사용하는 경우 AWS CDK 부트스트래핑 프로세스에서 생성된 일부 리소스에 대해 보고된 조사 결과가 표시될 수 있습니다. Security Hub 조사 결과는 정확성과 안전성을 다시 확인해야 하는 리소스 구성을 찾는 데 도움이 됩니다. AWS Security와 함께 이러한 특정 리소스 구성을 검토했으며 보안 문제를 일으키지 않는다고 확신합니다.

[KMS.2] IAM 보안 주체에는 모든 KMS 키에 대한 암호 해독 작업을 허용하는 IAM 인라인 정책이 없어야 합니다.

배포 역할(DeploymentActionRole)은 암호화된 데이터를 읽을 수 있는 권한을 부여합니다. 이는 CDK Pipelines를 사용한 교차 계정 배포에 필요합니다. 이 역할의 정책은 모든 데이터에 대한 권한을 부여하지 않습니다. 해당 리소스가 버킷 또는 키 정책을 통해 허용하는 경우에만 Amazon S3와 AWS KMS에서 암호화된 데이터를 읽을 수 있는 권한을 부여합니다.

다음은 부트스트랩 템플릿의 배포 역할에서 이러한 두 문의 스니펫입니다.

DeploymentActionRole:
    Type: AWS::IAM::Role
    Properties:
      ...
      Policies:
        - PolicyDocument:
            Statement:
              ...
              - Sid: PipelineCrossAccountArtifactsBucket
                Effect: Allow
                Action:
                  - s3:GetObject*
                  - s3:GetBucket*
                  - s3:List*
                  - s3:Abort*
                  - s3:DeleteObject*
                  - s3:PutObject*
                Resource: "*"
                Condition:
                  StringNotEquals:
                    s3:ResourceAccount:
                      Ref: AWS::AccountId
              - Sid: PipelineCrossAccountArtifactsKey
                Effect: Allow
                Action:
                  - kms:Decrypt
                  - kms:DescribeKey
                  - kms:Encrypt
                  - kms:ReEncrypt*
                  - kms:GenerateDataKey*
                Resource: "*"
                Condition:
                  StringEquals:
                    kms:ViaService:
                      Fn::Sub: s3.${AWS::Region}.amazonaws.com
              ...

Security Hub에서 이에 플래그를 지정하는 이유는 무엇인가요?

정책에는 Resource: *와 Condition 절이 결합되어 있습니다. Security Hub는 * 와일드카드에 플래그를 지정합니다. 이 와일드카드는 계정이 부트스트래핑될 때 CodePipeline 아티팩트 버킷에 대해 CDK Pipelines에서 생성한 AWS KMS 키가 아직 존재하지 않으므로 ARN이 부트스트랩 템플릿에서 참조할 수 없기 때문에 사용됩니다. 또한 Security Hub는 이 플래그를 지정할 때 Condition 절을 고려하지 않습니다. 이 Condition은 Resource: *를 AWS KMS 키의 동일한 AWS 계정에서 이루어진 요청으로 제한합니다. 이러한 요청은 AWS KMS와 동일한 AWS 리전에 있는 Amazon S3에서 와야 합니다.

이 조사 결과를 수정해야 하나요?

부트스트랩 템플릿의 AWS KMS 키를 지나치게 허용적으로 수정하지 않은 한 배포 역할은 필요 이상의 액세스를 허용하지 않습니다. 따라서 이 조사 결과를 수정할 필요는 없습니다.

이 조사 결과를 수정하려면 어떻게 해야 하나요?

이 조사 결과를 수정하는 방법은 교차 계정 배포에 CDK Pipelines를 사용할지 여부에 따라 달라집니다.

고려 사항

부트스트래핑은 환경에서 리소스를 프로비저닝하므로 해당 리소스를 AWS CDK와 함께 사용할 때 AWS 요금이 발생할 수 있습니다.