CDK 인프라

AWS CDK는 코드로 클라우드 인프라를 정의하고 AWS CloudFormation을 통해 프로비저닝하는 프레임워크입니다.

TypeScript 인프라 생성기는 TypeScript로 작성된 AWS CDK 인프라 애플리케이션을 생성합니다. 생성된 애플리케이션은 CFN Guard 검사를 통해 보안 모범 사례를 포함합니다.

사용 방법

인프라 프로젝트 생성

새 인프라 프로젝트를 두 가지 방법으로 생성할 수 있습니다:

VSCode
CLI

설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
VSCode에서 Nx 콘솔 열기
클릭 Generate (UI) "Common Nx Commands" 섹션에서
검색 @aws/nx-plugin - ts#infra
필수 매개변수 입력
클릭 Generate

pnpm nx g @aws/nx-plugin:ts#infra

yarn nx g @aws/nx-plugin:ts#infra

npx nx g @aws/nx-plugin:ts#infra

bunx nx g @aws/nx-plugin:ts#infra

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm nx g @aws/nx-plugin:ts#infra --dry-run

yarn nx g @aws/nx-plugin:ts#infra --dry-run

npx nx g @aws/nx-plugin:ts#infra --dry-run

bunx nx g @aws/nx-plugin:ts#infra --dry-run

옵션

매개변수	타입	기본값	설명
name 필수	string	-	The name of the application.
ruleSet	string	aws_prototyping	Rule set to validate your AWS resources with.
directory	string	packages	The directory of the new application.

생성기 출력

생성기는 <directory>/<name> 디렉토리에 다음 프로젝트 구조를 생성합니다:

디렉터리src
- main.ts 배포할 CDK 스테이지를 인스턴스화하는 애플리케이션 진입점
- 디렉터리stages CDK 스테이지 정의
  - application-stage.ts 스테이지에서 배포할 스택 컬렉션 정의
- 디렉터리stacks CDK 스택 정의
  - application-stack.ts 메인 애플리케이션 스택
cdk.json CDK 구성
project.json 프로젝트 구성 및 빌드 타겟

CDK 인프라 구현

src/stacks/application-stack.ts 내에서 CDK 인프라 작성을 시작할 수 있습니다. 예시:

import { Stack, StackProps } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3'
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // 인프라를 여기에 선언
    new Bucket(this, 'MyBucket');
  }
}

스테이지와 스택

최상위 src/main.ts 파일이 <namespace>-sandbox라는 이름의 CDK 스테이지를 인스턴스화하는 것을 확인할 수 있습니다. 이 스테이지는 개발 및 테스트용으로 사용됩니다.

new ApplicationStage(app, 'project-sandbox', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION,
  },
});

beta 및 prod 스테이지를 추가하여 별도 환경에 배포할 수 있습니다:

new ApplicationStage(app, 'project-beta', {
  env: {
    account: '123456789012', // 베타 계정
    region: 'us-west-2',
  },
});
new ApplicationStage(app, 'project-prod', {
  env: {
    account: '098765432109', // 프로덕션 계정
    region: 'us-west-2',
  },
});

스테이지는 함께 배포되어야 할 스택 컬렉션을 정의합니다. 스테이지 내에서 원하는 만큼 스택을 인스턴스화할 수 있습니다:

import { Stage, StageProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { BackendStack } from '../stacks/backend-stack.js';
import { FrontendStack } from '../stacks/frontend-stack.js';

/**
 * 애플리케이션을 구성하는 CDK 스택 컬렉션 정의
 */
export class ApplicationStage extends Stage {
  constructor(scope: Construct, id: string, props?: StageProps) {
    super(scope, id, props);

    new BackendStack(this, 'Backend', {
      crossRegionReferences: true,
    })

    new FrontendStack(this, 'Frontend', {
      crossRegionReferences: true,
    });
  }
}

API 인프라

tRPC API 또는 FastAPI 생성기를 사용하여 API를 생성한 경우 packages/common/constructs에 배포를 위한 구문이 이미 존재합니다.

예를 들어 my-api라는 tRPC API를 생성한 경우, 구문을 가져와 인스턴스화하면 배포에 필요한 모든 인프라가 추가됩니다:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // API 인프라 추가
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

웹사이트 인프라

CloudScape 웹사이트 생성기를 사용한 경우 packages/common/constructs에 배포 구문이 이미 존재합니다. 예시:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 웹사이트 인프라 추가
    new MyWebsite(this, 'MyWebsite');
  }
}

