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

Ресурсы — важнейший элемент языка 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 можно нажать ссылку «Документация» в заголовке, чтобы просмотреть его документацию. Документация провайдеров в реестре привязана к версиям; с помощью раскрывающегося меню выбора версии в заголовке можно переключаться между версиями документации.

Список общедоступных провайдеров и их документацию см. в Публичном реестре 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 — для указания скрытых зависимостей
• 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. Сведения о том, какие операции можно настроить, если такие есть, см. в документации каждого типа ресурса.