Using Terraform

FlexVM can be used through our API or through our Terraform provider. As with the API, you'll need an API token; the procedure is documented in API v3 Authentication.

Refer to the i3D.net Terraform Documentation for the full provider reference.

Overview

A typical FlexVM deployment is built in three steps, in this order:

1. Cloud — a private cloud that groups your VMs onto dedicated FlexMetal nodes of a single instance type within one site.

2. Node — bare metal capacity provisioned inside the Cloud. The Cloud must have enough node capacity to host your VMs.

3. VM — the virtual machines that run your workloads, scheduled onto the Cloud's nodes.

The examples below follow that order.

1. Creating a Cloud

Use the i3dnet_flexvm_cloud resource to create a private cloud. A Cloud fixes the FlexMetal instance_type and site that every node in it will share.

There is no update API for a Cloud: changing any attribute forces it to be destroyed and recreated.

resource "i3dnet_flexvm_cloud" "my-cloud" {
  name          = "my-private-cloud"
  description   = "Cloud for the odyssey project"
  site          = "frmtl1"
  instance_type = "bm9.hmm.gpu.4rtx4000.64"
}

Note: The Cloud's id (its UUID) is assigned by the platform and is only known after the Cloud is created — you don't set it yourself. In the next steps you reference it as i3dnet_flexvm_cloud.my-cloud.id. Terraform recognizes this reference and automatically creates the Cloud first, then fills in the real UUID when creating the Node and VM. You don't need a depends_on for this ordering to work.

2. Adding a Node

Use the i3dnet_flexvm_node resource to provision a bare metal node inside the Cloud. A Node inherits the Cloud's instance type and location, so cloud_id is the only required input — all other attributes are assigned by the platform.

Provisioning bare metal hardware can take a while; the resource waits until the Node reaches the running status.

resource "i3dnet_flexvm_node" "my-node" {
  cloud_id = i3dnet_flexvm_cloud.my-cloud.id
}

3. Creating a VM

Use the i3dnet_flexvm_vm resource to create a VM, which is scheduled onto the Cloud's nodes.

Exactly one of ssh_keys or user_data_file must be set. Use ssh_keys for simple SSH access, or user_data_file to pass a cloud-init file for more advanced first-boot configuration.

resource "i3dnet_flexvm_vm" "my-vm" {
  cloud_id           = i3dnet_flexvm_cloud.my-cloud.id
  name               = "test-gaming-vm1"
  description        = "Test Gaming VM 1"
  instance_type_name = "vm.gpu.1rtx4000.15c.248g"
  image_name         = "ubuntu-2404-server-amd64"
  ssh_keys           = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwdgjY0AlmkeLknBpoVmJg/quNSifyBHEK1MREpV4Ri [e-mail]"]

  # Optional free-form labels for grouping in the monthly usage report.
  tags = ["project:odyssey", "env:build"]
}

To provide cloud-init user-data from a file instead of ssh_keys, use user_data_file. Relative paths are resolved against Terraform's working directory, so prefer an absolute path or wrap it with abspath("${path.module}/..."):

resource "i3dnet_flexvm_vm" "my-vm-with-user-data" {
  cloud_id           = i3dnet_flexvm_cloud.my-cloud.id
  name               = "test-gaming-vm2"
  description        = "Test Gaming VM 2"
  instance_type_name = "vm.gpu.1rtx4000.15c.248g"
  image_name         = "ubuntu-2404-server-amd64"
  user_data_file     = abspath("${path.module}/cloud-init.yaml")
}

Referencing existing resources

If a Cloud or Node already exists and is not managed by your Terraform configuration, reference it through a data source instead of a resource. Because it is referenced through a data source, terraform destroy leaves the underlying Cloud or Node untouched.

Use the i3dnet_flexvm_cloud data source to look up an existing Cloud by its UUID:

data "i3dnet_flexvm_cloud" "existing" {
  id = "019256ab-1554-73a7-b091-f024b0a724ea"
}

resource "i3dnet_flexvm_vm" "my-vm" {
  cloud_id           = data.i3dnet_flexvm_cloud.existing.id
  name               = "development-ubuntu-2404"
  instance_type_name = "vm.4c.8g"
  image_name         = "ubuntu-2404-server-amd64"
  ssh_keys           = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwdgjY0AlmkeLknBpoVmJg/quNSifyBHEK1MREpV4Ri [e-mail]"]
}

Use the i3dnet_flexvm_node data source to look up a single Node by its Cloud and Node UUID:

data "i3dnet_flexvm_node" "example" {
  cloud_id = "019256ab-1554-73a7-b091-f024b0a724ea"
  id       = "019256ab-1554-73a7-b091-f024b0a724eb"
}

output "node_serial" {
  value = data.i3dnet_flexvm_node.example.serial
}