Terraform

The Oxide Terraform provider is used to declaratively manage Oxide resources with HashiCorp Terraform.

The provider uses the Oxide Go SDK to create, read, update, and delete Oxide resources such as instances, disks, VPCs, projects, silos, and more.

This guide demonstrates how to use the Oxide Terraform provider to create a project. Refer to the Oxide Terraform provider documentation for more information on how to use the provider and learn what resources are supported.

Prerequisites

Install Terraform

Follow the instructions at Install Terraform to download and install Terraform on your machine. Verify your installation once finished.

$ terraform version
Terraform v1.13.2
on linux_amd64

Install the Oxide Terraform Provider

Create a Terraform configuration file named main.tf with the following content. Update the version argument within the required_providers block to use the latest stable version of the Oxide Terraform provider, which can be found in the provider documentation.

terraform {
  required_version = ">= 1.0"

  required_providers {
    oxide = {
      source  = "oxidecomputer/oxide"
      version = ">= 0.14.0"
    }
  }
}

Initialize the configuration to download and install the Oxide Terraform provider.

$ terraform init
Initializing the backend...
Initializing provider plugins...
- Finding oxidecomputer/oxide versions matching ">= 0.14.0"...
- Installing oxidecomputer/oxide v0.14.0...
- Installed oxidecomputer/oxide v0.14.0 (self-signed, key ID E3EAA67E84FBBC3F)

Terraform has been successfully initialized!

For other installation methods, such as building from source, refer to the documentation in the oxidecomputer/terraform-provider-oxide repository.

Configure API Credentials

The API operations in this guide require a user with the collaborator role to generate API credentials.

Follow the instructions in this guide to configure Oxide API credentials. Then, export those credentials as environment variables for use with Terraform.

export OXIDE_HOST='https://oxide.sys.example.com'
export OXIDE_TOKEN='oxide-token-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

Manage an Oxide Project

We’ll use Terraform to manage an Oxide project.

Initialize the Configuration

Create a Terraform configuration file named main.tf with the following content. Update the oxide_project.example block to use a project name that does not already exist in your Oxide silo.

terraform {
  required_version = ">= 1.0"

  required_providers {
    oxide = {
      source  = "oxidecomputer/oxide"
      version = ">= 0.14.0"
    }
  }
}

# Configuration read from the OXIDE_HOST and OXIDE_TOKEN environment variables.
provider "oxide" {}

resource "oxide_project" "example" {
  name        = "example"
  description = "Managed by Terraform."
}

If you haven’t already, initialize your Terraform configuration to download and install the Oxide Terraform provider.

$ terraform init
Initializing the backend...
Initializing provider plugins...
- Reusing previous version of oxidecomputer/oxide from the dependency lock file
- Using previously-installed oxidecomputer/oxide v0.14.0

Terraform has been successfully initialized!

Create the Project

Apply the Terraform configuration to create the Oxide project.

$ terraform apply

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:

  # oxide_project.example will be created
  + resource "oxide_project" "example" {
      + description   = "Managed by Terraform."
      + id            = (known after apply)
      + name          = "example"
      + time_created  = (known after apply)
      + time_modified = (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

oxide_project.example: Creating...
oxide_project.example: Creation complete after 1s [id=78e011c4-4598-48fa-87f6-2a2400988ad6]

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

Read the Project

Show the newly created Oxide project.

$ terraform show
# oxide_project.example:
resource "oxide_project" "example" {
    description   = "Managed by Terraform."
    id            = "78e011c4-4598-48fa-87f6-2a2400988ad6"
    name          = "example"
    time_created  = "2025-09-15 19:27:33.27615 +0000 UTC"
    time_modified = "2025-09-15 19:27:33.27615 +0000 UTC"
}

Update the Project

Change the description of the project.

diff --git a/main.tf b/main.tf
index 7e10afb..e5b9fdc 100644
--- a/main.tf
+++ b/main.tf
@@ -14,5 +14,5 @@ provider "oxide" {}

 resource "oxide_project" "example" {
   name        = "example"
-  description = "Managed by Terraform."
+  description = "Managed by Terraform (updated)."
 }

Apply the configuration to have Terraform update the project description.

$ terraform apply
oxide_project.example: Refreshing state... [id=78e011c4-4598-48fa-87f6-2a2400988ad6]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following
symbols:
  ~ update in-place

Terraform will perform the following actions:

  # oxide_project.example will be updated in-place
  ~ resource "oxide_project" "example" {
      ~ description   = "Managed by Terraform." -> "Managed by Terraform (updated)."
      ~ id            = "78e011c4-4598-48fa-87f6-2a2400988ad6" -> (known after apply)
        name          = "example"
      ~ time_created  = "2025-09-15 19:14:44.021678 +0000 UTC" -> (known after apply)
      ~ time_modified = "2025-09-15 19:14:44.021678 +0000 UTC" -> (known after apply)
    }

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.

  Enter a value: yes

oxide_project.example: Modifying... [id=78e011c4-4598-48fa-87f6-2a2400988ad6]
oxide_project.example: Modifications complete after 1s [id=78e011c4-4598-48fa-87f6-2a2400988ad6]

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

Show the updated Oxide project.

$ terraform show
# oxide_project.example:
resource "oxide_project" "example" {
    description   = "Managed by Terraform (updated)."
    id            = "78e011c4-4598-48fa-87f6-2a2400988ad6"
    name          = "example"
    time_created  = "2025-09-15 19:27:33.27615 +0000 UTC"
    time_modified = "2025-09-15 19:28:13.911466 +0000 UTC"
}

Destroy the Project

Destroy the Oxide project.

$ terraform destroy
oxide_project.example: Refreshing state... [id=78e011c4-4598-48fa-87f6-2a2400988ad6]

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

Terraform will perform the following actions:

  # oxide_project.example will be destroyed
  - resource "oxide_project" "example" {
      - description   = "Managed by Terraform (updated)." -> null
      - id            = "78e011c4-4598-48fa-87f6-2a2400988ad6" -> null
      - name          = "example" -> null
      - time_created  = "2025-09-15 19:27:33.27615 +0000 UTC" -> null
      - time_modified = "2025-09-15 19:28:13.911466 +0000 UTC" -> null
    }

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

oxide_project.example: Destroying... [id=78e011c4-4598-48fa-87f6-2a2400988ad6]
oxide_project.example: Destruction complete after 1s

Destroy complete! Resources: 1 destroyed.

Congratulations! You’ve successfully used the Oxide Terraform provider to manage an Oxide project.

References