Skip to main content

Get Deployment Status by External ID

Endpoint Description​

GET /vendors/v1/machines/deployments/{external_deployment_id}

This endpoint retrieves the status of a container deployment on a specified machine using an external_deployment_id. It is designed to support external vendors who provide their own deployment identifiers. When initiating deployment in StartDeployment endpoint, vendors can specify an external_deployment_id, which is stored in the system. If the vendor later loses the internally assigned deployment_id, they can use their external_deployment_id to retrieve the deployment status. This endpoint requires authentication X-API-Key to access.

Request Parameters​

The request parameters for getting the deployment status must be specified in the URL path.

Parameters​

  • external_deployment_id: string
    • The unique identifier for the deployment, provided by the vendor during deployment start, used to request the deployment status.

Example Request​

GET /vendors/v1/machines/deployments/a1b2c3d4-5678-90ef-ghij-klmnopqrstuv

Success Response​

Status Code: 200 OK

Response Body Description​

The response body contains information about the status of the container deployment.

Fields​

  • deployment_id: string
    • The unique identifier for the deployment.
  • machine_id: string
    • The unique identifier for the machine on which the container is running.
  • external_deployment_id: string
    • The unique identifier for the deployment in the external system, provided during deployment start endpoint execution.
  • status: enum
    • The current status of the container.
    • Possible values:
      • STATUS_UNSPECIFIED: The status is unspecified.
      • STATUS_PENDING: The container has been scheduled and is waiting to be processed.
      • STATUS_STOPPING: The container is in the process of stopping.
      • STATUS_STOPPED: The container has been stopped.
      • STATUS_FAILED: The container operation encountered an error and failed.
      • STATUS_RUNNING: The container is running.
  • fail_reason: object
    • The reason for failure, if any.
    • code: int
      • The error code associated with the failure.
    • message: string
      • A descriptive message about the failure.
  • metadata: map<string, string>
    • Additional metadata about the deployment, represented as key-value pairs.
  • connection_info: object
    • Information about how to connect to the deployment.
    • ssh: object
      • SSH connection details.
      • direct: string
        • Direct SSH command to access the machine.
      • proxy: string
        • SSH command using a proxy to access the machine.
    • port_forwarding: object
      • Port forwarding details.
      • public: map<string, string>
        • Publicly accessible ports mapped to internal ports.
      • proxy: map<string, string>
        • Proxy-accessible ports mapped to internal ports.

Example Response Body​

{
  "deployment_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
  "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
  "external_deployment_id": "9f452b36-7f41-432c-accf-15699b7ca591",
  "status": "STATUS_RUNNING",
  "fail_reason": {
    "code": 0,
    "message": "string"
  },
  "metadata": {
    "example_key": "example_value"
  },
  "connection_info": {
    "ssh": {
      "direct": "ssh [email protected] -p 2222",
      "proxy": "ssh [email protected] p p 2233"
    },
    "port_forwarding": {
      "public": {
        "80": "10.10.10.10:2415",
        "443": "10.10.10.10:2416"
      },
      "proxy": {
        "80": "proxy1.hiveon.ai:3415",
        "443": "proxy1.hiveon.ai:3416"
      }
    }
  }
}

HTTP Status Codes​

The "Get Deployment Status" endpoint may return the following HTTP status codes based on the outcome of the request:

  • 200 OK: The request was successful, and the response body contains the status of the deployment.
  • 400 Bad Request: The server could not understand the request due to invalid syntax. This status is typically returned if the required parameter is missing or incorrectly formatted.
  • 401 Unauthorized: The request lacks valid authentication credentials for the target resource. This status indicates that the client must authenticate themselves to get the requested response.
  • 403 Forbidden: The server understood the request but refuses to authorize it. This typically means the requester doesn't have the required roles to access the resource.
  • 404 Not Found: The requested resource could not be found. This status may be returned if the deployment ID is incorrect.
  • 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request. This is a generic error message when no specific message is suitable.

Example cURL Request​

curl -X GET "https://api.hiveon.ai/vendors/v1/machines/deployments/a1b2c3d4-5678-90ef-ghij-klmnopqrstuv" \
     -H "Accept: application/json" \
     -H 'X-API-Key: <your_api_key>'

This cURL command retrieves the status of the container deployment on a specified machine, using the provided deployment ID.