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

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

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