aws-cdk

AWS CDK — это практическая инструкция по авторингу, развёртыванию и диагностике инфраструктуры AWS через Cloud Development Kit на TypeScript или Python. Она охватывает construct-архитектуру, работу со стеками, CloudFormation, drift, импорт существующих ресурсов, compliance и безопасный рефакторинг. Область применения ограничена CDK: для сырого CloudFormation YAML или JSON, SAM, Terraform, Pulumi и задач CI/CD вне CDK Pipelines источник предлагает другой инструмент или встроенные знания. Базовый рабочий цикл должен разделять генерацию шаблона и изменение AWS. Для нового окружения используется cdk bootstrap с account и region. Перед production deploy рекомендуется пройти cdk synth --strict, затем cdk diff и только после проверки различий — cdk deploy. cdk synth показывает результат сборки, cdk diff помогает увидеть изменения CloudFormation до их применения, а deploy выполняет реальное изменение. Для проверки конструкций предпочтительны L2-конструкции; L1 следует использовать, когда L2 не предоставляет нужное свойство, дополняя их Mixins или Facades и только затем обращаясь к escape hatch через node.defaultChild и addPropertyOverride. Для compliance источник указывает cdk-nag и добавление AwsSolutionsChecks через Aspects. Для drift используется cdk drift, а в CI — флаг --fail, если обнаруженное расхождение должно останавливать проверку. Импорт существующего ресурса выполняется через cdk import; для автоматизированного сценария возможен resource mapping и последующий deploy с --import-existing-resources. При рефакторинге нужно сохранять неизменными логические идентификаторы CloudFormation: изменение construct ID или его расположения может привести к замене ресурса и потере состояния. Безопасная последовательность — сначала cdk diff, а для специально поддерживаемого сценария cdk refactor --unstable=refactor без изменения свойств в том же deploy. Особенно опасен deadlock cross-stack reference. Если удалить ссылку между стеками сразу, экспорт может остаться используемым зависимым стеком и deploy не завершится. Рекомендованный путь — сначала ослабить reference через CrossStackReferences.of($RESOURCE).produce(ReferenceStrength.BOTH), затем WEAK, затем убрать ссылку; как legacy-вариант источник описывает двухпроходный exportValue. Для stateful ресурсов это не косметический рефакторинг: перед изменением логических идентификаторов всегда нужен diff и отдельная оценка риска замены. При UPDATE_ROLLBACK_FAILED источник предлагает cdk rollback $STACK или cdk rollback $STACK --orphan <LogicalId>, если конкретный ресурс нужно сохранить отдельно. Незаполненный S3 bucket не исчезнет при destroy сам по себе: для автоматического удаления должны быть одновременно removalPolicy: DESTROY и autoDeleteObjects: true. Версионирование усиливает риск, потому что delete markers могут остаться после кажущегося удаления. Эти настройки особенно важны для тестовых окружений, а для рабочих данных безопаснее явно выбирать retention и защищать stateful stack. Диагностика должна начинаться с первопричины, а не с общего сообщения DeployFailed или DeploymentError. Для подробного события предлагаются cdk deploy --verbose и, начиная с указанной в источнике версии CLI, cdk --unstable=diagnose diagnose $STACK; альтернативой является aws cloudformation describe-events с фильтром FailedEvents=true, где нужно искать первое событие с суффиксом _FAILED. Ошибки credentials проверяются через aws sts get-caller-identity и cdk doctor. Asset errors требуют проверить путь, Docker и bootstrap bucket; рекомендуемый способ строить путь — path.join(__dirname, ...). AppRequired означает, что в cdk.json не задан app, а BootstrapVersionValidation указывает на необходимость повторного bootstrap с тем же qualifier. Остальные типовые причины также имеют узкие проверки. ConcurrentReadLock или ConcurrentWriteLock лечатся удалением устаревшего cdk.out и повторным запуском, а параллельным CI нужен отдельный output каталог. UnresolvedAccount требует явного account и region в env; cdk list помогает, когда не найден logical stack ID. Ошибка module not found во время synth проверяется через tsc --noEmit, соответствие app в cdk.json и tsconfig и отсутствие старых JavaScript-файлов. DependencyCycle требует вынести общий ресурс в третий стек или использовать SSM для позднего связывания. Ошибки Lambda могут означать неверный handler, устаревшие импорты SDK или неупакованные Python-зависимости. Безопасность в инструкции не сводится к успешному synth. Для CI рекомендуются OIDC вместо статических ключей, custom permissions boundary на bootstrap, grant* для IAM-связей, cdk-nag с --strict, отдельный стек для stateful ресурсов и terminationProtection: true. cdk.context.json следует сохранять, чтобы контекст CDK был воспроизводим. Эти рекомендации не дают права выполнять deploy без проверки учётных данных, региона, diff, drift и последствий для данных. Итоговый сценарий использования прост: описать ресурсы через CDK, проверить типы и synth, изучить diff, отдельно оценить замены и межстековые зависимости, затем выполнить deploy с наблюдением CloudFormation. Если задача относится к другому формату инфраструктуры или к общей CI/CD-системе, эта инструкция не является подходящим источником решения.