Crate oxide

Expand description

§The Oxide Rust SDK

SDK for the Oxide API.

§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

§Authentication

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.

§Example

Create a new oxide::Client like this:

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),
        }
    }
}

Modules§

builder: Types for composing operation parameters.
extras: The extra feature adds additional, non-generated, compound interfaces to the Client. It is intended for methods that are functional rather than for those that offer enhanced output or a simplified interface. (This is why the the CLI uses a disk import interface from here, but has a number of custom network subcommands that pretty-print or provide a simpler user interface for common use cases.)
prelude: Items consumers will typically use such as the Client and extension traits.
types: Types used as operation parameters and responses.

Structs§

BasicConfigFile: Clients such as the CLI may specify additional configuration information; authentication only relies on the value of default-profile.
ByteStream: Untyped byte stream used for both success and error responses.
Client: Client for Oxide Region API
ClientConfig: Configuration for creating an authenticated Client
CredentialsFile
ProfileCredentials
ResponseValue: Typed value returned by generated client methods.

Enums§

Error: Error produced by generated client methods.
OxideAuthError: Errors for interfaces related to authentication

Traits§

ClientAffinityExt: Anti-affinity groups give control over instance placement.
ClientDisksExt: Virtual disks are used to store instance-local data which includes the operating system.
ClientFloatingIpsExt: Floating IPs allow a project to allocate well-known IPs to instances.
ClientHiddenExt: TODO operations that will not ship to customers
ClientImagesExt: Images are read-only virtual disks that may be used to boot virtual machines.
ClientInstancesExt: Virtual machine instances are the basic unit of computation. These operations are used for provisioning, controlling, and destroying instances.
ClientLoginExt: Authentication endpoints
ClientMetricsExt: Silo-scoped metrics
ClientPolicyExt: System-wide IAM policy
ClientProjectsExt: Projects are a grouping of associated resources such as instances and disks within a silo for purposes of billing and access control.
ClientRolesExt: Roles are a component of Identity and Access Management (IAM) that allow a user or agent account access to additional permissions.
ClientSessionExt: Information pertaining to the current session.
ClientSilosExt: Silos represent a logical partition of users and resources.
ClientSnapshotsExt: Snapshots of virtual disks at a particular point in time.
ClientSystemHardwareExt: These operations pertain to hardware inventory and management. Racks are the unit of expansion of an Oxide deployment. Racks are in turn composed of sleds, switches, power supplies, and a cabled backplane.
ClientSystemIpPoolsExt: IP pools are collections of external IPs that can be assigned to silos. When a pool is linked to a silo, users in that silo can allocate IPs from the pool for their instances.
ClientSystemMetricsExt: Metrics provide insight into the operation of the Oxide deployment. These include telemetry on hardware and software components that can be used to understand the current state as well as to diagnose issues.
ClientSystemNetworkingExt: This provides rack-level network configuration.
ClientSystemSilosExt: Silos represent a logical partition of users and resources.
ClientSystemStatusExt: Endpoints related to system health
ClientVpcsExt: Virtual Private Clouds (VPCs) provide isolated network environments for managing and deploying services.

Crate oxideCopy item path