Блоки ресурсов

Ресурсы — важнейший элемент языка OpenTofu. Каждый блок ресурса описывает один или несколько объектов инфраструктуры, например виртуальные сети, вычислительные экземпляры или компоненты более высокого уровня, такие как записи DNS.

Синтаксис ресурсов​

Объявления ресурсов могут включать ряд расширенных возможностей, но для начала работы требуется лишь небольшой их набор. Более сложные возможности синтаксиса, например объявления одного ресурса, создающие несколько похожих удалённых объектов, описаны далее на этой странице.

resource "aws_instance" "web" {
  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"
}

Блок resource объявляет ресурс заданного типа ("aws_instance") с заданным локальным именем ("web"). Имя используется для обращения к этому ресурсу из других частей того же модуля, но не имеет значения за пределами области действия этого модуля.

Тип и имя ресурса вместе служат идентификатором ресурса, поэтому они должны быть уникальны в пределах модуля.

В теле блока (между { и }) указываются аргументы конфигурации самого ресурса. Большинство аргументов в этом разделе зависят от типа ресурса. В данном примере и ami, и instance_type — аргументы, определённые специально для типа ресурса aws_instance.

Типы ресурсов​

Каждый ресурс связан с одним типом ресурса, который определяет, каким типом объекта инфраструктуры он управляет, а также какие аргументы и другие атрибуты поддерживает ресурс.

Провайдеры​

Каждый тип ресурса реализуется провайдером — подключаемым модулем для OpenTofu, предоставляющим набор типов ресурсов. Обычно провайдер предоставляет ресурсы для управления одной облачной или локальной платформой инфраструктуры. Провайдеры распространяются отдельно от OpenTofu, однако OpenTofu может автоматически устанавливать большинство провайдеров при инициализации рабочего каталога.

Чтобы управлять ресурсами, модуль должен указать, какие провайдеры ему требуются. Кроме того, большинству провайдеров необходима конфигурация для доступа к удалённым API, и корневой модуль должен предоставить эту конфигурацию.

Дополнительные сведения см. в следующих разделах:

• Требования к провайдерам — как объявить, какие провайдеры использует модуль.
• Конфигурация провайдеров — как настроить параметры провайдера.

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

Аргументы ресурсов​

Большинство аргументов в теле блока resource относятся к выбранному типу ресурса. В документации по типу ресурса перечислены доступные аргументы и указано, как следует задавать их значения.

В значениях аргументов ресурсов можно в полной мере использовать выражения и другие динамические возможности языка OpenTofu.

Кроме того, существуют некоторые метааргументы, определённые самим OpenTofu и применимые ко всем типам ресурсов. (См. раздел «Метааргументы» ниже.)

Документация по типам ресурсов​

У каждого провайдера есть собственная документация, описывающая его типы ресурсов и аргументы.

Большинство общедоступных провайдеров распространяется через публичный реестр Terraform, где также размещена их документация. На странице провайдера в реестре OpenTofu можно перейти к документации, нажав ссылку "Documentation" в заголовке. Документация провайдеров в реестре привязана к версиям. Чтобы выбрать документацию для другой версии, воспользуйтесь раскрывающимся списком версий в заголовке.

Список общедоступных провайдеров и их документацию можно найти в публичном реестре Terraform.

Поведение ресурсов​

Дополнительные сведения о том, как OpenTofu управляет ресурсами при применении конфигурации, см. в разделе «Поведение ресурсов».

Удаление ресурсов​

Если удалить блок ресурса из конфигурации, по умолчанию OpenTofu уничтожит этот ресурс.

Однако иногда требуется удалить ресурс из конфигурации, не уничтожая соответствующий объект инфраструктуры. В таких случаях его можно удалить из состояния OpenTofu, оставив в удалённой системе.

Для этого выполните следующие действия:

1. Удалите ресурс из конфигурации.
2. Вместо него добавьте блок removed, указав в атрибуте from адрес ресурса, который требуется «забыть».
3. Укажите lifecycle.destroy = false

Например:

removed {
  from = aws_instance.web
  lifecycle {
    destroy = false
  }
}

При выполнении tofu plan OpenTofu сообщит, что ресурс будет удалён из состояния, но не будет уничтожен.

Блоки removed также поддерживают вложенные блоки provisioner. Это полезно, если в resource, который требуется удалить, были блоки provisioner, которые пользователь хочет выполнить до уничтожения самого ресурса.

