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

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).