Skip to main content

Start Deployment with Container Configuration

Endpoint Description​

POST /vendors/v1/machines/deployments/start

This endpoint initiates a deployment on a specified machine using a container configuration and SSH public keys. It requires authentication X-API-Key to access. The request must include the machine ID, SSH public keys, and container configuration details.

Request Body Description​

The request body for starting a deployment must be a JSON object containing the following fields:

Fields​

  • machine_id: string

    • The unique identifier for the machine where the deployment will occur.
    • Must be a non-empty string.

  • machine_price_id: string

    • The unique identifier for the machine price to be used for the deployment.
    • Must be a non-empty string.

  • external_deployment_id: string

    • The unique identifier provided by an external vendor to track the deployment status. It is required if the deployment_id returned by the API is lost after the deployment starts.
    • Optional field.

  • ssh_pub_keys: array of strings

    • A list of SSH public keys to be used for accessing the machine.
    • Optional field.

  • container_config: object

    • Configuration details for the container to be deployed.

    • Contains the following sub-fields:

    • image: string

      • The container image to be used.
      • Must be a non-empty string.

    • docker_auth: object

      • Authentication details for accessing private Docker registries.
      • server: string
        • The Docker registry server.
      • login: string
        • The login username for the Docker registry.
      • password: string
        • The password for the Docker registry.

    • ports: array of objects

      • A list of port mappings for the container.
      • Maximum 100 port mappings allowed.
      • Each port mapping contains:
        • host_port: integer
          • Port number on the host.
          • Must be between 1 and 65535.
        • protocol: string
          • Network protocol for the port.
          • Must not be unspecified.
          • Must be one of the following: PORT_PROTOCOL_TCP, PORT_PROTOCOL_HTTPS.

    • startup_script: string

      • A script to be executed when the container starts.

    • environment_variables: map<string, string>

      • Environment variables for the container, represented as key-value pairs.

  • metadata: object

    • Clore-specific data needed for integration.
    • Additional key-value pairs for other Clore-specific data.

Example Request Body​

json
{
  "machine_id": "24d71100-7532-11ef-bd52-3a629d609f79",
  "machine_price_id": "3b2772f0-7533-11ef-930e-3a629d609f79",
  "external_deployment_id": "e8ee1cb1-cad1-4d90-a69d-79097a9572c8",
  "ssh_pub_keys": [
    "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC..."
  ],
  "container_config": {
    "image": "nginx:latest",
    "docker_auth": {
      "server": "docker.private.io",
      "login": "username",
      "password": "password123"
    },
    "ports": [
      {
        "host_port": 80,
        "protocol": "PORT_PROTOCOL_TCP"
      },
      {
        "host_port": 443,
        "protocol": "PORT_PROTOCOL_HTTPS"
      }
    ],
    "startup_script": "echo 'Hello, World!' > /var/www/html/index.html",
    "environment_variables": {
      "ENV_VAR1": "value1",
      "ENV_VAR2": "value2"
    }
  },
  "metadata": {
    "additional_key": "additional_value"
  }
}

Success Response​

Status Code: 200 OK

Response Body Description​

The response body contains the deployment ID for the initiated deployment.

Fields​

  • deployment_id: string
    • The unique identifier for the deployment.

Example Response Body​

{
  "deployment_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv"
}

HTTP Status Codes​

The "Start Deployment" 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 deployment ID.
  • 400 Bad Request: The server could not understand the request due to invalid syntax. This status is typically returned if required fields are 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 machine 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 POST "https://api.hiveon.ai/vendors/v1/machines/deployments/start" \
  -H "Content-Type: application/json" \
  -H 'X-API-Key: <your_api_key>' \
  -d '{
    "machine_id": "24d71100-7532-11ef-bd52-3a629d609f79",
    "machine_price_id": "3b2772f0-7533-11ef-930e-3a629d609f79",
    "external_deployment_id": "e8ee1cb1-cad1-4d90-a69d-79097a9572c8",
    "ssh_pub_keys": [
      "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC..."
    ],
    "container_config": {
      "image": "nginx:latest",
      "docker_auth": {
        "server": "docker.private.io",
        "login": "username",
        "password": "password123"
      },
      "ports": [
        {
          "host_port": 80,
          "protocol": "PORT_PROTOCOL_TCP"
        },
        {
          "host_port": 443,
          "protocol": "PORT_PROTOCOL_HTTPS"
        }
      ],
      "startup_script": "echo 'Hello, World!' > /var/www/html/index.html",
      "environment_variables": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      }
    },
    "metadata": {
      "additional_key": "additional_value"
    }
  }'

This cURL command initiates a deployment on a specified machine, using the provided machine ID, SSH public keys, and container configuration.