Hibernate an Instance

This endpoint hibernates an active Z-Series enterprise GPU virtual machine, pausing active compute usage while preserving your data state.

Hibernate an Instance - Overview

The Z-Series Hibernate Instance API allows authenticated users to hibernate an active Z-Series GPU virtual machine associated with their Dataoorts account.

The endpoint accepts an instance_id that identifies the virtual machine using either its local instance ID or provider VID. Before hibernation, the API automatically settles any outstanding compute charges and then sends a request to the provider to pause the virtual machine.

After successful hibernation, the instance status becomes Hibernated, and its stored SSH command is replaced with N/A (Hibernated).

Important: Only virtual machines in the Active state can be hibernated. The local Instance ID remains unchanged when the VM resumes, whereas the Provider VID resets with every restart.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/zseries/stop
Full URL	https://cloud.dataoorts.com/api/v1/zseries/stop
Authentication	Bearer Token
Request Format	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 endpoint requires a JSON request body containing the identifier of the Z-Series virtual machine to hibernate.

Parameter	Type	Required	Description
instance_id	String or Integer	Yes	The local Instance ID or DC Provider VID of the virtual machine to hibernate.

Example Request Body — Local Instance ID

JSON

{
  "instance_id": 205
}

Example Request Body — DC Provider VID

JSON

{
  "instance_id": "56982"
}

Replace example value with local Instance ID or DC Provider VID of the virtual machine you want to hibernate.

Request Examples

cURL - Use the following command to hibernate a Z-Series virtual machine using its local instance ID:

Bash

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

To identify the virtual machine using its DC Provider VID, provide that identifier as the instance_id value:

Bash

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

Replace YOUR_API_KEY with your actual API key and provide the identifier of the intended virtual machine.

Python Example Implementation

The following example uses the requests library to hibernate a Z-Series virtual machine. It reads the API key from an environment variable, handles unsuccessful HTTP responses, and checks the response format before processing the returned data.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


API_URL = "https://cloud.dataoorts.com/api/v1/zseries/stop"


