Alright … long post … Terraform guide 
Threefold maintains a Terraform provider for the grid. It’s a CLI tool, which might look complicated at first but it’s actually not. Deploying on the Grid using this tool gives you by far the most flexibility and access to all the current grid features. While Weblets are more accessible, Terraform gives you access to a lot more features.
First thing to do is installing it on the client (laptop, desktop, …) your using to deploy on the Grid.
Follow the appropriate guide for your OS.
For Linux this is quite simple:
wget -O- https://apt.releases.hashicorp.com/gpg | gpg --dearmor | sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform
Once you have Terraform installed we can start to create a deployment file: main.tf
Put each deployment file in a separate folder. Once your deployment file is ready, we will initialize Terraform and the Grid provider for this specific deployment (later in this guide). Initialization will download and create some extra files in the folder, so it’s important to keep these separate with your other Terraform deployments.
One could make many different deployment files so this guide will concentrate on a simple full vm. It’s up to you to experiment with all the available examples and features.
terraform {
required_providers {
grid = {
source = "threefoldtech/grid"
}
}
}
provider "grid" {
}
resource "grid_network" "net1" {
nodes = [3000]
ip_range = "10.20.0.0/16"
name = "mynetwork"
description = "My internal Grid network"
add_wg_access = true
}
resource "grid_deployment" "d1" {
node = 3000
network_name = grid_network.net1.name
ip_range = lookup(grid_network.net1.nodes_ip_range, 3000, "")
disks {
name = "root"
size = 50
}
vms {
name = "tftest"
description ="Terraform deployment test"
flist = "https://hub.grid.tf/tf-official-vms/ubuntu-22.04-lts.flist"
cpu = 4
publicip = true
publicip6 = true
memory = 8192
mounts {
disk_name = "root"
mount_point = "/data"
}
planetary = true
env_vars = {
SSH_KEY ="ADD YOUR SSH KEY HERE"
}
}
}
output "wg_config" {
value = grid_network.net1.access_wg_config
}
output "node1_vm1_ip" {
value = grid_deployment.d1.vms[0].ip
}
output "public_ip" {
value = grid_deployment.d1.vms[0].computedip
}
output "public_ip6" {
value = grid_deployment.d1.vms[0].computedip6
}
output "ygg_ip" {
value = grid_deployment.d1.vms[0].ygg_ip
}
So with this example, we will deploy an Ubuntu 22.04 flist on node 3000, with 4 cpu’s / 8GB ram / 50GB disk size / public IPv4/6 / Yggdrasil IP and Wireguard config.
The above example consists of:
- a provider for Terraform
- a network resource
- a deployment, being a full VM
- output statements to get the IP’s and Wireguard config after the deployment. These statements will give you an easy summary after a deployment.
Deploying on the Grid like this will not provide you with automatic node selection. You have to manually look for one that suits your requirements here: https://dashboard.grid.tf/explorer/nodes
Once the main.tf deployment file has been created, we have to set some environment variables. Terraform will use these environment variables for it’s deployments to identify your wallet and to know where to send requests and query’s. The easiest way is to create a file which has these env vars and source it into your terminal sessions every time you want to deploy or destroy something on the gird.
!! Please be very careful with this file as it will contain your wallet mnemonic !!
Example:
export MNEMONICS="YOUR MNEMONIC HERE"
export NETWORK="main"
In Linux you set the environment variables like this: source <filename>
In Windows or Mac I have no idea, if someone could post below would be nice. If your using Windows, I would advice to install the Windows subsystem for Linux anyway 
Some docs on environment variables in Linux or in Terraform.
Once the deployment file is made and environment variables set we can initialize. Move into the folder and execute the following:
cd <folder>
terraform init
Once initialization is ok you can start the actual deploy:
terraform apply -parallelism=1 -auto-approve
To destroy a deployment do:
terraform destroy -parallelism=1 -auto-approve
After a deployment is done you can show it’s details again with:
terraform show
Some important tips:
-
In the example you can see the Node ID is defined 3 times. If you want a different node you have to change it at all 3 places in the main.tf file. Following this example, replace ‘3000’ with your new Node ID 3 times.
-
The subnet you define for the network resource always have to be a /16. This is required if you for example deploy 2 or more vm’s on different nodes but within the same internal subnet / Grid network resource. Each node that is part of the network resource, will get a /24 defined.
-
A VM name can not be longer then 12 characters and can’t contain spaces or special signs.
-
Memory is in MB (Megabytes) and Disk size is in GB (Gigabyte)
-
add_wg_access = truewill enable Wireguard on the network resource. If this is set to true you will get a wireguard config which you can use to connect to the internal subnet running on the gird -
planetary = truewill enable Planetary Network / Yggdrasil accessibility for your deployment. -
SSH_KEY ="ssh-xx..xx..xx"will have to filled in with your public SSH key. This public key will be added to the vm, so you can use your private ssh key to login once a VM is deployed with the userroot. -
IP range of the internal subnet should always be within one of the known Internal Subnet ranges. Example:
ip_range = "10.20.0.0/16" -
Different flists can be found here for full VM’s and here for all other
-
If a new version of the Grid Terraform provider is out, you can update a deployment like this:
terraform init -upgrade. This has to be done in each deployment folder, since the provider files are stored locally in the deployment folder itself. -
If you encounter issues have a look if the issue is known or not, if not create one: https://github.com/threefoldtech/terraform-provider-grid/issues
-
The Grid Provider repo contains a lot of examples for experimenting and using all the features the Threefold Grid has to offer. You can combine these examples to build what you want.
-
Here you can find all the different Terraform options explained for each kind of deployment
There might be a few other / better ways to do things with Terraform. I’m no expert, only learned things along the way. Don’t hesitate to respond if something is wrong, something was forgotten or if there is a better way to do things.
