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

Ресурсы — важнейший элемент языка 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 — указание скрытых зависимостей
• 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). Дополнительная документация доступна на странице об атрибутах только для записи