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

Входные переменные позволяют настраивать различные аспекты модулей, не изменяя исходный код самого модуля. Эта функциональность позволяет совместно использовать модули в разных конфигурациях OpenTofu, делая модули компонуемыми и пригодными для повторного использования.

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

Если вы знакомы с традиционными языками программирования, может быть полезно сравнить модули с определениями функций:

• Входные переменные похожи на аргументы функции.
• Выходные значения похожи на возвращаемые функцией значения.
• Локальные значения похожи на временные локальные переменные функции.

Объявление входной переменной​

Каждая входная переменная, принимаемая модулем, должна быть объявлена с помощью блока variable:

variable "image_id" {
  type = string
}

variable "availability_zone_names" {
  type    = list(string)
  default = ["us-west-1a"]
}

variable "docker_ports" {
  type = list(object({
    internal = number
    external = number
    protocol = string
  }))
  default = [
    {
      internal = 8300
      external = 8300
      protocol = "tcp"
    }
  ]
}

Метка после ключевого слова variable — это имя переменной, которое должно быть уникальным среди всех переменных одного модуля. Это имя используется для присваивания переменной значения извне и для обращения к ее значению внутри модуля.

Имя переменной может быть любым допустимым идентификатором, кроме следующих: source, version, providers, count, for_each, lifecycle, depends_on, locals.

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

Аргументы​

Интерфейс командной строки OpenTofu определяет следующие необязательные аргументы для объявлений переменных:

• default — значение по умолчанию, которое делает переменную необязательной.
• type — этот аргумент указывает, значения каких типов допустимы для переменной.
• description — задает документацию входной переменной.
• validation — блок для определения правил проверки, обычно в дополнение к ограничениям типов.
• sensitive — ограничивает вывод OpenTofu в интерфейсе командной строки, когда переменная используется в конфигурации.
• nullable — указывает, может ли переменная иметь значение null внутри модуля.
• deprecated — помечает переменную как устаревшую, чтобы предупредить вызывающие стороны о необходимости миграции.

Значения по умолчанию​

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

Ограничения типов​

Аргумент type в блоке variable позволяет ограничить тип значения, которое будет принято в качестве значения переменной. Если ограничение типа не задано, принимаются значения любого типа.

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

Ограничения типов задаются комбинацией ключевых слов типов и конструкторов типов. Поддерживаются следующие ключевые слова типов:

• string
• number
• bool

Конструкторы типов позволяют задавать сложные типы, например коллекции:

• list(<TYPE>)
• set(<TYPE>)
• map(<TYPE>)
• object({<ATTR NAME> = <TYPE>, ... })
• tuple([<TYPE>, ...])

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

Если заданы аргументы type и default, указанное значение по умолчанию должно преобразовываться к заданному типу.

Документация входных переменных​

Поскольку входные переменные модуля являются частью его пользовательского интерфейса, с помощью необязательного аргумента description можно кратко описать назначение каждой переменной:

variable "image_id" {
  type        = string
  description = "The id of the machine image (AMI) to use for the server."
}

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

Пользовательские правила проверки​

Для конкретной переменной можно задать пользовательские правила проверки, добавив блок validation в соответствующий блок variable. Пример ниже проверяет, соответствует ли идентификатор AMI правильному синтаксису.

variable "image_id" {
  type        = string
  description = "The id of the machine image (AMI) to use for the server."

  validation {
    condition     = length(var.image_id) > 4 && substr(var.image_id, 0, 4) == "ami-"
    error_message = "The image_id value must be a valid AMI id, starting with \"ami-\"."
  }
}

Дополнительные сведения см. в разделе «Пользовательские проверки условий».

Скрытие значений в выводе CLI​

Пометка переменной как sensitive не позволяет OpenTofu показывать ее значение в выводе plan или apply при использовании этой переменной в других частях конфигурации.

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

Объявите переменную конфиденциальной, задав аргумент sensitive в значение true:

