Провижионеры

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

Провижионеры — крайняя мера​

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

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

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

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

Передача данных виртуальным машинам и другим вычислительным ресурсам​

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

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

• Alibaba Cloud: user_data в alicloud_instance или alicloud_launch_template.
• Amazon EC2: user_data или user_data_base64 в aws_instance, aws_launch_template и aws_launch_configuration.
• Amazon Lightsail: user_data в aws_lightsail_instance.
• Microsoft Azure: custom_data в azurerm_virtual_machine или azurerm_virtual_machine_scale_set.
• Google Cloud Platform: metadata в google_compute_instance или google_compute_instance_group.
• Oracle Cloud Infrastructure: metadata или extended_metadata в oci_core_instance или oci_core_instance_configuration.
• VMware vSphere: подключите виртуальный CDROM к vsphere_virtual_machine с помощью блока cdrom, содержащего файл с именем user-data.txt.

Во многие официальные образы дисков дистрибутивов Linux входит программное обеспечение cloud-init, которое может автоматически обрабатывать различными способами данные, переданные описанными выше методами. Это позволяет запускать произвольные сценарии и выполнять базовую настройку системы непосредственно во время загрузки, не подключаясь к машине по SSH.

Если вы создаёте собственные образы машин, используйте переданные описанными выше способами «пользовательские данные» или «метаданные» так, как это подходит вашему приложению. Инструкции по доступу к этим данным во время выполнения можно найти в документации поставщика.

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

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

Подготовка файлов с помощью cloud-config​

Добавьте в конфигурацию OpenTofu источник данных cloudinit_config и укажите файлы, которые нужно подготовить, в виде содержимого text/cloud-config. Источник данных cloudinit_config формирует конфигурации MIME с несколькими частями для использования с cloud-init. Передайте файлы в поле content в виде конфигураций, закодированных в YAML, используя блок write_files.

В следующем примере источник данных my_cloud_config задаёт часть MIME типа text/cloud-config с именем cloud.conf. Для поля part.content задано значение yamlencode, которое кодирует объект JSON write_files в YAML, чтобы система могла подготовить указанные файлы.

data "cloudinit_config" "my_cloud_config" {
  gzip          = false
  base64_encode = false

  part {
    content_type = "text/cloud-config"
    filename     = "cloud.conf"
    content = yamlencode(
      {
        "write_files" : [
          {
            "path" : "/etc/foo.conf",
            "content" : "foo contents",
          },
          {
            "path" : "/etc/bar.conf",
            "content" : file("bar.conf"),
          },
          {
            "path" : "/etc/baz.conf",
            "content" : templatefile("baz.tpl.conf", { SOME_VAR = "qux" }),
          },
        ],
      }
    )
  }
}

Запуск программного обеспечения для управления конфигурацией​

Для удобства пользователей, которым приходится использовать стандартные образы дистрибутивов операционных систем, в OpenTofu предусмотрено несколько специализированных провижионеров для запуска определённых продуктов управления конфигурацией.

Мы настоятельно рекомендуем не использовать их, а выполнять настройку системы в процессе создания собственного образа. Например, HashiCorp Packer предлагает похожий набор провижионеров для управления конфигурацией и позволяет выполнять установку в отдельном процессе сборки, прежде чем создать образ системного диска, который можно развернуть многократно.

Если вы используете программное обеспечение для управления конфигурацией с централизованным серверным компонентом, отложите этап регистрации до загрузки конечной системы из собственного образа. Для этого используйте один из описанных выше механизмов передачи необходимой информации каждому экземпляру, чтобы он мог зарегистрироваться на сервере управления конфигурацией сразу при загрузке, без необходимости принимать команды от OpenTofu по SSH или WinRM.

Возможно, нужные возможности уже поддерживаются провайдером​

Технически можно использовать провижионер local-exec для запуска интерфейса командной строки целевой системы, чтобы создавать, обновлять или иным образом взаимодействовать с удалёнными объектами этой системы.

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

Даже если необходимая вам функция пока недоступна в провайдере, мы рекомендуем считать использование local-exec временным обходным решением и создать задачу в репозитории соответствующего провайдера, чтобы обсудить добавление полноценной поддержки этой функции. Команды разработчиков провайдеров часто определяют приоритет функций на основе интереса пользователей, поэтому создание задачи — способ сообщить о вашем интересе.

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

Использование провижионеров​

Если после ознакомления с рекомендациями в разделах выше вы уверены, что провижионеры — лучший способ решить вашу задачу, добавьте блок provisioner внутрь блока resource вычислительного экземпляра.

