OUTSCALE Rust SDK

The OUTSCALE Rust SDK enables you to interact with the OUTSCALE API in Rust development environments. It uses the Rust 2021 Edition and provides:

  • A Rust-first API client generated from 3DS OUTSCALE’s OpenAPI definition.

  • An HTTP client based on reqwest with a configurable TLS backend (rustls-tls or native-tls).

  • Strongly typed models for OUTSCALE resources.

To use the OUTSCALE Rust SDK, ensure that you have the following elements:

  • An OUTSCALE account to access the OUTSCALE API.

  • Valid access keys. For more information, see About Access Keys.

  • Network access to the OUTSCALE API endpoints of the desired Regions.

Installation

Before you begin: Make sure a working Rust toolchain (Rust 2021 Edition, stable) and Cargo are installed on your machine.

Install the OUTSCALE Rust SDK from the Cargo crate by running the following command in your terminal:

$ cargo add outscale_api

You can also manually add the crate to your Cargo.toml file using the following syntax:

[dependencies]
outscale_api = "1"

API Access Configuration

The OUTSCALE Rust SDK is a Rust library. You must configure it directly in your code at initialization (for example, through a configuration struct or a builder). To configure access to the OUTSCALE API, you can set a profile in a credentials file or set your access keys directly in the environment variables.

Environment variables have precedence over the credentials file. If access keys are set in the environment variables, the values set in the credentials file will be overridden.

Configuring API Access Using the Credentials File

You can set as many profiles as needed in the ~/.osc/config.json file using the following syntax:

Credentials file sample
{
  "default": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>",
    "region": "<REGION>"
  },
  "profile_1": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>",
    "region": "<REGION>"
  },
  "profile_2": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>",
    "region": "<REGION>"
  }
}

  • This file is shared with other OUTSCALE SDKs and CLIs, like octl.

  • If you haven’t previously created the ~/.osc/config.json file, you need to do so at this step.

You can choose which of those profiles acts as the default by setting its name in the environment variables using the following command:

$ export OSC_PROFILE=<PROFILE>            # default: "default"

Configuring API Access Using Environment Variables

You can set your access keys and Region directly in the environment variables using the following commands:

$ export OSC_ACCESS_KEY=<ACCESS_KEY>
$ export OSC_SECRET_KEY=<SECRET_KEY>
$ export OSC_REGION=<REGION>              # default: eu-west-2

Initialization

You can set up access to the OUTSCALE API with the default profile using the following syntax:

use outscale_api::apis::profile::Profile;
use outscale_api::apis::volume_api::read_volumes;
use outscale_api::models::ReadVolumesRequest;

fn main() {
    let config = Profile::default().and_then(|p| p.try_into()).unwrap();

    // Example: listing volumes
    let request = ReadVolumesRequest::new();
    if let Err(error) = read_volumes(&config, Some(request)) {
        eprintln!("Error: {:?}", error);
        std::process::exit(1);
    }
    println!("OK");
}

You can also set up access to the OUTSCALE API with any previously configured profile using the following syntax:

use outscale_api::apis::profile::ProfileBuilder;
use outscale_api::apis::volume_api::read_volumes;
use outscale_api::models::ReadVolumesRequest;

fn main() {
    let config = ProfileBuilder::from_standard_configuration(None, "profile_name")
        .and_then(|pb| pb.build().try_into())
        .unwrap();

    // Example: listing volumes
    let request = ReadVolumesRequest::new();
    if let Err(error) = read_volumes(&config, Some(request)) {
        eprintln!("Error: {:?}", error);
        std::process::exit(1);
    }
    println!("OK");
}

Selecting the TLS Backend

The OUTSCALE Rust SDK allows you to configure the TLS backend of the HTTP client. By default, the TLS backend is rustls-tls. You can select native-tls that uses OpenSSL instead. In that case, you also need to disable default features to avoid pulling in rustls-tls.

To do so, modify the outscale-api dependency in your Cargo.toml file, following this syntax:

[dependencies]
outscale_api = { version = "1", default-features = false, features = ["native-tls"] }

Working With Async Runtimes

SDK calls are synchronous and block the current thread until completion. The calls must not be made directly from within an async runtime, as doing so would cause a panic when the SDK attempts to block the thread. To avoid this, wrap the calls in tokio::task::spawn_blocking, as shown in the following example:

use outscale_api::apis::profile::Profile;
use outscale_api::apis::vm_api::read_vms;
use outscale_api::models::ReadVmsRequest;

let config = Profile::default().and_then(|p| p.try_into()).unwrap();

let res = tokio::task::spawn_blocking(move || {
    read_vms(&config, Some(ReadVmsRequest::new()))
}).await.unwrap();

Examples

The examples directory of the OUTSCALE Rust SDK GitHub repository contains multiple usage examples. Those examples will show you how to:

  • Set up authentication.

  • Call common OUTSCALE API endpoints.

  • Inspect responses and work with the generated models.

To access the examples on your machine, clone the OUTSCALE Rust SDK GitHub repository, then navigate to the newly created osc-sdk-rust directory, using the following commands:

$ git clone https://github.com/outscale/osc-sdk-rust.git
$ cd osc-sdk-rust

To run the examples, you must first set your eu-west-2 credentials in the environment variables, using the following commands:

$ export OSC_ACCESS_KEY=<ACCESS_KEY>
$ export OSC_SECRET_KEY=<SECRET_KEY>

You can then run the example of your choice (config_file, keypair, region, or volume), using the following command:

$ cargo run --example <example-name>

Reading All Keypairs

The following sample reads all keypairs and prints the total number of existing keypairs.

use outscale_api::apis::keypair_api::read_keypairs;
use outscale_api::apis::profile::Profile;
use outscale_api::models::ReadKeypairsRequest;

fn main() {
    let config = Profile::default().and_then(|p| p.try_into()).unwrap();

    print!("Reading all keypairs... ");
    let request = ReadKeypairsRequest::new();
    let response = match read_keypairs(&config, Some(request)) {
        Err(error) => {
            println!("Error: {:?}", error);
            return;
        }
        Ok(resp) => resp,
    };
    if let Some(keypairs) = response.keypairs {
        println!("OK -> there are {} keypairs", keypairs.len());
    }
}

Creating a Volume

The following sample creates a 10 GiB Performance volume in the eu-west-2a Subregion and prints its ID.

use outscale_api::apis::profile::Profile;
use outscale_api::apis::volume_api::create_volume;
use outscale_api::models::CreateVolumeRequest;

fn main() {
    let config = Profile::default().and_then(|p| p.try_into()).unwrap();

    print!("Creating new volume... ");
    let mut request = CreateVolumeRequest::new("eu-west-2a".to_string());
    request.volume_type = Some("gp2".to_string());
    request.size = Some(10);
    let response = match create_volume(&config, Some(request)) {
        Err(error) => {
            eprintln!("Error: {:?}", error);
            std::process::exit(1);
        }
        Ok(resp) => resp,
    };
    let volume_id = response.volume.unwrap().volume_id.unwrap();
    println!("OK -> created volume id {}", volume_id);
}

Related Pages

Export to PDF