What is Terraform?

Terraform is an orchestration tool that provides infrastructure as code that enables consistent workflow to provision and manage your infrastructure throughout its lifecycle.

Many developers widely use it across the globe to control their services on platforms such as AWS, Google Cloud, Azure, and many more. From now on, anyone using Syntropy Stack as a network management tool will be able to provision and manage their infrastructure via Terraform.

Getting started

Download and Install Terraform

Download Terraform from the official website. It is available on the most popular OS like macOS, Windows, Linux, FreeBSD, OpenBSD or Solaris. You can download it via package manager or binary download, depending on your OS.

Setup your Syntropy Stack account

To be able to use Syntropy Stack Provider for Terraform, you need to create an account and then create an access token.

Start your project

Create a directory with your project:

mkdir my-terraform-project && cd my-terraform-project

To start building your infrastructure, create a resources.tf file

touch resources.tf

Fill it with the following content replacing <ACCESS_TOKEN> with your access token generated in the previous step:

terraform {
  required_providers {
    syntropystack = {
      source  = "SyntropyNet/syntropystack"
      version = "~> 0.1"
    }
  }
}

provider "syntropystack" {
  access_token = "<ACCESS_TOKEN>"
}

Afterwards, save the file and exit the editor. With the required module declaration in place, you can get started.

Now, to begin a new configuration, every Terraform project directory needs to be initialised, do this by running the command below.

terraform init

Terraform sets up the directory to support deploying plans. You should be able to see a success message in your terminal:

....

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

The initialisation process created a directory for the plugins in your Terraform folder under .terraform/providers folder and installs the Sytnropy Stack provider module there.

The Terraform installation for UpCloud is then all set. You are now ready to start planning your first Terraform deployment. Continue on with the rest of the guide to learn how to create and deploy Terraform plans.

Planning infrastructure

With our provider you are able to configure your Syntropy infrastructure by editing the rescources.tf file with the resources that you want to provision and deploy.

Example 1

Login to your Syntropy Stack platform and generate agent token that will be provided in the infrastructure code below. This will create a virtual agent:

resource "syntropystack_agent" "agent" {
  name        = "terraform-provider-syntropystack-agent"
  provider_id = 3
  token       = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Example 2

If you want to create a peer-to-peer connection between two agents, use the code below.

resource "syntropystack_network_connection" "p2p" {
  agent_peer  = [12345, 12346]
  sdn_enabled = false
}

Executing the plan

After deciding what you want to include in your infrastructure, you can see a summary of what will be changed:

terraform plan

As a result you will see a similar message (based on our examples):

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # syntropystack_agent.agent will be created
  + resource "syntropystack_agent" "agent" {
      + id          = (known after apply)
      + name        = "terraform-provider-syntropystack-agent"
      + provider_id = 3
      + token       = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }

  # syntropystack_network_connection.p2p will be created
  + resource "syntropystack_network_connection" "p2p" {
      + agent_peer  = [
          + 12345,
          + 12346,
        ]
      + id          = (known after apply)
      + sdn_enabled = false
    }

Plan: 2 to add, 0 to change, 0 to destroy.

───────────────────────────────────────────────────
Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.

For more fun ways of using our Terraform integration, check out our Recipes.

Deploying your configuration

The next step is to deploy the configuration by executing the plan with the command below.

terraform apply

After showing the summary of changes, you will be prompted with the question Do you want to perform these actions? type yes and hit enter to deploy the infrastructure. After successful completion of the task, you will see a short summary and information, for example:
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Managing resources

Whenever you need to add or change any element of your Sytnropy network setup, edit the file with the definition of your infrastructure (in our example it's resources.tf) file. You can verify your changes by using command:

terraform plan

If you're happy with your updates, use the following command to apply the changes:

terraform apply

You will be prompted with confirmation of changes just below the summary of planned changes:

Plan: 0 to add, 1 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

You can also destroy your infrastructure elements by using the following command:

terraform destroy

You will be shown a list of the elements to be destroyed, you need to confirm this action by typing yes and hitting enter.

Plan: 0 to add, 0 to change, 1 to destroy.

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

Summary

Great job completing this guide! You should now have some resources and the basic knowledge to start building your Syntropy infrastructure. Terraform has many advanced features, so treat it as just the beginning for your journey, feel free to check out our Terraform Recipies and official documentation at Terraform Registry. Check out the Terraform documentation to learn more.