웹사이트 런타임 구성에 모든 API 설정이 포함되도록 하려면 API 구문을 선언한 후에 웹사이트를 선언해야 합니다.

인프라 합성

build 타겟의 일부로 기본 컴파일, 린트 및 테스트 타겟을 실행하는 동시에 인프라 프로젝트를 CloudFormation으로 _합성_합니다. synth 타겟을 실행하여 독립적으로 수행할 수도 있습니다:

pnpm nx run <my-infra>:synth

yarn nx run <my-infra>:synth

npx nx run <my-infra>:synth

bunx nx run <my-infra>:synth

루트 dist 폴더의 dist/packages/<my-infra-project>/cdk.out에서 합성된 클라우드 어셈블리를 확인할 수 있습니다.

AWS 계정 부트스트랩

CDK 애플리케이션을 AWS 계정에 처음 배포할 때는 부트스트랩이 필요합니다.

먼저 AWS 계정 자격 증명을 구성했는지 확인하세요.

다음으로 cdk bootstrap 명령을 사용합니다:

npx cdk bootstrap aws://<account-id>/<region>

자세한 내용은 CDK 문서를 참조하세요.

AWS에 배포

빌드 후 deploy 타겟을 사용하여 인프라를 AWS에 배포할 수 있습니다.

먼저 AWS 계정 자격 증명을 구성했는지 확인하세요.

다음으로 배포 타겟을 실행합니다:

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/*

yarn nx run <my-infra>:deploy <my-infra>-sandbox/*

npx nx run <my-infra>:deploy <my-infra>-sandbox/*

bunx nx run <my-infra>:deploy <my-infra>-sandbox/*

위 명령은 <my-infra>-sandbox 스테이지의 모든 스택을 배포합니다. main.ts에 정의된 다른 스테이지를 지정할 수 있습니다.

전체 스택 이름을 지정하여 개별 스택을 배포할 수도 있습니다:

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/Application

yarn nx run <my-infra>:deploy <my-infra>-sandbox/Application

npx nx run <my-infra>:deploy <my-infra>-sandbox/Application

bunx nx run <my-infra>:deploy <my-infra>-sandbox/Application

CI/CD 파이프라인에서 AWS 배포

CI/CD 파이프라인의 일부로 AWS에 배포할 경우 deploy-ci 타겟을 사용합니다.

pnpm nx run <my-infra>:deploy-ci my-stage/*

yarn nx run <my-infra>:deploy-ci my-stage/*

npx nx run <my-infra>:deploy-ci my-stage/*

bunx nx run <my-infra>:deploy-ci my-stage/*

이 타겟은 일반 deploy 타겟과 달리 사전 합성된 클라우드 어셈블리를 배포하여 패키지 버전 변경으로 인한 비결정성 문제를 방지합니다. 이를 통해 모든 파이프라인 단계에서 동일한 클라우드 어셈블리를 사용하여 배포합니다.

AWS 인프라 삭제

destroy 타겟을 사용하여 리소스를 정리합니다:

pnpm nx run <my-infra>:destroy <my-infra>-sandbox/*

yarn nx run <my-infra>:destroy <my-infra>-sandbox/*

npx nx run <my-infra>:destroy <my-infra>-sandbox/*

bunx nx run <my-infra>:destroy <my-infra>-sandbox/*

추가 정보

CDK에 대한 자세한 내용은 CDK 개발자 가이드 및 API 참조를 참조하세요.