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

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

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

• Дочерний модуль может использовать выходные значения, чтобы предоставить родительскому модулю часть атрибутов своих ресурсов.
• Корневой модуль может использовать выходные значения, чтобы выводить определённые значения в интерфейсе командной строки после выполнения 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 и 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 — сокрытие значений в выводе интерфейса командной строки​

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

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

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