Attach Volume to Instance

This endpoint attaches a persistent storage volume to a running X-Series GPU virtual machine instance using their respective Volume ID and Instance ID.

Attach Volume to Instance - Overview

The X-Series Volume Attachment API allows authenticated users to attach an existing block storage volume to a specific GPU virtual machine using the volume ID and instance ID.

This endpoint is useful for expanding instance storage, connecting previously created volumes, and automating storage management workflows through the Dataoorts API.

When a volume is attached successfully, the API returns a confirmation message indicating that the volume has been attached to the specified instance.

Important Note: A volume can only be attached to a GPU instance located in the same region. Before submitting the request, ensure that the volume and the target instance belong to the same region.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/xseries/volumes/attach
Full URL	https://cloud.dataoorts.com/api/v1/xseries/volumes/attach
Authentication	Bearer Token
Content Type	application/json
Response Format	JSON

Authentication

This endpoint requires a valid Dataoorts Unify API key.

Include your API key in the Authorization header using the Bearer authentication scheme.

HTTP

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Generate or manage your API key through the Dataoorts Unify API.

Keep your API key confidential and never expose it in public repositories or client-side applications.

Request Parameters

The request body must be sent as JSON.

Parameter	Type	Required	Description
volume_id	Integer or String	Yes	The ID of the existing volume you want to attach to the instance.
instance_id	Integer	Yes	The ID of the GPU virtual machine to which the volume will be attached.

Provide valid identifiers for both the volume and the target instance. Ensure that the volume exists and that the selected instance is in the same region as the volume.

Request Examples

cURL - Use the following command to attach a volume to a GPU instance:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/xseries/volumes/attach" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "volume_id": 29161,
    "instance_id": 1392
  }'

Replace YOUR_API_KEY, volume_id, and instance_id with your actual values.

---

Python Example Implementation

Python

import os
import requests


API_URL = (
    "https://cloud.dataoorts.com"
    "/api/v1/xseries/volumes/attach"
)


def attach_xseries_volume(
    api_key: str,
    volume_id: int,
    instance_id: int,
) -> dict:
    """
    Attach an existing X-Series volume to a GPU instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        volume_id: The ID of the volume to attach.
        instance_id: The ID of the target GPU instance.

    Returns:
        dict: The JSON response returned by the API.

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the response cannot be decoded as JSON.
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "volume_id": volume_id,
        "instance_id": instance_id,
    }

    response = requests.post(
        API_URL,
        headers=headers,
        json=payload,
        timeout=60,
    )

    response.raise_for_status()

    try:
        return response.json()
    except requests.exceptions.JSONDecodeError as exc:
        raise ValueError(
            "The API returned an invalid JSON response."
        ) from exc


if __name__ == "__main__":
    api_key = os.getenv("DATAOORTS_API_KEY")

    if not api_key:
        raise RuntimeError(
            "Set the DATAOORTS_API_KEY environment variable."
        )

    try:
        result = attach_xseries_volume(
            api_key=api_key,
            volume_id=29161,
            instance_id=1392,
        )

        print("Status:", result.get("status"))
        print("Message:", result.get("message"))

    except requests.exceptions.RequestException as exc:
        print(f"API request failed: {exc}.")

    except ValueError as exc:
        print(f"Invalid API response: {exc}.")

Set your API key before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python attach_volume.py

Windows PowerShell

PowerShell

$env:DATAOORTS_API_KEY="YOUR_API_KEY"
python attach_volume.py

The script submits attachment request and displays the status and confirmation message returned by the API.

Example Success Response

When a volume is attached successfully, the API returns a JSON response similar to the following:

JSON

{
  "message": "Volume 29161 successfully attached to instance 1392.",
  "status": "success"
}

The volume ID, instance ID, and message will reflect the actual request.

Response Fields

Field	Type	Description
status	String	Indicates result of the API request. A successful response returns success.
message	String	Descriptive message confirming that volume was attached to specified vm.

Understanding the Volume Attachment Process

After submitting the request:

1. Dataoorts processes volume attachment request using supplied volume ID and instance ID.
2. The service validates and processes the requested attachment.
3. If the operation succeeds, the API returns a confirmation message.
4. You can use the List All Volumes endpoint to retrieve volume information and review the reported attachment details.

Important: A successful API response confirms the attachment operation reported by the API. It does not necessarily confirm that the volume has been mounted inside the instance's operating system or is ready for immediate use.

Important Notes

1. Region Compatibility: A volume can only be attached to a GPU instance located in the same region. Verify regional compatibility before submitting the request.

2. Valid Identifiers: Provide the correct volume_id and instance_id. Incorrect identifiers may prevent the operation from succeeding.

3. Existing Volumes: This endpoint attaches an existing volume. Create the volume first using the Create a Volume endpoint if you do not already have one.

4. Verify Attachment Status: After the request succeeds, retrieve the volume list to review the attachment information reported by the API.

5. Handle Request Timeouts Carefully: If the request times out or returns an error, check the volume's attachment information before retrying to avoid unnecessary repeated requests.

Error Handling

If request fails, API may return unsuccessful HTTP status code and JSON response containing an error message.

Your application should handle authentication failures, invalid volume or instance IDs, region compatibility issues, network errors, timeouts, and unexpected response formats. The exact error codes and response messages depend on the API response.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. Do not assume that every response contains the same fields as the successful response shown above.

Get Help and Support

For assistance with volume attachment, region compatibility, or API integration, contact the Dataoorts support team at [email protected].