Output Values

Output values make information about your infrastructure available on the command line, and can expose information for other Terraform configurations to use. Output values are similar to return values in programming languages.

Hands-on: Try the Output Data From Terraform tutorial.

Output values have several uses:

• A child module can use outputs to expose a subset of its resource attributes to a parent module.
• A root module can use outputs to print certain values in the CLI output after running terraform apply.
• When using remote state, root module outputs can be accessed by other configurations via a terraform_remote_state data source.

Resource instances managed by Terraform each export attributes whose values can be used elsewhere in configuration. Output values are a way to expose some of that information to the user of your module.

Declaring an Output Value

Each output value exported by a module must be declared using an output block:

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

The label immediately after the output keyword is the name, which must be a valid identifier. In a root module, this name is displayed to the user; in a child module, it can be used to access the output's value.

The value argument takes an expression whose result is to be returned to the user. In this example, the expression refers to the private_ip attribute exposed by an aws_instance resource defined elsewhere in this module (not shown). Any valid expression is allowed as an output value.

Accessing Child Module Outputs

In a parent module, outputs of child modules are available in expressions as module.<MODULE NAME>.<OUTPUT NAME>. For example, if a child module named web_server declared an output named instance_ip_addr, you could access that value as module.web_server.instance_ip_addr.

Custom Condition Checks

You can use precondition blocks to specify guarantees about output data. The following examples creates a precondition that checks whether the EC2 instance has an encrypted root volume.

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."
  }
}

Custom conditions can help capture assumptions, helping future maintainers understand the configuration design and intent. They also return useful information about errors earlier and in context, helping consumers more easily diagnose issues in their configurations.

Refer to Custom Condition Checks for more details.

Optional Arguments

output blocks can optionally include description, sensitive, ephemeral, and depends_on arguments, which are described in the following sections.

description — Output Value Documentation

Because the output values of a module are part of its user interface, you can briefly describe the purpose of each value using the optional description argument:

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

The description should concisely explain the purpose of the output and what kind of value is expected. This description string might be included in documentation about the module, and so it should be written from the perspective of the user of the module rather than its maintainer. For commentary for module maintainers, use comments.

ephemeral — Avoid storing values in state or plan files

You can mark output values as ephemeral in child modules to pass ephemeral values between modules while avoiding persisting those values to state or plan files. This is useful for managing credentials, tokens, or other temporary resources you do not want to store in Terraform state files.

You can mark an output in a child module as ephemeral by setting the ephemeral attribute to true:

# modules/db/main.tf

output "secret_id" {
  value       = aws_secretsmanager_secret.secret_id
  description = "Temporary secret ID for accessing database in AWS."
  ephemeral   = true
}

Terraform has access to the value of output blocks during plan and apply operations. At the end of a plan or apply operation, Terraform does not persist the value of any ephemeral outputs.

You can only reference ephemeral outputs in specific contexts or Terraform throws an error. The following are valid contexts for referencing ephemeral outputs:

• In another child module's ephemeral output block
• In ephemeral variables
• In ephemeral resources

Note that you cannot set an output value as ephemeral in the root module.

sensitive — Suppressing Values in CLI Output

An output can be marked as containing sensitive material using the optional sensitive argument:

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

Terraform will hide values marked as sensitive in the messages from terraform plan and terraform apply. In the following scenario, our root module has an output declared as sensitive and a module call with a sensitive output, which we then use in a resource attribute.

# 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
}

When we run a plan or apply, the sensitive value is redacted from output:

Terraform 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)

Terraform will still record sensitive values in the state, and so anyone who can access the state data will have access to the sensitive values in cleartext. For more information, see Sensitive Data in State.

depends_on — Explicit Output Dependencies

Since output values are just a means for passing data out of a module, it is usually not necessary to worry about their relationships with other nodes in the dependency graph.

However, when a parent module accesses an output value exported by one of its child modules, the dependencies of that output value allow Terraform to correctly determine the dependencies between resources defined in different modules.

Just as with resource dependencies, Terraform analyzes the value expression for an output value and automatically determines a set of dependencies, but in less-common cases there are dependencies that cannot be recognized implicitly. In these rare cases, the depends_on argument can be used to create additional explicit dependencies:

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,
  ]
}

The depends_on argument should be used only as a last resort. When using it, always include a comment explaining why it is being used, to help future maintainers understand the purpose of the additional dependency.