Creating a Virtual Machine

Current State of our main.tf

You should have something along the lines of the following in your main.tf file.

terraform {
  required_providers {
    katapult = {
      source = "krystal/katapult"
      version = "~> 0.0"
    }
  }
}

provider "katapult" {
  api_key = var.api_key
  organization = var.organization
  data_center = var.data_center
}

Add an IP Address

We'll need an IP Address for our Virtual Machine so we'll create that first.

Below our existing definitions in our main.tf lets add:

resource "katapult_ip" "my_ip" {}

What does this mean?

Okay let's break that down:

• resource - tells Terraform we're going to be creating / managing a resource in our provider.
• "katapult_ip" - this is the type of resource we want to create / manage.
• "my_ip" - this is the name of that resource in Terraform. It is how we will refer to this resource in the rest of our Terraform definitions.

Create our IP Address

Now that we've defined our IP Address resource, we need to tell Terraform to create it.

To do this, we need to run the following command:

terraform apply

View Example Output

This will prompt you with some output like this

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:

  + resource "katapult_ip" "my_ip" {
      + address           = (known after apply)
      + address_with_mask = (known after apply)
      + allocation_id     = (known after apply)
      + allocation_type   = (known after apply)
      + id                = (known after apply)
      + label             = (known after apply)
      + network_id        = (known after apply)
      + reverse_dns       = (known after apply)
      + version           = 4
      + vip               = false
    }

Plan: 1 to add, 0 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.

  Enter a value:

Here you should type yes and press enter.

This will create the IP Address resource in Katapult.

katapult_ip.my_ip: Creating...
katapult_ip.my_ip: Creation complete after 0s [id=ip_HVPzSNmOxEEodjrz]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

tip

You can find more documentation about the katapult_ip resource here: Katapult IP Resource

Add a Virtual Machine

We will now have to add a Virtual Machine Resource.

We can add a minimal resource definition for this.

resource "katapult_virtual_machine" "my_vm" {
  package = "rock-1"
  disk_template = "templates/ubuntu-22-04"
  disk_template_options = {
      install_agent = true
  }
  ip_address_ids = [katapult_ip.my_ip.id]
}

Break it down

• resource - tells Terraform we're going to be creating / managing a resource in our provider.
• "katapult_virtual_machine" - this is the type of resource we want to create / manage.
• "my_vm" - this is the name of that resource in Terraform. It is how we will refer to this resource in the rest of our Terraform definitions.
• package - this is the ID or permalink of the package we want to use for our Virtual Machine. In this case we're using the rock-1 package permalink.
• disk_template - this is the ID or permalink of the disk template we want to use for our Virtual Machine. In this case we're using the templates/ubuntu-22-04 disk template.
• disk_template_options - this is a map of options we can pass to the disk template. In this case we're setting install_agent to true.
• ip_address_ids - this is an array of IP Address IDs we want to assign to our Virtual Machine. In this case we're assigning the IP Address we created earlier.

Create our Virtual Machine

Now that we've defined our Virtual Machine resource, we need to tell Terraform to create it.

To do this, we need to run the following command:

terraform apply

View Example Output

This will prompt you to confirm the actions, answer yes and you will have some output like this:

katapult_ip.my_ip: Refreshing state... [id=ip_KE2ooRpj9kkfEeGf]

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:

  + resource "katapult_virtual_machine" "my_vm" {
      + disk_template         = "templates/ubuntu-22-04"
      + disk_template_options = {
          + "install_agent" = "true"
        }
      + fqdn                  = (known after apply)
      + hostname              = (known after apply)
      + id                    = (known after apply)
      + ip_address_ids        = [
          + "ip_KE2ooRpj9kkfEeGf",
        ]
      + ip_addresses          = (known after apply)
      + name                  = (known after apply)
      + network_speed_profile = (known after apply)
      + package               = "rock-1"
      + state                 = (known after apply)
    }

Plan: 1 to add, 0 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.

  Enter a value: yes

katapult_virtual_machine.my_vm: Creating...
katapult_virtual_machine.my_vm: Still creating... [10s elapsed]
katapult_virtual_machine.my_vm: Still creating... [20s elapsed]
katapult_virtual_machine.my_vm: Still creating... [30s elapsed]
katapult_virtual_machine.my_vm: Creation complete after 35s [id=vm_S0gVQdax9T9tZZhD]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

tip

You can find more documentation about the katapult_virtual_machine resource here: Katapult Virtual Machine Resource

Clean Up

If you're done with your Virtual Machine and IP Address, you can remove them by running:

terraform destroy

This will bypass the trash and remove the resources immediately. To remove the resources and move them to the trash, you can set the following environment variable:

export KATAPULT_SKIP_TRASH_OBJECT_PURGE=true

Then run terraform destroy again.

tip

You can also set this value in the terraform provider config.

provider "katapult" {
  api_key = var.api_key
  organization = var.organization
  data_center = var.data_center
  skip_trash_object_purge = true
}