This blog post will deep dive into how Terraform handles output and how we can leverage and use output values efficiently across our Terraform projects. Output values allow us to share data between modules and workspaces while also providing us the flexibility to pass values to external systems for automation purposes.

You have come to the right place if you are new to Terraform! Spacelift has curated a ton of valuable material, tutorials, and blog posts around Terraform and how industry experts use it on its Spacelift blog.

What are Terraform Output Values?

Terraform outputs are used for two things: either printing details about a resource/datasource/local/variable or exporting different details about these if we are using a module. They are very useful in both cases. For example, you can build different connection strings you can print in the console for easy use in an app, or you can export things that can be referenced in another configuration/in another module, facilitating the creation of other resources.

Terraform Output vs Input Values

Input variables permit us to customize Terraform configurations without hardcoding any values. This way, we can reuse Terraform modules while assigning custom values based on our needs. Usually, we refer to them as just variables in the context of Terraform.

To define input variables, we must declare them using a variable block:

variable "aws_region" {
  description = "AWS region"
  type        = string
}
 
variable "ec2_instance_type" {
  description = "Instance type for EC2 instances"
  type        = string
  default     = "t2.small"
}

The variable’s name is the label we set following the variable keyword. For every variable, we have the option to set some arguments such as default, type, description, validation, sensitive, and nullable. Check the official documentation about these arguments and how to set them in detail here.

After declaring our input variables, we can utilize them in modules by referencing them like this var.<variable_name>< where «variable_name>< matches the label following the variable keyword. For example, to reference the variable ec2_instance_type that we defined above:

resource "aws_instance" "web_server" {
  ami           = data.aws_ami.amazon_linux.id
  instance_type = var.ec2_instance_type
}

On the other hand, output values empower us to export helpful information from our Terraform projects that we have defined and provisioned with Terraform. In the context of Terraform, we refer to output values as just outputs for simplicity.

Combining input and output variables, we get the flexibility to customize, automate, reuse and share our Terraform code easily. Input variables are similar to function arguments in traditional programming, while output variables work similarly to the return values of a function. Both are equally important to make our Terraform projects functional and facilitate data’s incoming and outgoing flow.

Terraform Outputs Example Use Cases

More specifically, output values are quite helpful in certain use cases:

We can expose information from child modules to a parent module using outputs. Even more, from a root module, we can print outputs in the command line or pass these output values to external systems for automation purposes. When we use a remote state, we can access the root module outputs by other configurations using the terraform_remote_state data source. Output values from child modules aren’t accessible.

Declaring and Using Output Values

In order to define an output value, we have to use the output block:

output "instance_public_ip" {
  description = "Public IP of EC2 instance"
  value       = aws_instance.web_server.public_ip
}

In the above example, we define an output value with the name instance_public_ip. This way, we can pass the value to the parent module or display it to the end-user if it’s an output of the root module.

The value argument, which is the returned output value, takes an expression referencing other resources or module attributes. Terraform only renders and displays outputs when executing terraform apply and not when executing terraform plan.

To use outputs of nested modules from parent modules, we have to reference them as:

module.<module_name>.<output_value_name>

For example, to reference the output value instance_public_ip that we have declared above in a module named aws_web_server_instance from its parent module, we have to use:

module.aws_web_server_instance.instance_public_ip

Let’s examine how we can use all this in a real-world example. In this GitHub repositor, we define the Terraform configuration for this example’s infrastructure. To follow along, you will need to install Terraform, have an AWS account ready, and authenticate with your AWS keys via the command line. Note that you might be charged a few dollars in your AWS account if you follow along.

In this example, we create the necessary infrastructure for a webserver. For the needs of this demo, we split our Terraform configuration into three modules, the root one and two child modules responsible for handling VPC-related resources and EC2 instance-related resources.pro

The project structure looks like this:

For each module, we define a main.tf file that handles the main functionality of the module.

Variable’s declarations and default values are populated in variables.tf files, while for the root module, we also use a terraform.tfvars file to set some variable values.

A good practice is to define our outputs in separate outputs.tf files, as you can see in the above example project structure. By declaring output values in an outputs.tf file per module, we improve the clarity of our modules as it’s easier for users to understand what outputs to expect from them quickly.

