Terraform Basics

Table of Contents


We cover some important aspects of Terraform deployments on the ThreeFold Grid.

For a complete guide on deploying a full VM on the TFGrid, read this documentation.


Here are the requirements to use Terraform on the TFGrid:

Basic Commands

Here are some very useful commands to use with Terraform:

  • Initialize the repo terraform init
  • Execute a terraform file terraform apply
  • See the output terraform output
    • This is useful when you want to output variables such as public ip, planetary network ip, wireguard configurations, etc.
  • See the state terraform show
  • Destroy terraform destroy

Find A Node

There are two options when it comes to finding a node to deploy on. You can use the scheduler or search for a node with the Nodes Explorer.

  • Use the scheduler
    • Scheduler will help you find a node that matches your criteria
  • Use the Nodes Explorer
    • You can check the Node Finder to know which nodes fits your deployment criteria.
    • Make sure you choose a node which has enough capacity and is available (up and running).


We cover the basic preparations beforing explaining the main file.

  • Make a directory for your project
    • mkdir myfirstproject
  • Change directory
    • cd myfirstproject
  • Create a main file and insert content
    • nano main.tf

Main File Details

Here is a concrete example of a Terraform main file.

Initializing the Provider

terraform {
  required_providers {
    grid = {
      source = "threefoldtech/grid"
      version = "1.8.1"

  • You can always provide a version to chooses a specific version of the provider like 1.8.1-dev to use version 1.8.1 for devnet
  • If version = "1.8.1" is omitted, the provider will fetch the latest version, but for environments other than main you have to specify the version explicitly
  • For devnet, qanet and testnet use version = "<VERSION>-dev", "<VERSION>-qa" and "<VERSION>-rcx" respectively

Providers can have different arguments e.g using which identity when deploying, which Substrate network to create contracts on, etc. This can be done in the provider section, as shown below:

provider "grid" {
    mnemonics = "FROM THE CREATE TWIN STEP"
    network = "dev" # or test to use testnet


Export Environment Variables

When writing the main file, you can decide to leave a variable content empty. In this case you can export the variable content as environment variables.

  • Export your mnemonics
    • export MNEMONICS="..."
  • Export the network
    • export NETWORK="..."

For more info, consult the Provider Manual.

Output Section

The output section is useful to find information such as:

  • the overlay wireguard network configurations
  • the private IPs of the VMs
  • the public IP of the VM exposed under computedip

The output section will look something like this:

output "wg_config" {
    value = grid_network.net1.access_wg_config
output "node1_vm1_ip" {
    value = grid_deployment.d1.vms[0].ip
output "node1_vm2_ip" {
    value = grid_deployment.d1.vms[1].ip
output "public_ip" {
    value = grid_deployment.d1.vms[0].computedip

Start a Deployment

To start a deployment, run the following command terraform init && terraform apply.

Delete a Deployment

To delete a deployment, run the following command:

terraform destroy

Available Flists

You can consult the list of Flists to learn more about the available Flist to use with a virtual machine.

Full and Micro Virtual Machines

There are some key distinctions to take into account when it comes to deploying full or micro VMs on the TFGrid:

  • Only the flist determines if we get a full or a micro VM
  • Full VMs ignore the rootfs field and use the first mount as their root filesystem (rootfs)
  • We can upgrade a full VM by tearing it down, leaving the disk in detached state, and then reattaching the disk to a new VM

Tips on Managing Resources

As a general advice, you can use multiple accounts on TFChain and group your resources per account.

This gives you the following benefits:

  • More control over TFT spending
  • Easier to delete all your contracts
  • Less chance to make mistakes
  • Can use an account to share access with multiple people


This was a quick introduction to Terraform, for a complete guide, please read this documentation. For advanced tutorials and deployments, read this section. To learn more about the different resources to deploy with Terraform on the TFGrid, read this section.

Last change: 2024-02-27