Terraform Basics
Table of Contents
- Introduction
- Requirements
- Basic Commands
- Find A Node
- Preparation
- Main File Details
- Export Environment Variables
- Start a Deployment
- Delete a Deployment
- Available Flists
- Full and Micro Virtual Machines
- Tips on Managing Resources
- Conclusion
Introduction
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.
Requirements
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).
Preparation
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 version1.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
- For more information on this, read this documentation.
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
Conclusion
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.