Executing local programs with Terraform

As we saw in the previous recipe regarding file manipulation, apart from infrastructure provisioning, Terraform also allows you to run programs or scripts that are located on the local workstation where Terraform has been installed.

In this recipe, we will learn how to execute a local program inside the Terraform configuration.

Getting ready

For this recipe, we will complete the Terraform configuration that we used in the previous recipe to write a file on the local machine. Our goal will be to execute a PowerShell command with Terraform that will read and display the contents of the file that we have written using Terraform.

Of course, we will have to run this Terraform script on a Windows operating system.

The source code for this recipe is available at https://github.com/PacktPublishing/Terraform-Cookbook/tree/master/CHAP02/files_local_exec.

How to do it…

Perform the following steps:

1. In the main.tf file, which is in the files directory of the source code from the previous recipe, complete the Terraform configuration with the following code:

resource "null_resource" "readcontentfile" {
  provisioner "local-exec" {
   command = "Get-Content -Path ../mytextfile.txt"
   interpreter = ["PowerShell", "-Command"]
  }
}

2. Then, in a command-line terminal, execute the Terraform workflow commands, as follows:

terraform init
terraform plan -out="app.tfplan"
terraform apply "app.tfplan"

How it works…

In this recipe, we used null_resource, which is a null provider resource. This resource doesn't allow us to create resources, but rather run programs locally.

In this resource, we have the provisioner block, which is of the local-exec type, which operates on our local machine. Then, in this block, we indicate the command to execute, which is the -Content command of PowerShell. With this, we are telling Terraform to use the PowerShell interpreter to execute this command.

When executing the respective Terraform commands, we get the following result:

As you can see, the text This is my text, which we had written in the file (in the local_file resource), is displayed in the Terraform runtime output.

There's more…

In this recipe, we looked at a simple local-exec command being executed with Terraform. It is also possible to execute several commands that are stored in a script file (Bash, PowerShell, and so on) with a sample Terraform configuration, as shown here:

resource "null_resource" "readcontentfile" {
  provisioner "local-exec" {
    command = "myscript.ps1"
    interpreter = ["PowerShell", "-Command"]
  }
}

The local-exec provisioner sets expectations on the local system, which may not be obvious. This is usually otherwise mitigated by cross-platform builds from providers and Terraform itself, where the implementation should generally work the same on any supported platform (macOS/Linux/Windows).

In addition, it is important to know that the local-exec provisioner, once executed, ensures that the Terraform state file cannot be executed a second time by the terraform apply command.

To be able to execute the local-exec command based on a trigger element, such as a resource that has been modified, it is necessary to add a trigger object inside null_resource that will act as the trigger element of the local-exec resource.

The following example code uses a trigger, based on timestamp, to execute the local-exec code at each execution step of Terraform:

resource "null_resource" "readcontentfile" {
  triggers = {
   trigger = timestamp()
  }
  provisioner "local-exec" {
   command = "Get-Content -Path ../mytextfile.txt"
   interpreter = ["PowerShell", "-Command"]
  }
}

In this example, the trigger is a timestamp that will have a different value each time Terraform is run.

We will look at another concrete use case of local-exec in the Executing Azure CLI commands in Terraform recipe in Chapter 6, Provisioning Azure Infrastructure with Terraform.

See also

The local-exec provisioner documentation is available at https://www.terraform.io/docs/provisioners/local-exec.html.