The root module utilizes and configures the aws provider and then just simply calls two child modules aws_web_server_vpc and aws_web_server_instance in main.tf of the top directory.

root module main.tf

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "3.16.0"
    }
  }
}
 
provider "aws" {
  region = var.aws_region
}
 
module "aws_web_server_vpc" {
  source = "./modules/aws-web-server-vpc"
}
 
module "aws_web_server_instance" {
  source            = "./modules/aws-web-server-instance"
  ec2_instance_type = var.ec2_instance_type
  vpc_id            = module.aws_web_server_vpc.vpc_id
  subnet_id         = module.aws_web_server_vpc.subnet_id
}

We notice that when calling the module ***aws_web_server_instance, we are passing two expressions using output values from the aws_web_server_vpc module with the notation module.<module_name>.<output_value_name> we have seen earlier.

root module outputs.tf

output "vpc_id" {
  description = "ID of the vpc"
  value       = module.aws_web_server_vpc.vpc_id
}
 
output "instance_id" {
  description = "ID of EC2 instance"
  value       = module.aws_web_server_instance.instance_id
}
 
output "instance_public_ip" {
   description = "Public IP of EC2 instance"
   value       = module.aws_web_server_instance.instance_public_ip
}

We define three output values for our root module, and we expect to see them at the command line after our infrastructure is provisioned. Checking the value parameter of each block, we notice that all of them are coming from output values of the two child modules, and by declaring them as output values of the root module, we are able to pass them through to the command line.

root module variables.tf

variable "aws_region" {
  description = "AWS region"
  type        = string
}
 
variable "ec2_instance_type" {
  description = "Instance type for EC2 instances"
  type        = string
  default     = "t2.small"
}

root module terraform.tfvars

aws_region        = "us-east-1"
ec2_instance_type = "t2.nano"

Let’s examine next our two child modules and how we use output values to pass parameters between them.

aws-web-server-vpc module main.tf

resource "aws_vpc" "web_server" {
  cidr_block       = var.vpc_cidr_block
  instance_tenancy = "default"
 
  tags = {
    Name = var.vpc_name
  }
}
 
resource "aws_subnet" "web_server" {
  vpc_id                  = aws_vpc.web_server.id
  cidr_block              = var.subnet_cidr_block
  map_public_ip_on_launch = true
  availability_zone       = var.aws_az
 
  tags = {
    Name = var.subnet_name
  }
}
 
resource "aws_internet_gateway" "web_server" {
  vpc_id = aws_vpc.web_server.id
 
  tags = {
    Name = var.igw_name
  }
}
 
resource "aws_route_table" "web_server" {
  vpc_id = aws_vpc.web_server.id
  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.web_server.id
  }
 
  tags = {
    Name = var.rt_name
  }
}
 
resource "aws_route_table_association" "web_server" {
  subnet_id      = aws_subnet.web_server.id
  route_table_id = aws_route_table.web_server.id
}

In the above module, we define some resources necessary for the networking layer of our infrastructure.

aws-web-server-vpc module variables.tf

variable "vpc_cidr_block" {
  description = "CIDR block for webserver VPC"
  type        = string
  default     = "10.0.0.0/16"
}
 
variable "vpc_name" {
  description = "Name of the vpc"
  type        = string
  default     = "web_server"
}
 
variable "subnet_cidr_block" {
  description = "CIDR block for the webserver subnet"
  type        = string
  default     = "10.0.0.0/24"
}
 
variable "subnet_name" {
  description = "Name for the webserver subnet"
  type        = string
  default     = "web_server"
}
 
variable "aws_az" {
  description = "Availability Zone for the webserver subnet"
  type        = string
  default     = "us-east-1a"
}
 
variable "igw_name" {
  description = "Name for the Internet Gateway of the webserver vpc"
  type        = string
  default     = "web_server"
}
 
variable "rt_name" {
  description = "Name for the route table of the webserver vpc"
  type        = string
  default     = "web_server"
}

aws-web-server-vpc module outputs.tf

output "vpc_id" {
  description = "ID of the VPC"
  value       = aws_vpc.web_server.id
}
 
output "subnet_id" {
  description = "ID of the VPC subnet"
  value       = aws_subnet.web_server.id
}

