Nebius AI Cloud API

This repository contains the .proto files defining the gRPC API for Nebius AI Cloud services. It also provides a pre-generated Rust crate for interacting with this API.

Rust Crate Usage

This crate provides native Rust types and tonic clients for all Nebius AI Cloud services.

Setup

Add the crate to your Cargo.toml dependencies. You will also need tokio and tonic.

[dependencies]
nebius-api = "0.1" # Replace with the latest version from crates.io
tokio = { version = "1", features = ["full"] }
tonic = { version = "0.13", features = ["transport"] }

Example: Creating a Virtual Machine

The following example demonstrates how to create a simple virtual machine.

First, ensure you have an IAM token for authentication. You can get one using the Nebius CLI: nebius iam get-access-token. It is recommended to set this token as an environment variable. You will also need to provide IDs for your project, a subnet, and the boot image.

use nebius_api::{
    common::v1::ResourceMetadata,
    compute::v1::{
        instance_service_client::InstanceServiceClient, attached_disk_spec, resources_spec, AttachedDiskSpec,
        CreateInstanceRequest, ExistingDisk, InstanceSpec, NetworkInterfaceSpec, ResourcesSpec,
    },
};
use tonic::{transport::Channel, Request};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Get environment variables.
    let project_id = std::env::var("NEBIUS_PROJECT_ID").expect("NEBIUS_PROJECT_ID must be set");
    let subnet_id = std::env::var("NEBIUS_SUBNET_ID").expect("NEBIUS_SUBNET_ID must be set");
    let image_id = std::env::var("NEBIUS_IMAGE_ID").unwrap_or("image-ubuntu-2204-lts".to_string());
    let token = std::env::var("NEBIUS_TOKEN").expect("NEBIUS_TOKEN must be set");

    // 2. Create a channel to the API endpoint.
    let channel = Channel::from_static("https://compute.api.nebius.cloud")
        .connect()
        .await?;

    // 3. Create a client with an interceptor to add the authorization token.
    let mut client = InstanceServiceClient::with_interceptor(channel, move |mut req: Request<()>| {
        let auth_header = format!("Bearer {}", token).parse().unwrap();
        req.metadata_mut().insert("authorization", auth_header);
        Ok(req)
    });

    // 4. Prepare the request to create a VM.
    let request = tonic::Request::new(CreateInstanceRequest {
        metadata: Some(ResourceMetadata {
            parent_id: project_id,
            name: "demo-vm".into(),
            ..Default::default()
        }),
        spec: Some(InstanceSpec {
            resources: Some(ResourcesSpec {
                platform: "standard-v1".into(),
                size: Some(resources_spec::Size::Preset("standard-1-4".into())),
            }),
            network_interfaces: vec![NetworkInterfaceSpec {
                subnet_id,
                ..Default::default()
            }],
            boot_disk: Some(AttachedDiskSpec {
                attach_mode: 2, // READ_WRITE
                device_id: "boot".into(),
                r#type: Some(attached_disk_spec::Type::ExistingDisk(ExistingDisk {
                    id: image_id,
                })),
            }),
            ..Default::default()
        }),
    });

    // 5. Call the API. This returns an Operation.
    let response = client.create(request).await?;
    let operation = response.into_inner();

    println!("VM creation operation started: {}", operation.id);
    println!("You can poll the operation status using the OperationService.");

    Ok(())
}

### Development

If you are working on this crate directly, you will need the `buf` CLI to be installed. The Rust code is generated automatically from the `.proto` files when you run `cargo build`.

---

## API Documentation

The following sections describe the Nebius gRPC API in detail, including authentication, endpoints, and usage patterns.

## Tools

While you can interact directly with the Nebius AI Cloud API, we recommend leveraging the following tools to simplify your development and operations:

