Working with the API, CLI, and Terraform

Overview

To make use of the API, CLI, or other programmable interfaces, you must first obtain a rack-generated token and verify your device. This is done via the CLI command oxide auth login which contacts the rack external endpoint to attempt an OAuth 2.0 Device Authorization Grant.

Oxide CLI Tool Download

The Oxide command line tool is supported on a number of operating systems. It can be downloaded from the oxide.rs repo. You may also build your own CLI binary from the repo source code.

Once you have the CLI binary extracted and set to be executable on your workstation, you can follow the steps below to create a device token.

Device Token Setup

Prerequisites

Use a workstation that has a browser application.
Log in the Oxide Console to establish a session.
Download the CLI tool to your workstation.

Procedures

Start a terminal session on your workstation and log in the rack with the following CLI command:
```
oxide auth login --host https://$YourSiloDnsName
```

The CLI will attempt to open the Oxide rack console in a browser window. You should see a prompt like this:

Opened this URL in your browser:
  http://it-ops.sys.oxiderack.company.com/device/verify

Enter the code: SHXD-FDRF

Enter the verification code and click LOG IN ON DEVICE. Once verified, you should see the following message on your terminal:

CurrentUser {
    display_name: "alice",
    id: 8a5bf289-5655-4623-b32c-363166ecba76,
    silo_id: bdabeae2-886d-453b-bec7-8daeb874bf14,
    silo_name: Name(
        "it-ops",
    ),
}
Logged in as 8a5bf289-5655-4623-b32c-363166ecba76

A device token associated with the logged-in user will be granted and stored in ~/.config/oxide/hosts.toml on your workstation.
If you have more than one silo endpoints, you can set the OXIDE_HOST and OXIDE_TOKEN environment variables to select the identity to use.
```
export OXIDE_HOST=$SiloEndpoint
export OXIDE_TOKEN=$SiloOxideToken
```
Verify that the setup is complete by making an API call, e.g. listing ssh-keys:
```
oxide current-user ssh-key list
```

Working with Terraform

Next, we will be creating a simple resource with Terraform.

Prerequisites

Make sure you have Terraform installed by following these instructions.

Our provider requires Terraform 1.x or above; we recommend using the latest stable release whenever possible.

Make sure you’ve exported you credentials to the environment variables as specified on the CLI procedure above.

Procedures

Create a new directory called example and a file called main.tf within it (example/main.tf).

To create a new project copy the following HCL code to the file you just created:

terraform {
  required_version = ">= 1.0"

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

provider "oxide" {}

resource "oxide_project" "example" {
  description = "a test project"
  name        = "myproject"
}

Navigate to your newly created directory by running:

$ cd example/
$ pwd
/home/{YOUR-USER-DIRECTORY}/example

Once that’s done run:

$ terraform init && terraform apply
<...>
Initializing the backend...

Initializing provider plugins...
- Reusing previous version of oxidecomputer/oxide from the dependency lock file
- Using previously-installed oxidecomputer/oxide v0.2.0

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.

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   = "a test project"
      + id            = (known after apply)
      + name          = "myproject"
      + 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:

Type yes and enter to create the project:

  Enter a value: yes

oxide_project.example: Creating...
oxide_project.example: Creation complete after 3s [id=e4f7b4ee-527a-4ff7-a65d-bc1fe36e1348]

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

You can verify with the CLI that your project exists:

$ oxide project view --project myproject
success
Project {
    description: "a test project",
    id: e4f7b4ee-527a-4ff7-a65d-bc1fe36e1348,
    name: Name(
        "myproject",
    ),
    time_created: 2024-02-23T03:29:57.113388Z,
    time_modified: 2024-02-23T03:29:57.113388Z,
}

To remove the recently created resource run:

$ terraform destroy
oxide_project.example: Refreshing state... [id=e4f7b4ee-527a-4ff7-a65d-bc1fe36e1348]

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   = "a test project" -> null
      - id            = "e4f7b4ee-527a-4ff7-a65d-bc1fe36e1348" -> null
      - name          = "myproject" -> null
      - time_created  = "2024-02-23 03:29:57.113388 +0000 UTC" -> null
      - time_modified = "2024-02-23 03:29:57.113388 +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:

Type yes and enter to delete the project:

  Enter a value: yes

oxide_project.example: Destroying... [id=e4f7b4ee-527a-4ff7-a65d-bc1fe36e1348]
oxide_project.example: Destruction complete after 1s

Destroy complete! Resources: 1 destroyed.

Verify the project has been deleted with the CLI:

$ oxide project view --project myproject
error
Error Response: status: 404 Not Found; headers: {"content-type": "application/json", "x-request-id": "3d0b933c-f73a-4c9b-b8f6-f28d99413797", "content-length": "151", "date": "Fri, 23 Feb 2024 03:34:14 GMT"}; value: Error { error_code: Some("ObjectNotFound"), message: "not found: project with name \"myproject\"", request_id: "3d0b933c-f73a-4c9b-b8f6-f28d99413797" }

Documentation

You can obtain a concise summary of CLI commands in json format by executing oxide docs.

Here are the direct links to the programming guide and repos of Oxide-supported integration tools:

API Guide https://docs.oxide.computer/api
CLI Guide https://docs.oxide.computer/cli
Terraform Provider https://registry.terraform.io/providers/oxidecomputer/oxide/latest/docs
Go SDK (beta) https://pkg.go.dev/github.com/oxidecomputer/oxide.go
Rust SDK (beta) https://github.com/oxidecomputer/oxide.rs

Last updated

Working with the API, CLI, and Terraform

Table of Contents