The two outputs we export here from this module are passed to the aws-web-server-instance module as parameters in order to create the EC2 instance inside the vpc and subnet that we have just created. We saw how this was handled in the main.tf file of the root module. The output value vpc_id is passed along as an output of the root module and should be printed in the command line after we apply the plan.

Finally, the Terraform configuration for the aws-web-server-instance module uses the passed info from the aws-web-server-vpc module. It creates and configures the web server instance accordingly.

aws-web-server-instance module main.tf

data "aws_ami" "amazon_linux" {
  most_recent = true
  owners      = ["amazon"]
  filter {
    name   = "name"
    values = ["amzn2-ami-hvm-*-x86_64-gp2"]
  }
}
 
resource "aws_security_group" "web_server" {
  name        = var.ec2_security_group_name
  description = var.ec2_security_group_description
  vpc_id      = var.vpc_id
 
  ingress {
    description      = "Allow traffic on port 80 from everywhere"
    from_port        = 80
    to_port          = 80
    protocol         = "tcp"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
 
  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
 
  tags = {
    Name = var.ec2_security_group_name
  }
}
 
resource "aws_instance" "web_server" {
  ami           = data.aws_ami.amazon_linux.id
  instance_type = var.ec2_instance_type
 
  subnet_id              = var.subnet_id
  vpc_security_group_ids = [aws_security_group.web_server.id]
 
  tags = {
    Name = var.ec2_instance_name
  }
 
  user_data = <<-EOF
   #!/bin/bash
   sudo yum update -y
   sudo yum install httpd -y
   sudo systemctl enable httpd
   sudo systemctl start httpd
   echo "<html><body><div>This is a test webserver!</div></body></html>" > /var/www/html/index.html
   EOF
}

aws-web-server-instance module variables.tf

variable "ec2_instance_name" {
  description = "Name for web server EC2 instance"
  type        = string
  default     = "web_server"
}
 
variable "ec2_instance_type" {
  description = "Instance type for web server EC2 instance"
  type        = string
  default     = "t2.micro"
}
 
variable "ec2_security_group_name" {
  description = "Security group name for web server EC2 instance"
  type        = string
  default     = "web_server"
 
}
 
variable "ec2_security_group_description" {
  description = "Security group description for web server EC2 instance"
  type        = string
  default     = "Allow traffic for webserver"
}
 
variable "vpc_id" {
  description = "VPC id for web server EC2 instance"
  type        = string
}
 
variable "subnet_id" {
  description = "Subnet id for web server EC2 instance"
  type        = string
}

The two output values that we pass through the root module are also defined in this module’s outputs.tf file.

output "instance_id" {
  description = "ID of EC2 instance"
  value       = aws_instance.web_server.id
}
 
output "instance_public_ip" {
  description = "Public IP of EC2 instance"
  value       = aws_instance.web_server.public_ip
}

Time to wrap up everything and execute the plan to provision our demo infrastructure.pl

Our terraform plan shows 7 new resources to be added and displays the changes to our three output values declared in the root module. Let’s go ahead and apply the plan.

As expected, the three outputs declared in the root module are displayed at the command line, sweet!

We could use these values to automate other parts of our systems and process, but for now, we can get the value from instance_public_ip and head to http://<instance_public_ip>, and we should see our demo web server up and running.

Great! Everything works as expected.

Terraform Output Command

Output values are stored in the state Terraform file. Since we have successfully applied our plan, we can now access these output values at will. We can leverage the terraform output command for this purpose.

Additionally, we can query individual output values by name like this

terraform output <output_value_name>

To get the raw value without quotes, use the -raw flag.

terraform output -raw <output_value_name>

To get the JSON-formatted output, we can use the -json flag.

This is quite useful when we want to pass the outputs to other tools for automation since JSON is way easier to handle programmatically. Note that Terraform does not protect sensitive output values when using the -json flag.

You can use the -no-color option to ensure the stdout of the command does not have any colors in it. This is not very useful when you are running the terraform output command, but it can be useful when you are running an apply.

There is an option to specify the path to the state file and get the details from it when you are getting your outputs. This is done by specifying the -state=path_to_statefile option.

When we are done, let’s go ahead and delete all these resources to avoid paying for them.

From the top of our repository, execute:

terraform destroy

Terraform Output Values Options & Arguments

When defining output values, we have a couple of options that might help us better define and organize them.

description

The description argument of an output is optional, yet very powerful. Even though it is optional, it should always be used to explain what the output does, as this will be very helpful when you are collaborating with other team members. Some outputs are very easy to understand (like the one below) and may be self-explanatory:

output "instance_id" {
  value       = aws_instance.web_server.id
  description = "ID of the Web Server instance"
}

However, other outputs can be harder to understand:

output "even_numbers" {
  value       = [for i in [1, 2, 3, 4, 5, 6] : i if i % 2 == 0]
  description = "Gets the even numbers from the list"
}

sensitive

In cases where we want to handle sensitive values and suppress them in command line output, we can declare an output value as sensitive. Terraform will redact the values of sensitive outputs when planning, applying, destroying, or querying outputs to avoid printing them to the console. In practice, this is a good use case when we would like to pass values to other Terraform modules or automation tools without exposing them to the intermediate users.

output "example_password" {
  description = "An example DB password"
  value       = aws_db_instance.database.password
  sensitive   = true
}

Note that Terraform won’t redact sensitive output values when you query a specific output by name. After we apply a plan with an output declared as sensitive, the console displays a message with the value redacted.

These values are still recorded in the state files, so anyone who can access them can also access any sensitive values of our Terraform configuration.

depends_on

The depends_on argument creates explicit dependencies between different Terraform components. Usually, it is not required to create dependencies between outputs and other resources, but in some rare cases, you can do that. For example, if you want to reach an application before the security group allows you to do that, you will have connection issues. You can avoid these by creating an explicit dependency to that security group:

output "instance_id" {
  value       = aws_instance.web_server.id
  description = "ID of the Web Server instance"
  depends_on  = [aws_security_group.web_sec.id]
}

Terraform Output Custom Condition Checks

You can use Terraform outputs in conjunction with pre/post conditions to specify guarantees on the specific output data. This is done by adding a precondition/postcondition block inside your resource:

output "instance_id" {
  value       = aws_instance.web_server.id
  description = "ID of the Web Server instance"
  precondition {
    condition     = aws_instance.web_server.instance_type == “t2.micro”
    error_message = "The instance type is different than t2.micro"
  }
}

Terraform Remote State Data Source

Occasionally, we might need to share data between different Terraform configurations with separate states. This is where the terraform_remote_state data sources come into play. We can retrieve the root module outputs from another Terraform configuration using this data source. This built-in data source is available without any extra configuration needed.

Following up on our previous example, let’s say that we would like to create a new subnet in the vpc of our aws-web-server-vpc module. This time, the new subnet needs to be defined in a completely separate Terraform configuration that has its own state. We can leverage the terraform_remote_state to get the value of the vpc_id defined as an output of our previous example’s root module. In this case, we use the local backend to reach the state of another configuration in the local machine. The backend could be any remote backend that points to a Terraform state in a real-world scenario.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "3.16.0"
    }
  }
}
 
provider "aws" {
  region = "us-east-1"
}
 
data "terraform_remote_state" "terraform_output" {
  backend = "local"
 
  config = {
    path = "../terraform-output/terraform.tfstate"
  }
}
 
resource "aws_subnet" "test_terraform_remote_state_subnet" {
  vpc_id            = data.terraform_remote_state.terraform_output.outputs.vpc_id
  cidr_block        = "10.0.1.0/24"
  availability_zone = "us-east-1b"
 
  tags = {
   Name = "test_terraform_remote_state_subnet"
  }
}

Note that only the output values of the root module are accessible from the remote state. If we want to pass values from nested modules, we have to configure a passthrough output value declaration as we defined earlier in the root module of our previous example.

Although this option is handy for some use cases, it also has some caveats. To use this data source, the user must have access to the entire state snapshot, which could potentially expose sensitive data. Check out the official docs to find alternative ways to share data between configurations.

Key Points

We have seen how Terraform handles and exports output values between modules and the different options for outputs configuration. Even more, we compared input and output variables and examined multiple use cases where the use of outputs is helpful. Finally, we went through a complete example of using output values in our Terraform configuration between different modules and printing them to the console.

Thank you for reading, and I hope you enjoyed this “Terraform Outputs” blog post as much as I did.