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

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 / tofu.workspace — имя текущего выбранного рабочего пространства.
• terraform.applying / tofu.applying — значение true, когда выполняется этап применения, и false на любом другом этапе (планирование, проверка). Это ключевое слово связано с этапом применения, а не с командой применения: при запуске tofu apply оно сначала получит значение false на этапе планирования, а затем true на этапе применения. Это временное значение, с которым следует обращаться соответствующим образом.

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

Например, если использовать 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).