Объявление об устаревании
Инструмент Cloud Development Kit for Terraform признан устаревшим с 10 декабря 2025 года. HashiCorp больше не поддерживает и не обслуживает Cloud Development Kit for Terraform.
Ресурсы — это важнейший элемент при определении инфраструктуры в приложениях CDKTF. Каждый ресурс описывает один или несколько инфраструктурных объектов, таких как виртуальные сети, инстансы вычислений или компоненты более высокого уровня, например записи DNS.
В своем приложении CDK for Terraform (CDKTF) вы будете использовать предпочитаемый язык программирования для определения ресурсов, которые Terraform должен управлять у одного или нескольких провайдеров. На этой странице объясняется, как использовать ресурсы в вашем приложении и как применять обходные пути (escape hatches) для изменения поведения ресурсов при необходимости.
Определения и свойства ресурсов различаются в зависимости от типа ресурса и провайдера. Полный список доступных ресурсов и параметров их конфигурации см. в документации вашего провайдера.
В следующем примере определяется ресурс таблицы DynamoDB для провайдера AWS.
На странице примеров содержится множество примеров проектов для каждого поддерживаемого языка программирования.
Вы можете создавать экземпляры одного и того же ресурса несколько раз в своей инфраструктуре. Например, вы можете создать несколько бакетов S3 с различными конфигурациями. Экземпляры, разделяющие один и тот же родительский элемент, считаются частью одной области видимости (scope). Вы должны задать уникальное свойство name для каждого экземпляра, чтобы избежать конфликтов имен.
Дополнительные сведения и пример см. в документации по конструктам.
Вы можете ссылаться на свойства ресурсов по всей своей конфигурации. Например, вы можете использовать имя родительского ресурса при назначении имен связанным дочерним ресурсам. Полный список доступных свойств для каждого типа ресурса см. в документации вашего провайдера.
Чтобы создавать ссылки, вызовите myResource.<propertyName> на экземпляре ресурса. Например, вы можете использовать myResource.name для получения свойства name из myResource. Terraform не поддерживает передачу целого блока (например, exampleNamespace.metadata) в ресурс или источник данных, поэтому вы должны создать ссылку для каждого отдельного свойства.
Ссылки также полезны, когда необходимо отслеживать логические зависимости. Например, ресурсы Kubernetes находятся в пространстве имен (namespace), поэтому пространство имен должно существовать до того, как Terraform сможет подготовить связанные ресурсы. В следующем примере используется ссылка на свойство пространства имен в развертывании. Эта ссылка сообщает Terraform, что ему необходимо создать пространство имен перед созданием ресурсов.
При работе с определениями инфраструктуры, когда возникает необходимость выполнить рефакторинг или переименовать ресурсы без их удаления и повторного создания, вы можете использовать функцию moveTo следующим образом:
Дополнительную информацию см. в нашем руководстве по рефакторингу.
Провизионеры (provisioners) могут использоваться для моделирования определенных действий на локальной или удаленной машине с целью подготовки серверов или других инфраструктурных объектов к работе. Дополнительную концептуальную информацию о провизионерах можно найти в документации Terraform. Вы можете передать ключ provisioners для определения списка провизионеров, а соединения можно настроить с помощью ключа connection. Рабочий пример можно найти по адресу examples/typescript/provisioner.
Если вам нужно использовать специальный объект self, который может применяться только в блоках провизионеров и соединений для ссылки на родительский ресурс, вы можете использовать класс TerraformSelf следующим образом: TerraformSelf.getString("public_ip").
Если вам нужно убедиться, что условие выполнено до или после создания ресурса, вы можете указать условия. Чтобы добавить условие, настройте ключ lifecycle в вашем ресурсе с помощью объекта, содержащего precondition и / или postcondition. Эти ключи принимают список условий с ключом condition, содержащим вычисляемое выражение Terraform, и ключом errorMessage, содержащим строку, которая отображается, если условие не выполнено.
Если у вас есть существующие ресурсы, которыми вы хотите управлять с помощью CDKTF, вы можете импортировать их в свое приложение CDKTF. Лучший способ сделать это — использовать функцию блока import в Terraform версии >= 1.5. В CDKTF это можно сделать как с заданной конфигурацией, так и без нее.
Как выполнить импорт
Чтобы импортировать ресурс, сначала создайте экземпляр типа ресурса, который вы хотите импортировать — в нашем случае мы будем использовать S3Bucket. Конфигурация явно не требуется. Затем вызовите метод importFrom на объекте ресурса. Этот метод принимает идентификатор импортируемого ресурса в качестве первого аргумента и провайдер в качестве необязательного второго. Провайдер требуется только в том случае, если в вашей конфигурации имеется несколько провайдеров одного типа.
При запуске plan / apply вы получите информацию о том, что ваш ресурс будет импортирован. После выполнения apply вы можете удалить вызов importFrom, и ресурс перейдет под управление CDKTF.
Обратите внимание, что Terraform обновит существующие поля в импортированном ресурсе в соответствии с вашей конфигурацией при передаче его под управление. В нашем случае мы не определяли никаких конкретных свойств для S3Bucket, что заставляет Terraform, например, удалить теги, в настоящее время определенные для ресурса (как видно из плана ниже). Если вы хотите сохранить существующие настройки, вы можете сначала запустить план, добавить в конфигурацию ресурса все, что изменил бы Terraform, и только после этого применить изменения.
Ваш вывод может выглядеть следующим образом:
Генерация конфигурации для импорта
Если вы не хотите самостоятельно указывать конфигурацию импортируемого ресурса, вы можете использовать статический метод generateConfigForImport в классе ресурса, который хотите импортировать. Этот метод принимает область видимости (scope) в качестве первого аргумента, идентификатор конструката импортируемого ресурса (как он будет указан в возвращаемой сгенерированной конфигурации), идентификатор импортируемого ресурса и провайдер в качестве необязательного четвертого аргумента. Провайдер требуется только в том случае, если в вашей конфигурации имеется несколько провайдеров одного типа.
При выполнении cdktf plan <stack-name> Terraform сгенерирует код для импортируемого ресурса, а CDKTF преобразует его в используемый вами язык.
Ваш вывод может выглядеть следующим образом:
Однако на данном этапе ваш ресурс еще не импортирован. Чтобы выполнить импорт, сначала добавьте новую сгенерированную конфигурацию в свой проект, затем удалите первоначальный вызов generateConfigForImport. Наконец, выполните шаги, описанные выше в разделе «Как выполнить импорт». При выполнении apply ваш ресурс будет импортирован и перейдет под управление CDKTF.
Terraform предоставляет мета-аргументы для изменения поведения ресурсов. Например, мета-аргумент for_each создает несколько экземпляров ресурсов на основе карты (map) или множества строк (set of strings). Обходной путь (escape hatch) позволяет использовать эти мета-аргументы в вашем приложении CDKTF и переопределять атрибуты, которые CDKTF пока не может выразить полностью.
В следующем примере определяется провизионер для ресурса с использованием метода addOverride.
При запуске cdktf synth CDKTF генерирует конфигурацию Terraform с провизионером, добавленным в JSON-объект.
Чтобы переопределить атрибут, включите ключ атрибута ресурса в addOverride. Атрибут в обходном пути (escape hatch) записан в змеином регистре (snake case), поскольку конфигурация Terraform в формате JSON использует змеиный регистр вместо верблюжьего (camel case).
Когда вы запускаете cdktf synth, CDKTF генерирует конфигурацию Terraform с переопределенным значением.
Используйте нотацию с точкой для доступа к элементам в массивах: resource.addOverride("configurations.0.https", true).
Обходной путь для динамических блоков (Dynamic Blocks)
Конфигурации Terraform иногда используют динамические блоки для создания связанных ресурсов на основе динамических данных или данных, которые становятся известны только после того, как Terraform подготовит инфраструктуру. Например, вы можете создать серию вложенных блоков для ряда входящих портов виртуального частного облака (VPC). Динамический блок выполняет циклическое обхождение сложного значения и генерирует вложенный блок ресурса для каждого элемента этого сложного значения.
В приложениях CDKTF вы должны использовать обходной путь, когда хотите выполнить цикл по динамическому значению, такому как TerraformVariable или вывод ресурса.
Чтобы использовать обходной путь для циклического обхождения динамических данных, необходимо:
- Установите первый аргумент addOverride равным dynamic.<attribute_name>.
- Создайте значение for_each для второго аргумента и установите его равным списку, по которому вы хотите выполнить итерацию.
- Используйте атрибут в качестве основы для ссылки при обращении к значениям из списка. Например, используйте "${<attribute_name>.value.nested_value}".
В следующем примере добавляются входящие значения путем цилического обхода портов, переданных в качестве TerraformVariable.
Вам следует использовать обходные пути только тогда, когда необходимо работать с динамическими значениями, которые неизвестны до тех пор, пока Terraform не подготовит вашу инфраструктуру. Если вы работаете со статическими значениями, мы рекомендуем использовать функциональность выбранного вами языка программирования для итерации по массиву.
В следующем примере выполняется циклический обход портов без использования обходного пути.
Встроенный ресурс terraform_data
Ресурс terraform_data реализует стандартный жизненный цикл ресурса, но напрямую не выполняет никаких других действий. В CDKTF этот ресурс представлен классом TerraformData, и вы можете импортировать его напрямую из пакета cdktf.
Большие конфигурации ресурсов
Некоторые отдельные ресурсы Terraform имеют очень глубоко вложенные схемы с большим количеством атрибутов. Это раздувает классы конфигурации и замедляет генерацию кода для языков, отличных от TypeScript. Чтобы обойти это, мы иногда ограничиваем глубину классов конфигурации и используем any на более глубоком уровне, а некоторые атрибуты напрямую предоставляем как any в классе конфигурации верхнего уровня.
- aws Provider:aws_quicksight_template.definition, aws_quicksight_dashboard.definition, и aws_quicksight_analysis.definition установлены в anywafv2-related ресурсы имеют много глубоко вложенных атрибутов, которые могут быть пропущены
- aws_quicksight_template.definition, aws_quicksight_dashboard.definition и aws_quicksight_analysis.definition установлены в any
- Ресурсы, связанные с wafv2, имеют множество глубоко вложенных атрибутов, которые могут быть пропущены