resource "aws_instance" "web" {
  # ...

  provisioner "local-exec" {
    command = "echo The server's IP address is ${self.private_ip}"
  }
}

Для провижионера local-exec не требуется дополнительная настройка, однако большинству других провижионеров необходимо подключаться к удалённой системе по SSH или WinRM. Добавьте блок connection, чтобы OpenTofu знал, как взаимодействовать с сервером.

В OpenTofu предусмотрено несколько встроенных провижионеров. Также можно использовать сторонние провижионеры в виде плагинов, разместив их в %APPDATA%\terraform.d\plugins, ~/.terraform.d/plugins, $XDG_DATA_HOME/opentofu/plugins или в том же каталоге, где установлен исполняемый файл OpenTofu. Однако мы не рекомендуем использовать какие-либо провижионеры, кроме встроенных file, local-exec и remote-exec.

Все провижионеры поддерживают метааргументы when и on_failure, описанные ниже (см. разделы Провижионеры, выполняемые при удалении и Обработка сбоев).

Объект self​

Выражения в блоках provisioner не могут ссылаться на родительский ресурс по имени. Вместо этого можно использовать специальный объект self.

Объект self представляет родительский ресурс провижионера и содержит все атрибуты этого ресурса. Например, используйте self.public_ip, чтобы обратиться к атрибуту public_ip ресурса aws_instance.

Скрытие журналов провижионеров в выводе CLI​

Конфигурация блока provisioner может использовать чувствительные значения, например чувствительные переменные sensitive или чувствительные выходные значения sensitive. В таком случае весь вывод журнала провижионера автоматически скрывается, чтобы чувствительные значения не отображались.

Провижионеры, выполняемые при создании​

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

Если провижионер, выполняемый при создании, завершается с ошибкой, ресурс помечается как загрязнённый. При следующем tofu apply будет запланировано удаление и повторное создание загрязнённого ресурса. OpenTofu поступает так, поскольку неудачный запуск провижионера может оставить ресурс в частично настроенном состоянии. Поскольку OpenTofu не может определить, что именно делает провижионер, единственный способ гарантировать корректное создание ресурса — создать его заново. Это и называется пометкой как загрязнённого.

Изменить такое поведение можно с помощью атрибута on_failure, подробно описанного ниже.

Провижионеры, выполняемые при удалении​

Если указано when = destroy, провижионер запускается при удалении содержащего его ресурса.

resource "aws_instance" "web" {
  # ...

  provisioner "local-exec" {
    when    = destroy
    command = "echo 'Destroy-time provisioner'"
  }
}

Провижионеры удаления запускаются до удаления ресурса. Если они завершаются с ошибкой, OpenTofu выдаст ошибку и повторно запустит их при следующем tofu apply. Поэтому провижионеры удаления должны безопасно выполняться несколько раз.

Провижионеры удаления запускаются, только если они остаются в конфигурации на момент удаления ресурса. Если полностью удалить из конфигурации блок ресурса с провижионером удаления, его конфигурация провижионера также будет удалена, и поэтому провижионер не запустится. Чтобы обойти это ограничение и безопасно удалить ресурс с провижионером удаления, выполните следующие действия:

• Измените конфигурацию ресурса, добавив count = 0.
• Примените конфигурацию, чтобы удалить все существующие экземпляры ресурса, включая запуск провижионера удаления.
• Полностью удалите блок ресурса из конфигурации вместе с блоками provisioner.
• Примените конфигурацию ещё раз. Дополнительные действия не потребуются, поскольку ресурсы уже удалены.

Из-за этого ограничения провижионеры удаления следует использовать редко и с осторожностью.

Несколько провижионеров​

В ресурсе можно указать несколько провижионеров. Они выполняются в порядке, в котором указаны в файле конфигурации.

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

Пример с несколькими провижионерами:

resource "aws_instance" "web" {
  # ...

  provisioner "local-exec" {
    command = "echo first"
  }

  provisioner "local-exec" {
    command = "echo second"
  }
}

Обработка сбоев​

По умолчанию сбой провижионера приводит к сбою самого применения конфигурации в OpenTofu. Изменить это поведение можно с помощью параметра on_failure. Допустимые значения:

• continue — проигнорировать ошибку и продолжить создание или удаление.

• fail — выдать ошибку и прекратить применение конфигурации (поведение по умолчанию). Если это провижионер создания, ресурс помечается как загрязнённый.

Пример:

resource "aws_instance" "web" {
  # ...

  provisioner "local-exec" {
    command    = "echo The server's IP address is ${self.private_ip}"
    on_failure = continue
  }
}