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

To connect to the Oxide API, the SDK needs a host URL and a token. There are several ways to specify these:

  • Configuration files: the CLI’s oxide auth login command generates config.toml and credentials.toml in $HOME/.config/oxide/. The credentials file contains sensitive information such as tokens and user IDs.

  • Environment variables: You can set the OXIDE_HOST and OXIDE_TOKEN environment variables.

  • Explicit host URL and token.

The simplest way to create an authenticated client is to use oxide::Client::new_authenticated(), which uses the same credentials and authentication logic as the CLI. By default, it reads data from configuration files in $HOME/.config/oxide.

use futures::StreamExt;
use oxide::{Client, prelude::*};

#[tokio::main]
async fn main() {
    // Make a client from the on-disk configuration.
    let client = Client::new_authenticated()
        .expect("unable to create an authenticated client");

    // Start using the client!

    // For example we can look at the projects in our silo:
    let mut projects = client.project_list().stream();
    loop {
        match projects.next().await {
            // No more items.
            None => break,
            // Print the name of a project.
            Some(Ok(project)) => println!("project {}", *project.name),
            // Something went wrong
            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 = "<host address>"
  # token = "<token value>"
}

# 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