Ресурсы

Уведомление об устаревании

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 сможет подготовить связанные ресурсы. В следующем примере используется ссылка на свойство namespace в развертывании. Эта ссылка сообщает Terraform, что ему нужно создать пространство имен перед созданием ресурсов.

При работе с определениями инфраструктуры, когда возникает необходимость выполнить рефакторинг или переименовать ресурсы без их удаления и воссоздания, вы можете использовать функцию moveTo следующим образом:

Дополнительную информацию см. в нашем Руководстве по рефакторингу.

Провизионеры (provisioners) могут использоваться для моделирования определенных действий на локальной или удаленной машине с целью подготовки серверов или других инфраструктурных объектов к работе. Вы можете найти более подробную информацию о концепции провизионеров в документации Terraform. Вы можете передать ключ provisioners для определения списка провизионеров, а соединения могут быть настроены с помощью ключа connection. Рабочий пример можно найти в examples/typescript/provisioner.

Если вам нужно использовать специальный объект self, который может применяться только в блоках provisioner и connection для ссылки на родительский ресурс, вы можете использовать класс TerraformSelf следующим образом: TerraformSelf.getString("public_ip").

Если вам нужно убедиться, что условие выполнено до или после создания ресурса, вы можете указать условия. Чтобы добавить одно из них, настройте ключ lifecycle в своем ресурсе с объектом, содержащим precondition и / или postcondition. Эти ключи принимают список условий с ключом condition, содержащим вычисляемое выражение Terraform, и ключом errorMessage, содержащим строку, которая будет отображаться, если условие не выполнено.

Если у вас есть существующие ресурсы, которыми вы хотите управлять с помощью CDKTF, вы можете импортировать их в свое приложение CDKTF. Лучший способ сделать это — использовать функцию блока import в Terraform версии >= 1.5. Вы можете сделать это в CDKTF как с заданной конфигурацией, так и без нее.

Как импортировать

Чтобы импортировать ресурс, сначала создайте экземпляр типа ресурса, который вы хотите импортировать — в нашем случае мы будем использовать S3Bucket. Никакой конфигурации явно не требуется. Затем вы вызываете метод importFrom на объекте ресурса. Этот метод принимает ID импортируемого ресурса в качестве первого аргумента и провайдер в качестве необязательного второго. Провайдер требуется только в том случае, если в вашей конфигурации есть несколько провайдеров одного типа.

При запуске plan / apply вы получите информацию о том, что ваш ресурс будет импортирован. После выполнения apply вы можете удалить вызов importFrom, и ресурс перейдет под управление CDKTF.

Обратите внимание, что Terraform обновит существующие поля импортированного ресурса в соответствии с вашей конфигурацией при взятии его под управление. В нашем случае мы не определяли каких-либо конкретных свойств для S3Bucket, что заставляет Terraform, например, удалить теги, в настоящее время определенные на ресурсе (как видно из плана ниже). Если вы хотите сохранить существующие настройки, вы можете сначала запустить plan, добавить в конфигурацию ресурса все, что изменил бы Terraform, и только после этого применить изменения.

Ваш вывод может выглядеть следующим образом:

Генерация конфигурации для импорта

Если вы не хотите самостоятельно указывать конфигурацию импортируемого ресурса, вы можете использовать статический метод generateConfigForImport в классе импортируемого ресурса. Этот метод принимает область видимости в качестве первого аргумента, идентификатор конструката импортируемого ресурса (как он будет указан в возвращаемой сгенерированной конфигурации), идентификатор импортируемого ресурса и провайдер в качестве необязательного четвертого аргумента. Провайдер требуется только в том случае, если в вашей конфигурации есть несколько провайдеров одного типа.

При запуске cdktf plan <stack-name> Terraform сгенерирует код для импортируемого ресурса, а CDKTF преобразует его на используемый вами язык.

Ваш вывод может выглядеть следующим образом:

Тем не менее, на данный момент ваш ресурс еще не импортирован. Чтобы выполнить импорт, сначала добавьте новую сгенерированную конфигурацию в свой проект, затем удалите исходный вызов generateConfigForImport. Наконец, выполните шаги, описанные в разделе «Как импортировать» выше. При выполнении apply ваш ресурс будет импортирован и перейдет под управление CDKTF.

Terraform предоставляет мета-аргументы для изменения поведения ресурсов. Например, мета-аргумент for_each создает несколько экземпляров ресурсов на основе карты (map) или набора строк. Обходной путь (escape hatch) позволяет использовать эти мета-аргументы в вашем приложении CDKTF и переопределять атрибуты, которые CDKTF пока не может выразить полностью.

В следующем примере определяется провизионер для ресурса с использованием метода addOverride.

Когда вы запускаете cdktf synth, CDKTF генерирует конфигурацию Terraform с провизионером, добавленным в JSON-объект.

Чтобы переопределить атрибут, включите ключ атрибута ресурса в addOverride. Атрибут в лазейке (escape hatch) записан в snake_case, так как конфигурация Terraform JSON использует snake_case вместо camel case.

Когда вы запускаете cdktf synth, CDKTF генерирует конфигурацию Terraform с переопределенным значением.

Используйте нотацию с точкой для доступа к элементам в массивах: resource.addOverride("configurations.0.https", true).

Лазейка для динамических блоков

Конфигурации Terraform иногда используют динамические блоки для создания связанных ресурсов на основе динамических данных или данных, которые становятся известны только после того, как Terraform подготовит инфраструктуру. Например, вы можете создать серию вложенных блоков для ряда входящих (ingress) портов виртуальной частной сети (VPC). Динамический блок выполняет циклическое обход复杂ного значения и генерирует вложенный блок ресурса для каждого элемента этого сложного значения.

В приложениях CDKTF вы должны использовать лазейку (escape hatch), когда хотите выполнить цикл по динамическому значению, такому как 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 установлены в any, ресурсы, связанные с wafv2, имеют множество глубоко вложенных атрибутов, которые могут быть пропущены

• aws_quicksight_template.definition, aws_quicksight_dashboard.definition и aws_quicksight_analysis.definition установлены в any

• ресурсы, связанные с wafv2, имеют множество глубоко вложенных атрибутов, которые могут быть пропущены