Cơ sở hạ tầng CDK

AWS CDK là một framework để định nghĩa cơ sở hạ tầng đám mây bằng code và triển khai nó thông qua AWS CloudFormation.

Trình tạo cơ sở hạ tầng TypeScript tạo ra một ứng dụng cơ sở hạ tầng AWS CDK được viết bằng TypeScript. Ứng dụng được tạo ra bao gồm các phương pháp bảo mật tốt nhất thông qua kiểm tra bảo mật Checkov.

Cách sử dụng

Tạo một dự án cơ sở hạ tầng

Bạn có thể tạo một dự án cơ sở hạ tầng mới theo hai cách:

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#infra
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

You can also perform a dry-run to see what files would be changed

pnpm

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

yarn

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

npm

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

bun

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

Tùy chọn

Parameter	Type	Default	Description
name Required	string	-	The name of the application.
directory	string	packages	The directory of the new application.

Kết quả đầu ra của trình tạo

Trình tạo sẽ tạo cấu trúc dự án sau trong thư mục <directory>/<name>:

• Thư mụcsrc

  • main.ts Điểm khởi đầu ứng dụng khởi tạo các CDK stage để triển khai
  • Thư mụcstages Định nghĩa CDK Stage

    • application-stage.ts Định nghĩa một tập hợp các stack để triển khai trong một stage
  • Thư mụcstacks Định nghĩa CDK Stack

    • application-stack.ts Stack ứng dụng chính
• cdk.json Cấu hình CDK
• project.json Cấu hình dự án và các target build
• checkov.yml Tệp cấu hình Checkov

Mẹo

Cơ sở hạ tầng của bạn là một dự án TypeScript, vì vậy bạn có thể tham khảo tài liệu dự án TypeScript để biết thêm chi tiết về cách sử dụng chung của chúng.

Triển khai cơ sở hạ tầng CDK của bạn

Bạn có thể bắt đầu viết cơ sở hạ tầng CDK của mình bên trong src/stacks/application-stack.ts, ví dụ:

src/stacks/application-stack.ts

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

    // Khai báo cơ sở hạ tầng của bạn ở đây
    new Bucket(this, 'MyBucket');
  }
}

Stage và Stack

Bạn sẽ nhận thấy rằng tệp src/main.ts cấp cao nhất khởi tạo một CDK Stage có tên là <namespace>-sandbox. Stage này được dành cho việc phát triển và thử nghiệm của riêng bạn.

src/main.ts

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

Bạn có thể thêm nhiều stage hơn, ví dụ bạn có thể muốn định nghĩa các stage beta và prod để triển khai đến các môi trường riêng biệt:

src/main.ts

new ApplicationStage(app, 'project-beta', {
  env: {
    account: '123456789012', // tài khoản beta
    region: 'us-west-2',
  },
});
new ApplicationStage(app, 'project-prod', {
  env: {
    account: '098765432109', // tài khoản prod
    region: 'us-west-2',
  },
});

Một Stage định nghĩa một tập hợp các stack nên được triển khai cùng nhau để tạo thành ứng dụng của bạn. Bạn có thể khởi tạo bao nhiêu stack tùy thích trong một stage, ví dụ:

src/stages/application-stage.ts

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

/**
 * Định nghĩa một tập hợp các CDK Stack tạo thành ứng dụng của bạn
 */
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,
    });
  }
}

Cơ sở hạ tầng API

Nếu bạn đã sử dụng trình tạo tRPC API hoặc FastAPI để tạo API, bạn sẽ nhận thấy bạn đã có một số construct có sẵn trong packages/common/constructs để triển khai chúng.

Ví dụ, nếu bạn đã tạo một tRPC API có tên là my-api, bạn chỉ cần import và khởi tạo construct để thêm tất cả cơ sở hạ tầng cần thiết để triển khai nó:

src/stacks/application-stack.ts

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

    // Thêm cơ sở hạ tầng cho API của bạn
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Cơ sở hạ tầng Website

Nếu bạn đã sử dụng trình tạo CloudScape website, bạn sẽ nhận thấy bạn đã có một construct trong packages/common/constructs để triển khai nó. Ví dụ:

src/stacks/application-stack.ts

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

    // Thêm cơ sở hạ tầng cho website của bạn
    new MyWebsite(this, 'MyWebsite');
  }
}

Điều quan trọng là đảm bảo rằng website được khai báo sau bất kỳ construct API nào để Runtime Config của website bao gồm tất cả cấu hình API.

Tổng hợp cơ sở hạ tầng của bạn