- [Nebius CLI](https://docs.nebius.com/cli)
- [Terraform Provider](https://docs.nebius.com/terraform-provider)
- [SDK for Go](https://github.com/nebius/gosdk)
- [Python SDK](https://github.com/nebius/pysdk)

Using these tools can save time and reduce the complexity of managing authentication, constructing requests, and handling responses.

## API Endpoints

Nebius AI Cloud gRPC services are accessed via endpoints formatted as `{service-name}.{base-address}`.
You can find a list of endpoints and services [here](endpoints.md). Below is an explanation of how these addresses are constructed:

1. **Base Address**:
   - The current base address is `api.nebius.cloud:443`, though additional base addresses will be introduced soon.
1. **Service Name Derivation**:
   - Services with `option (api_service_name)`:
     - Some services explicitly define their name using this annotation (e.g., `option (api_service_name) = "foo.bar"`), this value becomes the `{service-name}` used in the address.
     - For example, requests to `TokenExchangeService` ([iam](nebius/iam/v1/token_exchange_service.proto)) would be sent to: `tokens.iam.api.nebius.cloud:443`.
   - Services without `option (api_service_name)`:
     - For services lacking this annotation, the `{service-name}` is derived from the first level directory within the `.proto` file path.
     - For instance, requests to `DiskService` (declared in [nebius/**compute**/v1/disk_service.proto](nebius/compute/v1/disk_service.proto)) would be directed to `compute.api.nebius.cloud:443`
1. **Special Case**: `OperationService`
   - `nebius.common.v1.OperationService` ([common](nebius/common/v1/operation_service.proto)) is an exception to the naming convention.
   - When fetching the status of an operation returned by another service, use the original service's address.
   - As an example, to fetch the status of an operation created by `DiskService` ([compute](nebius/compute/v1/disk_service.proto)), you would use: `compute.api.nebius.cloud:443`.

## Authentication

Nebius AI Cloud uses bearer token authentication.
All requests must include an `Authorization: Bearer <IAM-access-token>` header.

### User Account Authentication

Prerequisites: Ensure you have installed and configured the `nebius` CLI as per the [documentation](https://docs.nebius.com/cli/).

Steps:

1. Run `nebius iam get-access-token` to retrieve your IAM access token.
1. Include this token in the `Authorization` header of your gRPC requests.

Example:

```bash
grpcurl -H "Authorization: Bearer $(nebius iam get-access-token)" \
  cpl.iam.api.nebius.cloud:443 \
  nebius.iam.v1.ProfileService/Get

{
  "userProfile": {
    "id": "useraccount-e00...",
    "federationInfo": {
      "federationUserAccountId": "...",
      "federationId": "federation-e00..."
    },
    "attributes": {
      ...
    }
  }
}

Service Account Authentication

Prerequisites: You must have created a service account with the necessary credentials as outlined in the documentation.

Service account credentials cannot be directly used for authentication. Your service needs to obtain an IAM token using OAuth 2.0 with a compatible client library that implements RFC-8693 and JWT to generate a claim.

Steps:

1. Generate a JWT:
   • Use the RS256 signing algorithm.
   • Include the following claims:
     • kid: Public Key ID of your service account.
     • iss: Your service account ID.
     • sub: Your service account ID.
     • exp: Set a short expiration time (e.g., 5 minutes) as the token is only used for exchanging another token.
   • Sign the JWT with the service account's private key.
2. Exchange JWT for an IAM Token:
   • Using gRPC: Call nebius.iam.v1.TokenExchangeService/Exchange on tokens.iam.api.nebius.cloud:443.
   • Using HTTP: Send a POST request to https://auth.eu.nebius.com:443/oauth2/token/exchange.
3. Use the IAM Token from access_token from the response
4. Repeat the process before the IAM token expires (indicated by expires_in from the response).

SA_ID="serviceaccount-e00..."
KEY_ID="publickey-e00..."
PRIVATE_KEY_PATH="private_key.pem"

# https://github.com/mike-engel/jwt-cli
JWT=$(jwt encode \
  --alg RS256 \
  --kid $KEY_ID \
  --iss $SA_ID \
  --sub $SA_ID \
  --exp="$(date --date="+5minutes" +%s 2>/dev/null || date -v+5M +%s)" \
  --secret @${PRIVATE_KEY_PATH})

read -r -d '' REQUEST <<EOF
{
  "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
  "requestedTokenType": "urn:ietf:params:oauth:token-type:access_token",
  "subjectToken": "${JWT}",
  "subjectTokenType": "urn:ietf:params:oauth:token-type:jwt"
}
EOF

RESPONSE=$(grpcurl -d "$REQUEST" \
  tokens.iam.api.nebius.cloud:443 \
  nebius.iam.v1.TokenExchangeService/Exchange)

TOKEN=$(jq -r '.accessToken' <<< $RESPONSE)

grpcurl -H "Authorization: Bearer $TOKEN" \
  cpl.iam.api.nebius.cloud:443 \
  nebius.iam.v1.ProfileService/Get

{
  "serviceAccountProfile": {
    "info": {
      "metadata": {
        "id": "serviceaccount-e00...",
        "parentId": "project-e00...",
        "name": "...",
        "createdAt": "..."
      },
      "spec": {},
      "status": {
        "active": true
      }
    }
  }
} 

SA_ID="serviceaccount-e00..."
KEY_ID="publickey-e00..."
PRIVATE_KEY_PATH="private_key.pem"

# https://github.com/mike-engel/jwt-cli
JWT=$(jwt encode \
  --alg RS256 \
  --kid $KEY_ID \
  --iss $SA_ID \
  --sub $SA_ID \
  --exp="$(date --date="+5minutes" +%s 2>/dev/null || date -v+5M +%s)" \
  --secret @${PRIVATE_KEY_PATH})

RESPONSE=$(curl https://auth.eu.nebius.com:443/oauth2/token/exchange \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "subject_token=${JWT}" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:jwt")

TOKEN=$(jq -r '.access_token' <<< $RESPONSE)

grpcurl -H "Authorization: Bearer $TOKEN" \
  cpl.iam.api.nebius.cloud:443 \
  nebius.iam.v1.ProfileService/Get

{
  "serviceAccountProfile": {
    "info": {
      "metadata": {
        "id": "serviceaccount-e00...",
        "parentId": "project-e00...",
        "name": "...",
        "createdAt": "..."
      },
      "spec": {},
      "status": {
        "active": true
      }
    }
  }
} 

Method Update and X-ResetMask Header

In Nebius AI Cloud API, the Update method is designed to perform a "full-replace" of resource fields rather than a "patch" operation. However, to maintain compatibility with clients of different versions, the server ensures that fields unknown to the client are not unintentionally modified. To achieve this, Nebius employs a mechanism called the Reset Mask.

Note: Nebius' Reset Mask is distinct from Google's Field Mask.

Behavior

A field in a protobuf message is not transmitted over the wire if it has a default value (empty string, 0, false, or NULL). The server updates a resource field only if:

• The request contains a non-default value for that field, or
• The field is explicitly included in the mask provided in the X-ResetMask header.

For example, to detach (remove) secondary disks from a compute instance, you can use the following X-ResetMask:

grpcurl -H "Authorization: Bearer $TOKEN" \
  -H "X-ResetMask: spec.secondary_disks" \
  -d '{"metadata": {"id": "compute-instance-id"}}' \
  compute.api.nebius.cloud:443 \
  nebius.compute.v1.InstanceService/Update

The Nebius SDK for all supported languages manages the X-ResetMask header automatically.

Reset Mask Syntax

A reset mask is a comma-separated list of elements, where each element specifies one or more fields in a protobuf message.

Example:

a, b.c, d.e.12, f.(j.h,i.j).k, l.*.m

The fields matched by the mask above are:

• a
• c within the structure b
• The 12th element in the list e within the structure d
• The field k within maps h and j (found in objects j and i, respectively, under the common ancestor f)
• All m fields from any direct child of l (e.g., l.q.m)

Lists and Maps

When modifying lists or maps, all elements of the container are included in the operation since the client can fully read and understand these structures, regardless of version differences.

• Lists:
  • Elements within the range 0...min(incoming.length, previous.length)-1 are updated individually, with each treated as part of the field mask.
  • Elements beyond this range are either removed or added.
• Maps:
  • Elements present in the incoming message are updated.
  • Missing elements are removed, while new elements are added.

Special Cases:

• To clear a list or map, add its name as a key in the reset mask.
• To modify or fully replace a list/map, include it in the request without specifying it in the reset mask.
• To remove specific values from objects in a list or map, include the object's index in the reset mask.

Nested Structures

If a reset mask targets a structure (e.g., a), it does not clear the contents of its fields unless those fields are explicitly included in the mask. However, if a field inside a structure is listed in the mask (e.g., a.b), the structure itself is reset if it is not present in the request payload.

Example:

• Resource: {a: {b:1, c:2}}
• Request: {} + X-ResetMask: a.b
• Result: {a: null} (the entire a structure is reset)

To preserve other fields in the structure, ensure the structure is explicitly included in the request:

• Resource: {a: {b:1, c:2}}
• Request: {a: {}} + X-ResetMask: a.b
• Result: {a: {c: 2}}

Operations

Most methods that modify data return a nebius.common.v1.Operation (operation.proto). This message can represent both synchronous and asynchronous operations. A synchronous operation is returned in a completed state, while an asynchronous one will update over time.

Status

An operation is considered complete when its status field is set. If the status field is null, the operation is still in progress. Completed operations also include a finished_at timestamp. If an error occurs, details will be provided in the status.details field, as explained in the Error Details section.

Parallel Operations

Nebius AI Cloud does not support concurrent operations on the same resource. Attempting multiple operations simultaneously on the same resource may result in an error, or the initial operation could be aborted in favor of the newer request.

Retention Policy

Ongoing operations are never deleted. Completed operations, however, may be deleted according to the retention policy of the service.

Error Details

Errors can occur either when an RPC method is called or when an asynchronous Operation completes unsuccessfully. In both cases, the google.rpc.Status message is used to describe the error. It may include additional details in the form of nebius.common.v1.ServiceError messages, providing more context about the issue.

A variety of ServiceError types can be returned (e.g. BadRequest, QuotaFailure, TooManyRequests). Refer to the complete list of possible error types in error.proto.

The ServiceError may also include a retry_type field, offering guidance on how to handle retries for the failed operation.

Idempotency

To ensure the idempotency of modifying operations in the Nebius AI Cloud API, you can use the X-Idempotency-Key header. Idempotency guarantees that the same operation will not be executed multiple times, even if the client retries the request due to network failures or timeouts. For read-only methods such as Get and List, the X-Idempotency-Key header is ignored.

The value of X-Idempotency-Key must be a sufficiently long string of random alphanumeric characters ([A-Za-z0-9-]), preferably a random-based UUID (e.g., 7f95c54a-ee0e-4f8c-a64c-c9e0aac605a0).

Example:

grpcurl -H "Authorization: Bearer $TOKEN" \
  -H "X-Idempotency-Key: 7f95c54a-ee0e-4f8c-a64c-c9e0aac605a0" \
  -d '{"metadata": {"id": "compute-instance-id"}, "spec": {"cpu": 4}}' \
  compute.api.nebius.cloud:443 \
  nebius.compute.v1.InstanceService/Update

A real-world program would:

1. Poll nebius.common.v1.OperationService/Get until the operation status is set.
2. Handle retries & errors based on ServiceError.retry_type.

Tip: The nebius crate exposes all services, so you can script the whole workflow – creating disks, subnets, firewalls, and so on – entirely in Rust.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Copyright (c) 2024 Nebius B.V.