Tại sao CDK yêu cầu toolkit stack?
Bạn chạy lệnh cdk deploy và thay vì thấy thanh tiến trình, bạn lại nhận được một thông báo lỗi dài. Lỗi trông như thế này:
Error: This stack uses assets, so the toolkit stack must be deployed to the environment (Run "cdk bootstrap aws://123456789012/us-east-1")
Điều này xảy ra vì mã nguồn CDK của bạn bao gồm các "asset" (tài sản). Đây là các tệp cục bộ—chẳng hạn như một hàm Lambda Python 5MB hoặc một Docker image 200MB—mà CloudFormation không thể xử lý trực tiếp. CDK cần một vùng đệm (staging area) để lưu trữ các tệp này trước khi có thể triển khai hạ tầng của bạn.
"Toolkit stack" (tên là CDKToolkit) cung cấp vùng đệm này. Nó thiết lập một S3 bucket để lưu trữ tệp và các IAM role cho quyền triển khai. Nếu bạn chưa khởi tạo tài khoản AWS và region của mình, CDK sẽ không có nơi nào để đặt mã nguồn của bạn.
Cách khắc phục: Bootstrapping môi trường của bạn
1. Câu lệnh tiêu chuẩn
Cách khắc phục nhanh nhất là chạy chính xác câu lệnh được gợi ý trong terminal của bạn. Thay thế ID tài khoản và region bằng thông tin cụ thể của bạn:
cdk bootstrap aws://123456789012/us-east-1
Đợi khoảng 2–3 phút. CDK sẽ tạo một CloudFormation stack để thiết lập S3 bucket và các khóa mã hóa cần thiết.
2. Làm việc với AWS Profiles
Nếu bạn sử dụng flag --profile để triển khai, bạn cũng phải sử dụng nó khi thực hiện bootstrap. Nếu không, bạn có thể vô tình bootstrap nhầm tài khoản AWS.
cdk bootstrap --profile prod-account aws://123456789012/us-east-1
3. Triển khai trên nhiều region
Bootstrapping có tính chất riêng biệt cho từng region. Nếu ứng dụng của bạn trải dài trên us-east-1 (N. Virginia) và us-west-2 (Oregon), bạn cần chạy câu lệnh cho cả hai. CDK sẽ tạo một stack CDKToolkit riêng biệt trong mỗi region để đảm bảo các asset được lưu trữ cục bộ giúp triển khai nhanh hơn.
4. Giải quyết lỗi Permission Denied
Quá trình bootstrapping tạo ra các IAM role và S3 bucket, đây là những hành động yêu cầu đặc quyền cao. Nếu bạn thấy lỗi "Access Denied", người dùng IAM hiện tại của bạn có thể thiếu policy AdministratorAccess. Hãy yêu cầu quản trị viên cấp quyền tạm thời hoặc nhờ họ chạy lệnh bootstrap cho bạn.
Cách xác minh kết quả
Đừng chỉ tin vào thông báo ở terminal. Bạn có thể kiểm tra hạ tầng mà CDK đã xây dựng tại các khu vực sau:
- CloudFormation: Tìm kiếm stack có tên
CDKToolkit. Nó phải hiển thị trạng tháiCREATE_COMPLETE. - S3 Console: Bạn sẽ tìm thấy một bucket mới có tên
cdk-hnb659fds-assets-[account]-[region]. Đây là nơi lưu trữ các tệp.zipcủa Lambda. - IAM: Một số role bắt đầu bằng
cdk-hnb659fds-sẽ được tạo để xử lý việc tải tệp lên và thực thi CloudFormation.
Thực hành tốt nhất (Best Practices)
Thiết lập một lần: Bạn chỉ cần bootstrap một tài khoản/region một lần duy nhất. Không cần đưa lệnh cdk bootstrap vào các kịch bản GitHub Actions hoặc Jenkins pipeline. Việc này chỉ làm tốn thêm thời gian không cần thiết cho quy trình CI/CD của bạn.
CDK v1 so với v2: Nếu bạn vừa nâng cấp từ CDK v1 lên v2, bạn có thể cần bootstrap lại. CDK v2 sử dụng template bootstrap "Hiện đại" (Modern) cung cấp bảo mật tốt hơn và hỗ trợ triển khai đa tài khoản tốt hơn so với phiên bản cũ.
Chi phí: S3 bucket được tạo hầu như miễn phí nếu nó trống. Bạn chỉ trả tiền cho dung lượng lưu trữ của các asset mà bạn tải lên. Nếu bạn thấy hóa đơn AWS tăng lên, hãy kiểm tra bucket và loại bỏ các phiên bản cũ của các hàm Lambda hoặc Docker image.