Understanding Terraform Provisioners
Terraform provisioners are a powerful, albeit sometimes complex, feature that allows you to execute scripts or commands on a newly created resource or a resource that is being destroyed. They are primarily used for tasks that Terraform itself cannot manage directly, such as installing software, configuring services, or running initial setup scripts.
What are Terraform Provisioners?
Provisioners are blocks within a Terraform resource that define actions to be taken on the resource after it has been created or before it is destroyed. They act as a bridge between Terraform's declarative infrastructure management and imperative configuration tasks.
Provisioners execute scripts on managed resources.
Terraform provisioners allow you to run scripts on your infrastructure resources after they are created or before they are destroyed. This is useful for tasks like software installation or initial configuration.
Terraform provisioners are a mechanism to execute scripts on remote or local machines. They are typically used to perform tasks that are outside the scope of Terraform's declarative model, such as installing packages, starting services, or running custom setup commands. There are two main types: remote-exec and file.
Types of Provisioners
Terraform offers two primary types of provisioners, each serving a distinct purpose:
| Provisioner Type | Description | Use Case Example |
|---|---|---|
file | Copies files from the local machine to the remote resource. | Uploading a configuration file or an application binary. |
remote-exec | Executes commands on the remote resource. | Running apt-get update and apt-get install nginx on a new EC2 instance. |
How Provisioners Work
When Terraform creates a resource, it first provisions the infrastructure itself. Once the resource is successfully created and accessible, Terraform then executes any configured provisioners. For
remote-exec
file
To execute scripts or commands on a resource after it's created or before it's destroyed, for tasks Terraform can't manage declaratively.
It's important to note that provisioners run after the resource has been created by Terraform. This means they rely on the resource being in a state where remote execution or file transfer is possible (e.g., the instance is running and SSH is available).
Provisioner Configuration
Provisioners are defined within the resource block they are associated with. They accept arguments like
connection
command
source
destination
Consider a simple aws_instance resource. A remote-exec provisioner can be added to install and start an Nginx web server. The connection block specifies the SSH host, user, and private key. The inline argument within remote-exec lists the commands to be executed sequentially on the remote instance.
Text-based content
Library pages focus on text content
The
connection
remote-exec
file
When to Use Provisioners (and When Not To)
Provisioners are best suited for initial setup or one-time configuration tasks. However, they can introduce complexity and make your Terraform configurations less declarative and more imperative. For ongoing configuration management, tools like Ansible, Chef, Puppet, or cloud-native configuration management services are generally preferred.
Think of provisioners as the 'bootstrapping' mechanism for your infrastructure, not as a full-fledged configuration management system.
It's also important to consider the order of operations. Terraform executes provisioners in the order they appear within the resource block. You can also use
when = destroy
They can make Terraform configurations less declarative and more imperative, and for ongoing management, dedicated configuration management tools are often better.
Best Practices and Considerations
When using provisioners, keep the scripts idempotent (meaning running them multiple times has the same effect as running them once). This helps prevent unexpected behavior if Terraform needs to re-apply changes. Also, be mindful of security, especially when handling sensitive information in scripts or connection details.
Consider using
triggers
Learning Resources
The official HashiCorp documentation on Terraform provisioners, covering their purpose, types, and configuration.
A video tutorial explaining the file and remote-exec provisioners with practical examples.
A blog post discussing the use cases, best practices, and potential pitfalls of Terraform provisioners.
Detailed documentation on configuring the connection block for provisioners, including authentication methods.
An official Terraform example demonstrating the use of remote-exec provisioner to install Nginx on an EC2 instance.
A HashiCorp blog post offering insights and best practices for using provisioners effectively in Terraform.
A community tutorial that walks through the concepts and practical application of Terraform provisioners.
A video demonstration focusing specifically on the file provisioner for transferring files.
An article comparing Terraform provisioners with dedicated configuration management tools and when to use each.
Documentation explaining how to configure provisioners that execute during resource destruction.