Như một phần của target build, cũng như chạy các target compile, lint và test mặc định, dự án cơ sở hạ tầng của bạn được tổng hợp thành CloudFormation. Điều này cũng có thể được thực thi một cách độc lập, bằng cách chạy target synth:

pnpm

pnpm nx run <my-infra>:synth

yarn

yarn nx run <my-infra>:synth

npm

npx nx run <my-infra>:synth

bun

bunx nx run <my-infra>:synth

Bạn sẽ tìm thấy cloud assembly đã tổng hợp của mình trong thư mục dist gốc, dưới dist/packages/<my-infra-project>/cdk.out.

Kiểm tra bảo mật

Một target checkov được thêm vào dự án của bạn để chạy kiểm tra bảo mật trên cơ sở hạ tầng của bạn bằng Checkov.

pnpm

pnpm nx run <my-infra>:checkov

yarn

yarn nx run <my-infra>:checkov

npm

npx nx run <my-infra>:checkov

bun

bunx nx run <my-infra>:checkov

Bạn sẽ tìm thấy kết quả kiểm tra bảo mật của mình trong thư mục dist gốc, dưới dist/packages/<my-infra-project>/checkov.

Ghi chú

Checkov được chạy bằng uvx, vì vậy bạn sẽ cần cài đặt uv nếu bạn chưa có.

Chú ý

Một số quy tắc Checkov được loại trừ theo mặc định thông qua tệp checkov.yml. Bạn nên xem xét lại những quy tắc này dựa trên trường hợp sử dụng của bạn.

Loại trừ kiểm tra Checkov

Có thể có những trường hợp bạn muốn loại trừ một số quy tắc nhất định trên các tài nguyên. Bạn có thể làm điều này theo hai cách:

Loại trừ một quy tắc trên một construct nhất định

import { suppressRules } from ':my-scope/common-constructs';

// loại trừ CKV_AWS_XXX cho construct đã cho.
suppressRules(construct, ['CKV_AWS_XXX'], 'Reason');

Loại trừ một quy tắc trên một construct con cháu

import { suppressRules } from ':my-scope/common-constructs';

// Loại trừ CKV_AWS_XXX cho construct hoặc bất kỳ construct con cháu nào của nó nếu nó là một instance của Bucket
suppressRules(construct, ['CKV_AWS_XXX'], 'Reason', (construct) => construct instanceof Bucket);

Bootstrap tài khoản AWS của bạn

Nếu bạn đang triển khai một ứng dụng CDK đến một tài khoản AWS lần đầu tiên, nó sẽ cần được bootstrap trước.

Đầu tiên, đảm bảo rằng bạn đã cấu hình thông tin xác thực cho tài khoản AWS của mình.

Tiếp theo, bạn có thể sử dụng lệnh cdk bootstrap:

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

Để biết thêm chi tiết, vui lòng tham khảo tài liệu CDK.

Triển khai lên AWS

Sau khi build, bạn có thể triển khai cơ sở hạ tầng của mình lên AWS bằng target deploy.

Chú ý

Sử dụng target deploy-ci nếu triển khai trong một pipeline CI/CD. Xem bên dưới để biết thêm chi tiết.

Đầu tiên, đảm bảo rằng bạn đã cấu hình thông tin xác thực cho tài khoản AWS của mình.

Tiếp theo, chạy target deploy:

pnpm

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

yarn

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

npm

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

bun

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

Mẹo

Lệnh trên triển khai tất cả các stack cho stage <my-infra>-sandbox. Bạn có thể chỉ định các stage khác miễn là chúng được định nghĩa trong main.ts.

Bạn cũng có thể triển khai các stack riêng lẻ bằng cách chỉ định tên stack đầy đủ, ví dụ:

pnpm

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

yarn

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

npm

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

bun

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

Triển khai lên AWS trong một pipeline CI/CD

Sử dụng target deploy-ci nếu bạn đang triển khai lên AWS như một phần của pipeline CI/CD.

pnpm

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

yarn

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

npm

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

bun

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

Target này khác một chút so với target deploy thông thường ở chỗ nó đảm bảo cloud-assembly đã được tổng hợp trước được triển khai, thay vì tổng hợp ngay lập tức. Điều này giúp tránh các vấn đề tiềm ẩn với tính không xác định do thay đổi phiên bản package, đảm bảo rằng mọi giai đoạn pipeline triển khai sử dụng cùng một cloud-assembly.

Xóa bỏ cơ sở hạ tầng AWS

Sử dụng target destroy để xóa bỏ tài nguyên của bạn:

pnpm

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

yarn

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

npm

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

bun

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

Thông tin thêm

Để biết thêm thông tin về CDK, vui lòng tham khảo CDK Developer Guide và API Reference.