SDKs

Caution

These SDKs are under development. New releases may contain breaking changes.

Authentication

To use any of the SDKs, you’ll need a host URL and a device token. The easiest way to get a token is through the CLI. First, log in:

$ oxide auth login --host https://my-oxide-rack.com

Then print the token:

$ oxide auth status --show-token

See the Authentication guide for more details.

Rust

Installation

The oxide crate is available on crates.io. You’ll probably want to use tokio as well. Add them to your Cargo.toml file or use cargo add:

$ cargo add oxide
$ cargo add tokio

Usage

The Rust SDK relies on the environment variables OXIDE_HOST and OXIDE_TOKEN or the configuration file generated by the CLI at $HOME/.config/oxide/ hosts.toml. The SDK will first look for the environment variables. If they are not present, it will look for the config file.

use futures::StreamExt;
use oxide::{config::Config, context::Context, prelude::*};

#[tokio::main]
async fn main() {
    let context = Context::new(Config::default()).expect("unabled to create context");
    let client: &Client = context.client().expect("unable to get client");

    let mut projects = client.project_list().stream();
    loop {
        match projects.next().await {
            None => break,
            Some(Ok(project)) => println!("project {}", *project.name),
            Some(Err(err)) => println!("error {}", err),
        }
    }
}

TypeScript

@oxide/api is built on the Fetch API and has no dependencies. It works in the browser, Node.js 18+, Deno, Bun, or any other runtime that supports Fetch.

Installation

$ npm install @oxide/api

Usage

import Oxide from "@oxide/api"

const oxide = new Oxide({
  host: "https://my-oxide-rack.com",
  token: "oxide-abc123",
})

const result = await oxide.methods.projectList({})

if (result.type === "success") {
  console.log(result.data.items.map((p) => p.name))
}

Go

The oxide package requires Go 1.21.x or above.

Installation

Use go get inside your module dependencies directory to install the SDK:

$ go get github.com/oxidecomputer/oxide.go@latest

Usage

package main

import (
	"fmt"

	"github.com/oxidecomputer/oxide.go/oxide"
)

func main() {
	cfg := oxide.Config{
		Address: "https://api.oxide.computer",
		Token:   "oxide-abc123",
	}
	client, err := oxide.NewClient(&cfg)
	if err != nil {
		panic(err)
	}

	ctx := context.Background()
	params := oxide.ProjectCreateParams{
		Body: &oxide.ProjectCreate{
			Description: "A sample project",
			Name:        oxide.Name("my-project"),
		},
	}

	resp, err := client.ProjectCreate(ctx, params)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%+v\n", resp)
}

Terraform

Our provider requires Terraform 1.x or above; we recommend using the latest stable release. Follow these instructions to install Terraform.

Make sure you’ve exported your OXIDE_HOST and OXIDE_TOKEN credentials to the environment variables as specified on the CLI procedure above. See the full Oxide Terraform provider documentation here.

Usage

terraform {
  required_version = ">= 1.0"

  required_providers {
    oxide = {
      source  = "oxidecomputer/oxide"
      version = "0.3.0"
    }
  }
}

provider "oxide" {
  # The provider will default to use $OXIDE_HOST and $OXIDE_TOKEN.
  # If necessary they can be set explicitly (not recommended).
  # host = ""
  # token = ""
}

# Create a blank disk
resource "oxide_disk" "example" {
  project_id  = "c1dee930-a8e4-11ed-afa1-0242ac120002"
  description = "a test disk"
  name        = "mydisk"
  size        = 1073741824
  block_size  = 512
}
Last updated