removed {
  from = aws_s3_bucket.example
  lifecycle {
    destroy = true
  }
  provisioner "local-exec" {
    when = destroy
    command = "echo 'destroying bucket ${self.bucket}'"
  }
}

Поле command поддерживает ссылки только на объект self, each.key и count.index, которые представляют сведения о целевом resource, всё ещё хранящиеся в состоянии OpenTofu.

Блок provisioner будет выполнен только в том случае, если блок removed настроен определённым образом:

• lifecycle.destroy = true
• provisioner.when = destroy

Во всех остальных случаях выполнение будет пропущено.

Дополнительные сведения о провиженерах см. на этой странице.

Метааргументы​

Язык OpenTofu определяет несколько метааргументов, которые можно использовать с любым управляемым типом ресурса, чтобы изменить поведение ресурсов.

О следующих метааргументах рассказывается на отдельных страницах:

• depends_on — для указания неявных зависимостей
• enabled — для условного создания одного экземпляра ресурса в соответствии с выражением
• count — для создания нескольких экземпляров ресурса в соответствии с заданным количеством
• for_each — для создания нескольких экземпляров на основе карты или набора строк
• provider — для выбора нестандартной конфигурации провайдера
• lifecycle — для настройки жизненного цикла
• provisioner — для выполнения дополнительных действий после создания ресурса

Пользовательские проверки условий​

С помощью блоков precondition и postcondition можно задавать предположения и гарантии относительно работы ресурса. В следующем примере создаётся предварительное условие, проверяющее правильность настройки AMI.

resource "aws_instance" "example" {
  instance_type = "t2.micro"
  ami           = "ami-abc123"

  lifecycle {
    # The AMI ID must refer to an AMI that contains an operating system
    # for the `x86_64` architecture.
    precondition {
      condition     = data.aws_ami.example.architecture == "x86_64"
      error_message = "The selected AMI must be for the x86_64 architecture."
    }
  }
}

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

Подробнее см. в разделе «Пользовательские проверки условий».

Тайм-ауты операций​

Для некоторых типов ресурсов предусмотрен специальный вложенный аргумент-блок timeouts, который позволяет задать время выполнения отдельных операций, по истечении которого они будут считаться неудачными. Например, ресурс aws_db_instance позволяет настраивать тайм-ауты для операций create, update и delete.

Обработка тайм-аутов полностью реализуется типом ресурса в провайдере, однако типы ресурсов с этой возможностью обычно определяют дочерний блок timeouts с вложенным аргументом для каждой операции, тайм-аут которой можно настроить. Значением каждого аргумента служит строковое представление длительности, например "60m" для 60 минут, "10s" для десяти секунд или "2h" для двух часов.

resource "aws_db_instance" "example" {
  # ...

  timeouts {
    create = "60m"
    delete = "2h"
  }
}

Набор операций, для которых можно настроить тайм-ауты, определяется каждым типом ресурса отдельно. Большинство типов ресурсов вообще не поддерживают блок timeouts. Узнайте из документации по конкретному типу ресурса, какие операции можно настраивать, если такие операции поддерживаются.

Атрибуты только для записи​

Во многих управляемых ресурсах теперь доступны атрибуты только для записи в качестве альтернативы более старым атрибутам, существовавшим до появления понятия эфемерности. Например, см. ресурс aws_secretsmanager_secret_version и его альтернативу secret_string_wo для secret_string). Дополнительная документация доступна в разделе «Атрибуты только для записи»

Устаревание блоков и атрибутов​

Со временем авторам провайдеров может потребоваться изменить схему некоторых типов ресурсов. В идеале перед полным удалением атрибуты и блоки следует пометить как устаревшие. Это уведомляет пользователей об устаревших возможностях и даёт им время на переход. OpenTofu выдаёт предупреждение каждый раз, когда обнаруживает ссылку на устаревшую возможность провайдера.

resource "example_resource" "dummy" {
}

locals {
  usage = example_resource.dummy.some_deprecated_attribute
}

Warning: Value derived from a deprecated source

  on main.tf line 5, in locals:
  36:         usage = example_resource.dummy.some_deprecated_attribute

This value is derived from example_resource.dummy.some_deprecated_attribute, which is deprecated with the following message:

This is a deprecated message from the provider author

Предупреждения об устаревании можно отфильтровать или отключить с помощью аргумента CLI -deprecation. По умолчанию предупреждения об устаревших ресурсах объединяются по адресу ресурса. Чтобы просматривать их по отдельности, можно использовать -consolidation-warnings=false. Дополнительные сведения см. в описании параметров команд plan и apply.