Hibernate an Instance

This endpoint initiates the hibernation process for an active Nova Series GPU virtual machine instance using its unique Instance ID.

Hibernate an Instance - Overview

The Nova Series Hibernate API allows authenticated users to hibernate or stop a running Nova virtual machine using its instance ID.

This endpoint is useful for managing instance lifecycles and temporarily stopping instances that are no longer required for active workloads. It can be integrated into automation scripts, infrastructure management tools, and custom applications.

When the hibernation request succeeds, the API returns a confirmation message and the instance status reported by the service.

Important Note: Hibernating an instance may interrupt running applications, active connections, and workloads. Ensure that the instance can safely be stopped before submitting the request.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/nova/hibernate
Full URL	https://cloud.dataoorts.com/api/v1/nova/hibernate
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
instance_id	Integer	Yes	The ID of the Nova instance you want to hibernate.

Provide the ID of the intended instance and verify the identifier before submitting the request.

Request Examples

cURL - Use the following command to hibernate a Nova instance:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/nova/hibernate" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_id": 430
  }'

Replace YOUR_API_KEY and the example instance ID with your actual values.

Python Example Implementation

The following example uses the requests library to submit a hibernation request and display the response returned by the API.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


API_URL = "https://cloud.dataoorts.com/api/v1/nova/hibernate"


def hibernate_nova_instance(
    api_key: str,
    instance_id: int,
) -> dict:
    """
    Hibernate or stop a running Nova instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        instance_id: The ID of the instance to hibernate.

    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 = {
        "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 = hibernate_nova_instance(
            api_key=api_key,
            instance_id=430,
        )

        print("Status:", result.get("status"))
        print("Current Status:", result.get("current_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 hibernate_instance.py

Windows PowerShell

PowerShell

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

Replace 430 with the ID of the Nova instance you want to hibernate.

Example Success Response

When the hibernation request succeeds, the API returns a JSON response similar to the following:

JSON

{
  "current_status": "stopped",
  "message": "Instance hibernation initiated successfully.",
  "status": "success"
}

The returned values reflect the result reported by the API.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success.
current_status	String	The instance status reported by the API after the hibernation request. The example response returns stopped.
message	String	A descriptive message confirming that the hibernation process was initiated successfully.

Understanding the Hibernation Process

A successful response indicates that the API reports the hibernation request as initiated. It does not necessarily mean that every aspect of the instance shutdown process has completed.

After submitting the request:

1. Dataoorts processes the hibernation request for the specified instance.
2. The instance transitions toward a Stopped or Hibernated State.
3. The API returns the operation status and a confirmation message.
4. You can retrieve the latest instance information to check the state reported by the service.

Important Notes

1. Correct Instance ID: Verify the instance_id before submitting the request to ensure that the intended instance is hibernated.

2. Workload Interruption: Hibernating an instance may interrupt running applications, active sessions, and network connections. Plan the operation accordingly.

3. Instance Status: The example response reports current_status as stopped. Treat this as the status returned by the API rather than assuming that all shutdown operations have completed.

4. Hibernation vs. Termination: Hibernation or stopping an instance is different from permanently terminating it. Use the appropriate lifecycle operation for your intended outcome.

5. Handling Timeouts: If the request times out or returns an error, the hibernation operation may still have been initiated. Check the instance state before submitting another request.

Error Handling

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

Your application should handle authentication failures, invalid instance IDs, network errors, request timeouts, server errors, 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 Nova instance hibernation or API integration, contact the Dataoorts support team at [email protected].