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

Входные переменные позволяют настраивать отдельные аспекты модулей, не изменяя исходный код самого модуля. Эта возможность позволяет использовать модули в разных конфигурациях 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 CLI определяет следующие необязательные аргументы для объявлений переменных:

• default — значение по умолчанию, которое делает переменную необязательной.
• type — этот аргумент задаёт типы значений, допустимые для переменной.
• description — документация входной переменной.
• validation — блок для определения правил проверки, обычно дополняющих ограничения типа.
• sensitive — ограничивает вывод OpenTofu в интерфейсе командной строки, когда переменная используется в конфигурации.
• ephemeral — ограничивает использование переменной эфемерными контекстами.
• 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]

Эфемерность​

Пометка переменной как ephemeral ограничивает её использование следующими эфемерными контекстами:

• Эфемерные ресурсы
• Эфемерные переменные
• Эфемерные выходные значения
• Локальные значения
• Поставщики
• Средства подготовки
• Блоки connection ресурса
• Атрибуты write-only ресурса

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

Объявите переменную эфемерной, задав аргумент ephemeral равным true:

variable "user_password" {
  type      = string
  ephemeral = true
}

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

locals {
  sanitized = trimspace(var.user_password) # `sanitized` is an ephemeral local now
}

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

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

Аргумент 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.

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