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

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 — в блоках средств подготовки и подключения.

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