Ссылки на именованные значения

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

Типы именованных значений​

Основные виды именованных значений, доступные в OpenTofu:

• Ресурсы
• Входные переменные
• Локальные значения
• Выходные значения дочерних модулей
• Источники данных
• Информация о файловой системе и рабочей области
• Локальные значения блока

В разделах ниже подробно описан каждый вид именованных значений.

Хотя во многих из этих имён используются пути, разделённые точками и напоминающие нотацию атрибутов для элементов объектных значений, они не реализованы как настоящие объекты. Это означает, что их нужно использовать строго в указанном виде: нельзя заменить пути, разделённые точками, нотацией с квадратными скобками, а также нельзя выполнять итерацию по «родительскому объекту» именованной сущности; например, нельзя использовать aws_instance в выражении for для перебора всех ресурсов экземпляров AWS.

Ресурсы​

<RESOURCE TYPE>.<NAME> представляет собой управляемый ресурс указанного типа и имени.

Значение ссылки на ресурс может различаться в зависимости от того, использует ли ресурс count или for_each:

• Если ресурс не использует count или for_each, значение ссылки является объектом. Атрибуты ресурса — это элементы объекта, к которым можно обращаться с помощью нотации с точкой или квадратными скобками.
• Если для ресурса задан аргумент count, значение ссылки представляет собой список объектов, соответствующих его экземплярам.
• Если для ресурса задан аргумент for_each, значение ссылки представляет собой отображение объектов, соответствующих его экземплярам.

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

Подробнее об использовании ссылок на ресурсы см. ниже в разделе ссылки на атрибуты ресурсов.

Входные переменные​

var.<NAME> — это значение входной переменной с указанным именем.

Если в объявлении переменной задано ограничение типа (аргумент type), OpenTofu автоматически преобразует переданное вызывающим кодом значение, чтобы оно соответствовало ограничению типа.

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

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

Локальные значения​

local.<NAME> — это значение локального значения с указанным именем.

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

Выходные значения дочерних модулей​

module.<MODULE NAME> — это значение, представляющее результаты блока module.

Если в соответствующем блоке module не заданы ни count, ни for_each, значение будет объектом с одним атрибутом для каждого выходного значения, определённого в дочернем модуле. Чтобы обратиться к одному из выходных значений модуля, используйте module.<MODULE NAME>.<OUTPUT NAME>.

Если в соответствующем блоке module используется for_each, значение будет отображением объектов. Ключи отображения соответствуют ключам в выражении for_each, а каждое значение представляет собой объект с одним атрибутом для каждого выходного значения, определённого в дочернем модуле, и соответствует одному экземпляру модуля.

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

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

data.<DATA TYPE>.<NAME> — это объект, представляющий ресурс данных указанного типа и имени источника данных. Если для ресурса задан аргумент count, значение представляет собой список объектов, соответствующих его экземплярам. Если для ресурса задан аргумент for_each, значение представляет собой отображение объектов, соответствующих его экземплярам.

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

Информация о файловой системе и рабочей области​

Доступны следующие значения:

• path.module — путь в файловой системе к модулю, в котором размещено выражение. Не рекомендуется использовать path.module для операций записи, так как поведение может различаться в зависимости от того, используете ли вы удалённые или локальные источники модулей. При нескольких вызовах локальных модулей используется один и тот же исходный каталог, поэтому данные в path.module перезаписываются при каждом вызове. Это может привести к состояниям гонки и неожиданным результатам.
• path.root — путь в файловой системе к корневому модулю конфигурации.
• path.cwd — путь в файловой системе к исходному рабочему каталогу, из которого вы запустили OpenTofu до применения аргумента -chdir. Это абсолютный путь, содержащий сведения о структуре файловой системы. Он также полезен в некоторых сложных случаях, когда OpenTofu запускается из каталога, отличного от каталога корневого модуля. По возможности рекомендуется использовать path.root или path.module вместо path.cwd.
• terraform.workspace — имя выбранной в данный момент рабочей области.

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

Например, если напрямую использовать path.cwd для задания пути в аргументе ресурса, то при последующем применении той же конфигурации из другого каталога или на другом компьютере с иной структурой каталогов поставщик сочтёт изменение пути изменением, которое нужно применить, даже если путь по-прежнему указывает на тот же файл.

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

