Выходные значения

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

Выходные значения используются в нескольких целях:

• Дочерний модуль может использовать выходные значения, чтобы предоставить родительскому модулю подмножество атрибутов своих ресурсов.
• Корневой модуль может использовать выходные значения для вывода определённых значений в CLI после запуска tofu apply.
• При использовании удалённого состояния выходные значения корневого модуля могут быть доступны другим конфигурациям через источник данных terraform_remote_state.

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

Объявление выходного значения​

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

output "instance_ip_addr" {
  value = aws_instance.server.private_ip
}

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

Аргумент value принимает выражение, результат которого возвращается пользователю. В этом примере выражение ссылается на атрибут private_ip, предоставляемый ресурсом aws_instance, объявленным в другом месте этого модуля (здесь не показан). В качестве выходного значения можно использовать любое допустимое выражение.

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

В родительском модуле выходные значения дочерних модулей доступны в выражениях как module.<MODULE NAME>.<OUTPUT NAME>. Например, если дочерний модуль с именем web_server объявляет выходное значение с именем instance_ip_addr, к нему можно обратиться как к module.web_server.instance_ip_addr.

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

С помощью блоков precondition можно задавать гарантии для выходных данных. В следующих примерах создаётся предварительное условие, проверяющее, зашифрован ли корневой том экземпляра EC2.

output "api_base_url" {
  value = "https://${aws_instance.example.private_dns}:8433/"

  # The EC2 instance must have an encrypted root volume.
  precondition {
    condition     = data.aws_ebs_volume.example.encrypted
    error_message = "The server's root volume is not encrypted."
  }
}

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

Подробнее см. в разделе Пользовательские проверки условий.

Необязательные аргументы​

Блоки output могут включать необязательные аргументы description, sensitive, ephemeral и depends_on, описанные в следующих разделах.

description — документация выходного значения​

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

output "instance_ip_addr" {
  value       = aws_instance.server.private_ip
  description = "The private IP address of the main server instance."
}

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

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

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

output "db_password" {
  value       = aws_db_instance.db.password
  description = "The password for logging in to the database."
  sensitive   = true
}

OpenTofu будет скрывать значения, помеченные как конфиденциальные, в сообщениях tofu plan и tofu apply. В следующем примере корневой модуль содержит выходное значение, объявленное конфиденциальным, и вызов модуля с конфиденциальным выходным значением, которое затем используется в атрибуте ресурса.

# main.tf

module "foo" {
  source = "./mod"
}

resource "test_instance" "x" {
  some_attribute = module.foo.a # resource attribute references a sensitive output
}

output "out" {
  value     = "xyz"
  sensitive = true
}

# mod/main.tf, our module containing a sensitive output

output "a" {
  value     = "secret"
  sensitive = true
}

При запуске планирования или применения конфиденциальное значение будет скрыто в выводе:

OpenTofu will perform the following actions:

  # test_instance.x will be created
  + resource "test_instance" "x" {
      + some_attribute    = (sensitive value)
    }

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

Changes to Outputs:
  + out = (sensitive value)

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

ephemeral — управление сохранением выходных значений в состоянии и плане​

Выходное значение можно пометить как эфемерное с помощью необязательного аргумента ephemeral:

output "db_password" {
  value       = aws_db_instance.db.password
  description = "The password for logging in to the database."
  ephemeral   = true
}

Если автор модуля задаёт атрибут ephemeral в блоке output, его использование будет ограничено допустимыми эфемерными контекстами:

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

# main.tf

module "foo" {
  source = "./mod"
}

resource "test_instance" "x" {
  secret_wo = module.foo.a # the "secret_wo", which is a write only attribute configured by the "test_instance" managed resource can reference this
}

# mod/main.tf, our module containing a sensitive output

output "a" {
  value     = "secret"
  ephemeral = true
}

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

OpenTofu will perform the following actions:

  # test_instance.x will be created
  + resource "test_instance" "x" {
      + secret_wo = (write-only attribute)
    }

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

depends_on — явные зависимости выходных значений​

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

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

Как и в случае с зависимостями ресурсов, OpenTofu анализирует выражение value выходного значения и автоматически определяет набор зависимостей. Однако в некоторых случаях зависимости не удаётся распознать неявно. В таких редких случаях аргумент depends_on можно использовать для создания дополнительных явных зависимостей:

output "instance_ip_addr" {
  value       = aws_instance.server.private_ip
  description = "The private IP address of the main server instance."

  depends_on = [
    # Security group rule must be created before this IP address could
    # actually be used, otherwise the services will be unreachable.
    aws_security_group_rule.local_access,
  ]
}

Аргумент depends_on следует использовать только в крайнем случае. При его использовании всегда добавляйте комментарий с объяснением причины — это поможет будущим сопровождающим понять назначение дополнительной зависимости.

deprecated — пометка выходного значения как устаревшего​

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

output "examle" {
  value      = "someval"
  deprecated = "'examle' output must no longer be used due to a typo, use 'example' instead"
}

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

Warning: Value derived from a deprecated source

  on main.tf line 45, in locals:
  45:   a = module.mod.examle

This value is derived from module.mod.examle, which is deprecated with the following message:

'examle' output must no longer be used due to a typo, use 'example' instead

Предупреждения об устаревании можно фильтровать или отключать с помощью аргумента CLI -deprecation. По умолчанию предупреждения об устаревших выходных значениях модулей объединяются по адресу выходного значения. Чтобы просматривать их по отдельности, можно использовать -consolidation-warnings=false. Дополнительные сведения см. в описании параметров команд plan и apply.