def hibernate_zseries_instance(
    api_key: str,
    instance_id: int | str,
) -> dict | None:
    """
    Hibernate an active Z-Series GPU virtual machine.

    Args:
        api_key: Your Dataoorts Unify API key.
        instance_id: The local Instance ID or Provider VID.

    Returns:
        The JSON response containing the hibernation result,
        or None if the API returns a non-JSON response.

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the response contains invalid 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=180,
    )

    response.raise_for_status()

    content_type = response.headers.get("Content-Type", "")

    if "application/json" not in content_type.lower():
        print("Non-JSON response received:")
        print(response.text[:500])
        return None

    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_zseries_instance(
            api_key=api_key,
            instance_id=19,
        )

        if result is not None:
            print("Status:", result.get("status"))
            print("Message:", result.get("message"))
            print("Current Status:", result.get("current_status"))

    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 in your Env before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python zseries_hibernate.py

Windows PowerShell

PowerShell

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

The script submits the instance identifier and displays the returned status, message, and current instance status when a valid JSON response is received.

Example Success Response

A successful request returns a JSON object containing the current instance status, a descriptive message, and the response status.

JSON

{
  "current_status": "Hibernated",
  "message": "Instance 19 hibernated successfully.",
  "status": "success"
}

The instance identifier and response message may differ depending on the virtual machine being hibernated.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success; an unsuccessful response returns error.
message	String	A descriptive message confirming the hibernation result.
current_status	String	Instance status retured after operation. Example return Hibernated.

Understanding Instance Information

Instance Identification

The instance_id parameter identifies the Z-Series virtual machine targeted by the request.

You can provide either local Instance ID or DC Provider VID. Identifier is submitted in the JSON request body.

Hibernation Process

Before hibernation, the API automatically settles any outstanding compute charges. It then sends the request to the provider to pause the virtual machine. When the operation succeeds, the response returns current_status as Hibernated.

Instance Status Requirements

The virtual machine must be in the Active state before hibernation can be initiated. If the virtual machine is already hibernated or is in another unsupported state, the API may return an invalid VM state error.

Connection Information

After hibernation, the stored SSH command is replaced with N/A (Hibernated). Check the latest instance information before attempting to connect to the virtual machine.

Instance ID and Provider VID

The local Instance ID remains unchanged when the virtual machine resumes from hibernation. The DC Provider VID resets with every restart. Retain the local Instance ID when tracking the virtual machine across restarts, and retrieve the latest instance information when the current DC Provider VID is needed.

Hibernation Process Workflow

The Z-Series hibernation process follows these steps:

1. Authenticate using your Dataoorts Unify API key.
2. Identify the virtual machine using its local Instance ID or DC Provider VID.
3. Submit a POST request to /api/v1/zseries/stop.
4. The API validates instance ownership and ensures that the virtual machine is in the Active state.
5. The API calculates and settles any outstanding compute charges.
6. The API sends the hibernation request to the provider.
7. After successful hibernation, the instance status becomes Hibernated and the stored SSH command is replaced with N/A (Hibernated).
8. Use the corresponding Resume/Start endpoint to resume the virtual machine when needed.

Important Notes

1. Active State Required: Only virtual machines in the Active state can be hibernated.

2. Instance Identifier: Provide either Local Instance ID or DC Provider VID through the instance_id param.

3. Outstanding Charges: Outstanding compute charges are automatically settled before hibernation.

4. Connection Information: After hibernation, the stored SSH command is replaced with N/A (Hibernated).

5. Instance ID: The local Instance ID remains unchanged when the virtual machine resumes from hibernation.

6. Provider VID: The Provider VID resets with every restart. Retrieve the latest instance information when the current provider identifier is required.

7. Resuming the VM: The VM can later be resumed using the corresponding Restart endpoint.

8. Compute Usage: Hibernation preserves the VM state while stopping active GPU compute usage.

9. Request Timeout: The Python example uses a timeout of 180 seconds. If the request times out, check the latest instance status before retrying because the outcome of the original request may be uncertain.

10. API Key Security: Keep your API key confidential and store it in the DATAOORTS_API_KEY environment variable rather than hardcoding it in your application.

Error Handling

The API may return an unsuccessful HTTP status code and a JSON error response when a hibernation request cannot be completed.

Your application should handle authentication failures, missing instance identifiers, invalid VM states, instances that cannot be found or accessed, provider errors, server errors, and unexpected response formats.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. The example also checks the response content type and handles JSON decoding errors before processing the Z Series GPU virtual machine hibernation result.

Missing API Key

HTTP Status: 401 Unauthorized

JSON

{
  "status": "error",
  "message": "Authorization header with 'Bearer <TOKEN>' is required."
}

Include the Authorization header with a valid Bearer token.

Missing Token

HTTP Status: 401 Unauthorized

JSON

{
  "status": "error",
  "message": "API Token is missing or empty."
}

Ensure that the API token is present and non-empty.

Invalid API Key

HTTP Status: 403 Forbidden

JSON

{
  "status": "error",
  "message": "Unauthorized: Invalid API key."
}

Verify that your Dataoorts API key is valid and included in the request header.

Invalid JSON

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Invalid JSON payload."
}

Ensure that the request body contains valid JSON.

Missing Instance ID

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Missing required field: 'instance_id'."
}

Provide the required instance_id field in the JSON request body.

Invalid VM State

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Invalid VM state: Hibernated."
}

This error is returned when the virtual machine is not currently in the Active state. Check the latest instance status before submitting the GPU Instance Hibernation request.

Instance Not Found

HTTP Status: 404 Not Found

JSON

{
  "status": "error",
  "message": "Z-Series instance not found or access denied."
}

Verify that the instance identifier is correct and that the virtual machine belongs to the authenticated user.

DC Provider Error

HTTP Status: 502 Bad Gateway

JSON

{
  "status": "error",
  "message": "DC Provider failed to hibernate instance, Please try again."
}

This response indicates that the provider could not hibernate the instance. Check the instance status and try again if appropriate.

Internal Server Error

HTTP Status: 500 Internal Server Error

JSON

{
  "status": "error",
  "message": "Internal Server Error, Please Contact Support."
}

If the error persists, contact the Dataoorts support team at [email protected] for assistance.

General Error Handling

Scenario	Recommended Handling
API key is missing	Include Authorization header with a valid Bearer token.
API token is empty	Set a non-empty DATAOORTS_API_KEY env variable.
API key is invalid	Verify the API key through the Dataoorts platform.
Request body is invalid	Send a valid JSON object containing instance_id.
Instance ID is missing	Provide the required instance_id field.
VM is not in the Active state	Check current VM status before attempting hibernation.
Instance is not found or access is denied	Verify the identifier and confirm that the VM belongs to the authenticated user.
Provider returns 502	Check the instance status and retry if appropriate.
Request times out	Retrieve the latest instance status before retrying.
Response is not JSON	Inspect the returned response text without attempting to parse it as JSON.
Response contains invalid JSON	Handle the JSON decoding error before accessing response fields.

Get Help and Support

For assistance with Z-Series VM hibernation or API integration, Contact support team at [email protected].