За исключением path.module, рекомендуется использовать значения из этого раздела только в корневом модуле конфигурации. Если вы пишете общий модуль, которому нужен префикс для создания уникальных имён, определите входную переменную модуля и позвольте вызывающему модулю задавать префикс. Затем вызывающий модуль сможет задать его с помощью terraform.workspace, если это уместно, либо использовать другое значение:

module "example" {
  # ...

  name_prefix = "app-${terraform.workspace}"
}

Локальные значения блока​

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

• count.index — в ресурсах, использующих метааргумент count.
• each.key / each.value — в ресурсах, использующих метааргумент for_each.
• self — в блоках провижинера и подключения.

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

Именованные значения и зависимости​

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

Ссылки на атрибуты ресурсов​

Наиболее распространённый тип ссылки — ссылка на атрибут ресурса, объявленного с помощью блока resource или data. Поскольку содержимое таких блоков само по себе может быть довольно сложным, выражения, ссылающиеся на это содержимое, тоже могут быть сложными.

Рассмотрим следующий пример блока ресурса:

resource "aws_instance" "example" {
  ami           = "ami-abc123"
  instance_type = "t2.micro"

  ebs_block_device {
    device_name = "sda2"
    volume_size = 16
  }
  ebs_block_device {
    device_name = "sda3"
    volume_size = 20
  }
}

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

• Аргумент ami, заданный в конфигурации, можно использовать в другом месте с помощью ссылочного выражения aws_instance.example.ami.

• Атрибут id, экспортируемый этим типом ресурса, можно прочитать с помощью того же синтаксиса: aws_instance.example.id.

• К аргументам вложенных блоков ebs_block_device можно обращаться с помощью выражения splat. Например, чтобы получить список всех значений device_name, используйте aws_instance.example.ebs_block_device[*].device_name.

• Вложенные блоки этого типа ресурса не имеют экспортируемых атрибутов, но если бы для ebs_block_device был задокументирован атрибут id, получить список этих атрибутов можно было бы аналогичным образом: aws_instance.example.ebs_block_device[*].id.

• Иногда вложенные блоки определяются так, что каждому блоку назначается логический ключ. Он служит той же цели, что и имя самого ресурса, предоставляя удобный способ ссылаться на конкретный блок в выражениях. Если бы в aws_instance был гипотетический тип вложенного блока device, принимающий такой ключ, его конфигурация выглядела бы следующим образом:

    device "foo" {
      size = 2
    }
    device "bar" {
      size = 4
    }

  К аргументам внутри блоков с ключами можно обращаться с помощью индексного синтаксиса, например aws_instance.example.device["foo"].size.

  Чтобы получить отображение значений определённого аргумента для именованных типов вложенных блоков, используйте выражение for: {for k, device in aws_instance.example.device : k => device.size}.

Если для ресурса задан аргумент count, сам ресурс становится списком объектов экземпляров, а не одним объектом. В этом случае обращаться к атрибутам экземпляров можно с помощью выражений splat или индексного синтаксиса:

• aws_instance.example[*].id возвращает список идентификаторов всех экземпляров.
• aws_instance.example[0].id возвращает только идентификатор первого экземпляра.

Если для ресурса задан аргумент for_each, сам ресурс становится отображением объектов экземпляров, а не одним объектом. Атрибуты экземпляров необходимо указывать по ключу; также к ним можно обращаться с помощью выражения for.

• aws_instance.example["a"].id возвращает идентификатор ресурса с ключом «a».
• [for value in aws_instance.example: value.id] возвращает список идентификаторов всех экземпляров.

Обратите внимание: в отличие от count, выражения splat не применимы напрямую к ресурсам, управляемым с помощью for_each, поскольку выражения splat должны работать со значением-списком. Однако можно использовать функцию values(), чтобы извлечь экземпляры в виде списка, а затем применить выражение splat к этому списку:

• values(aws_instance.example)[*].id

Конфиденциальные атрибуты ресурсов​

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

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

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

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

Пока неизвестные значения​

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

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

Однако в некоторых ситуациях неизвестные значения действительно оказывают существенное влияние:

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

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

• Если аргументу внутри блока module присвоено неизвестное значение, все ссылки на соответствующую входную переменную в дочернем модуле будут использовать это неизвестное значение.

• Если неизвестное значение используется в аргументе value выходного значения, все ссылки на это выходное значение в родительском модуле будут использовать это неизвестное значение.

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

В выходных данных tofu plan неизвестные значения отображаются как (known after apply).