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

Выходные значения предоставляют информацию о вашей инфраструктуре в командной строке и могут открывать доступ к информации для использования в других конфигурациях 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
}

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

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
}

При выполнении команды plan или apply значение, используемое в блоке 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.