variable "user_information" {
  type = object({
    name    = string
    address = string
  })
  sensitive = true
}

resource "some_resource" "a" {
  name    = var.user_information.name
  address = var.user_information.address
}

Любые выражения, результат которых зависит от конфиденциальной переменной, также будут считаться конфиденциальными. Поэтому в приведенном выше примере два аргумента resource "some_resource" "a" также будут скрыты в выводе плана:

OpenTofu will perform the following actions:

  # some_resource.a will be created
  + resource "some_resource" "a" {
      + name    = (sensitive value)
      + address = (sensitive value)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

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

  # some_resource.a will be updated in-place
  ~ resource "some_resource" "a" {
      ~ nested_block {
          # At least one attribute in this block is (or was) sensitive,
          # so its contents will not be displayed.
        }
    }

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

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

Случаи, когда OpenTofu может раскрыть конфиденциальную переменную​

Переменная sensitive — это понятие, относящееся к конфигурации, а значения передаются провайдерам без какого-либо сокрытия. Ошибка провайдера может раскрыть значение, если оно включено в сообщение об ошибке. Например, провайдер может вернуть следующую ошибку, даже если «foo» — конфиденциальное значение: "Invalid value 'foo' for field"

Если атрибут ресурса используется в качестве идентификатора ресурса, определяемого провайдером, или входит в его состав, apply раскроет это значение. В примере ниже атрибут prefix задан как конфиденциальная переменная, но впоследствии это значение («jae») раскрывается в составе идентификатора ресурса:

  # random_pet.animal will be created
  + resource "random_pet" "animal" {
      + id        = (known after apply)
      + length    = 2
      + prefix    = (sensitive value)
      + separator = "-"
    }

Plan: 1 to add, 0 to change, 0 to destroy.

...

random_pet.animal: Creating...
random_pet.animal: Creation complete after 0s [id=jae-known-mongoose]

Запрет нулевых входных значений​

Аргумент nullable в блоке переменной определяет, может ли вызывающий модуль присвоить переменной значение null.

variable "example" {
  type     = string
  nullable = false
}

Значение по умолчанию для nullable — true. Если nullable равно true, null является допустимым значением переменной, и конфигурация модуля всегда должна учитывать возможность того, что значение переменной равно null. Передача значения null в качестве входного аргумента модуля переопределит любое значение default.

Значение nullable, равное false, гарантирует, что внутри модуля значение переменной никогда не будет null. Если nullable равно false, а у переменной есть значение default, OpenTofu использует значение по умолчанию, если входной аргумент модуля равен null.

Аргумент nullable управляет только тем, может ли прямое значение переменной быть null. Для переменных типов «коллекция» или «структура», таких как списки или объекты, вызывающая сторона по-прежнему может использовать null во вложенных элементах или атрибутах, если сама коллекция или структура не равна null.

Пометка переменной как устаревшей​

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

variable "examle" {
  type       = string
  deprecated = "'examle' variable must no longer be used due to a typo, use 'example' instead"
}

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

│ Warning: Variable marked as deprecated by the module author
│
│   on main.tf line 3, in module "mod":
│    3:   examle = "a"
│
│ Variable "examle" is marked as deprecated with the following message:
│ 'examle' variable must no longer be used due to a typo, use 'example' instead

Предупреждения об устаревании можно фильтровать или отключить с помощью аргумента CLI -deprecation. Дополнительные сведения см. в описании параметров команд plan и apply.

Использование значений входных переменных​

В модуле, в котором объявлена переменная, к ее значению можно обращаться из выражений как var.<NAME>, где <NAME> соответствует метке, заданной в блоке объявления:

resource "aws_instance" "example" {
  instance_type = "t2.micro"
  ami           = var.image_id
}

Присвоенное переменной значение можно использовать только в выражениях внутри модуля, в котором она объявлена.

Присваивание значений переменным корневого модуля​

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

• По отдельности, с помощью параметра командной строки -var.
• В файлах определений переменных (.tfvars), указанных в командной строке или загружаемых автоматически.
• В качестве переменных среды.

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

Переменные в командной строке​

Чтобы задать отдельные переменные в командной строке, используйте параметр -var при выполнении команд tofu plan и tofu apply:

tofu apply -var="image_id=ami-abc123"
tofu apply -var='image_id_list=["ami-abc123","ami-def456"]' -var="instance_type=t2.micro"
tofu apply -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def456"}'

В примерах выше показан подходящий синтаксис для оболочек Unix, например в Linux или macOS. Дополнительные сведения о кавычках в оболочках, включая примеры для командной строки Windows, см. в разделе «Входные переменные в командной строке».

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

Файлы определений переменных (.tfvars)​

Чтобы задать большое количество переменных, удобнее указать их значения в файле определений переменных (имя файла должно оканчиваться на .tfvars или .tfvars.json), а затем указать этот файл в командной строке с помощью -var-file:

tofu apply -var-file="testing.tfvars"

Файл определений переменных использует тот же базовый синтаксис, что и файлы языка OpenTofu, но содержит только присваивания значений именам переменных:

image_id = "ami-abc123"
availability_zone_names = [
  "us-east-1a",
  "us-west-1c",
]

OpenTofu также автоматически загружает несколько файлов определений переменных, если они существуют:

• Файлы с точными именами terraform.tfvars или terraform.tfvars.json.
• Любые файлы, имена которых оканчиваются на .auto.tfvars или .auto.tfvars.json.

Файлы, имена которых оканчиваются на .json, разбираются как объекты JSON, свойства корневого объекта соответствуют именам переменных:

{
  "image_id": "ami-abc123",
  "availability_zone_names": ["us-west-1a", "us-west-1c"]
}

Переменные среды​

В качестве запасного способа задания переменных OpenTofu ищет в среде собственного процесса переменные среды с именами, начинающимися с TF_VAR_, за которым следует имя объявленной переменной.

Это может быть полезно при запуске OpenTofu в автоматизированном режиме или при последовательном выполнении команд OpenTofu с одними и теми же переменными. Например, в командной строке bash в системе Unix:

$ export TF_VAR_image_id=ami-abc123
$ tofu plan
...

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

Значения сложных типов​

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

Для параметра командной строки -var и переменных среды действуют особые правила. Для удобства OpenTofu по умолчанию интерпретирует значения -var и переменных среды как литеральные строки, для которых достаточно кавычек оболочки и не требуются специальные кавычки OpenTofu. Например, в оболочке Unix:

$ export TF_VAR_image_id='ami-abc123'

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

$ export TF_VAR_availability_zone_names='["us-west-1b","us-west-1d"]'

Для удобства чтения и чтобы не беспокоиться об экранировании в оболочке, мы рекомендуем всегда задавать сложные значения переменных через файлы определений переменных. Дополнительные сведения о кавычках и экранировании аргументов -var см. в разделе «Входные переменные в командной строке».

Значения необъявленных переменных​

Если вы задали значение переменной, но не объявили ее с помощью соответствующего определения variable {}, в зависимости от способа задания значения может появиться ошибка или предупреждение.

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

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

variable "moose" {
  type = string
}

И следующий файл .tfvars:

mosse = "Moose"

Приведут к тому, что OpenTofu предупредит вас об отсутствии объявленной переменной "mosse", что поможет заметить ошибку.

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

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

Приоритет определений переменных​

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

OpenTofu загружает переменные в следующем порядке; более поздние источники имеют приоритет над более ранними:

• Переменные среды
• Файл terraform.tfvars, если он существует.
• Файл terraform.tfvars.json, если он существует.
• Все файлы *.auto.tfvars или *.auto.tfvars.json, обработанные в лексикографическом порядке имен файлов.
• Все параметры -var и -var-file в командной строке — в указанном порядке.