Источники данных

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

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

Использование источников данных​

Доступ к источнику данных осуществляется через особый вид ресурса, известный как ресурс данных, который объявляется с помощью блока data:

data "aws_ami" "example" {
  most_recent = true

  owners = ["self"]
  tags = {
    Name   = "app-server"
    Tested = "true"
  }
}

Блок data запрашивает у OpenTofu чтение данных из указанного источника данных ("aws_ami") и экспорт результата под заданным локальным именем ("example"). Это имя используется для обращения к ресурсу в других местах того же модуля OpenTofu, но не имеет значения за пределами модуля.

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

Тело блока (между { и }) содержит ограничения запроса, определяемые источником данных. Большинство аргументов в этом разделе зависят от источника данных; в данном примере most_recent, owners и tags — это аргументы, определённые специально для источника данных aws_ami.

Чтобы отличать ресурсы данных от ресурсов основного типа (объявляемых блоком resource), последние называют управляемыми ресурсами. Оба вида ресурсов принимают аргументы и экспортируют атрибуты для использования в конфигурации, но управляемые ресурсы заставляют OpenTofu создавать, обновлять и удалять объекты инфраструктуры, тогда как ресурсы данных заставляют OpenTofu только читать объекты. Для краткости управляемые ресурсы часто называют просто «ресурсами», если их значение ясно из контекста.

Аргументы источников данных​

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

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

Большинство элементов в теле блока data определяются выбранным источником данных и относятся именно к нему; в этих аргументах можно в полной мере использовать выражения и другие динамические возможности языка OpenTofu.

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

Поведение ресурсов данных​

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

• По крайней мере один из указанных аргументов — это атрибут управляемого ресурса или другое значение, которое OpenTofu не может определить до этапа применения.
• Ресурс данных напрямую зависит от управляемого ресурса, для которого в текущем плане запланированы изменения.
• У ресурса данных есть пользовательские условия, и он прямо или косвенно зависит от управляемого ресурса, для которого в текущем плане запланированы изменения.

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

Локальные источники данных​

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

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

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

Зависимости ресурсов данных​

Для ресурсов данных действует то же поведение при разрешении зависимостей, что и для управляемых ресурсов. Установка метааргумента depends_on в блоках data откладывает чтение источника данных до применения всех изменений зависимостей.

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

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

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

data "aws_ami" "example" {
  id = var.aws_ami_id

  lifecycle {
    # The AMI ID must refer to an existing AMI that has the tag "nomad-server".
    postcondition {
      condition     = self.tags["Component"] == "nomad-server"
      error_message = "tags[\"Component\"] must be \"nomad-server\"."
    }
  }
}

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

Дополнительные сведения см. в разделе Проверки пользовательских условий.

Несколько экземпляров ресурса​

Ресурсы данных поддерживают метааргументы count и for_each, определённые для управляемых ресурсов, с тем же синтаксисом и поведением.

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

Выбор нестандартной конфигурации провайдера​

Ресурсы данных поддерживают метааргумент provider, определённый для управляемых ресурсов, с тем же синтаксисом и поведением.

Настройки жизненного цикла​

Для жизненного цикла ресурсов данных не предусмотрено настроек. Однако блок lifecycle зарезервирован для будущих версий.

Пример​

Конфигурация источника данных выглядит следующим образом:

# Find the latest available AMI that is tagged with Component = web
data "aws_ami" "web" {
  filter {
    name   = "state"
    values = ["available"]
  }

  filter {
    name   = "tag:Component"
    values = ["web"]
  }

  most_recent = true
}

Описание​

Блок data создаёт экземпляр данных заданного типа (метка первого блока) и имени (метка второго блока). Сочетание типа и имени должно быть уникальным.

Внутри блока (в { }) находится конфигурация экземпляра данных. Конфигурация зависит от типа; как и в случае с ресурсами, у каждого провайдера в общедоступном реестре OpenTofu есть собственная документация по настройке и использованию предоставляемых им типов данных.

Каждый экземпляр данных экспортирует один или несколько атрибутов, которые можно использовать в других ресурсах в виде ссылочных выражений следующей формы: data.<TYPE>.<NAME>.<ATTRIBUTE>. Например:

resource "aws_instance" "web" {
  ami           = data.aws_ami.web.id
  instance_type = "t1.micro"
}

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

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

Нестандартные конфигурации провайдера​

Как и в случае с ресурсами, если в модуле используется несколько конфигураций одного провайдера, с помощью метааргумента provider можно указать, какую конфигурацию использовать:

data "aws_ami" "web" {
  provider = aws.west

  # ...
}

Дополнительные сведения см. в разделе Метааргумент provider ресурса.

Жизненный цикл источника данных​

Если аргументы экземпляра данных не содержат ссылок на вычисляемые значения, например атрибуты ещё не созданных ресурсов, экземпляр данных будет считан, а его состояние обновлено на этапе «обновления» OpenTofu, который по умолчанию выполняется перед созданием плана. Благодаря этому полученные данные доступны во время планирования, а сравнение показывает фактические полученные значения.

Аргументы экземпляра данных могут ссылаться на вычисляемые значения; в этом случае атрибуты самого экземпляра нельзя определить, пока не будут заданы все его аргументы. Тогда обновление экземпляра данных откладывается до этапа «применения», а все подстановки атрибутов экземпляра данных в плане будут отображаться как «вычисляемые», поскольку значения ещё неизвестны.