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 and specific user roles 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.

  • ssh_pub_keys: array of strings

    • A list of SSH public keys to be used for accessing the machine.
    • Each key must be a non-empty string.

  • 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 integers

      • A list of ports to be exposed by the container.
      • Each port must be a valid integer representing a network port.

    • startup_script: string

      • A script to be executed when the container starts.
      • This script can be used to perform initialization tasks or configure the container environment.

    • environment_variables: map<string, string>

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

  • metadata: object

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

Example Request Body​

{
  "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
  "ssh_pub_keys": ["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC..."],
  "container_config": {
    "image": "nginx:latest",
    "docker_auth": {
      "server": "docker.private.io",
      "login": "",
      "password": ""
    },
    "ports": [80, 443],
    "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 "Authorization: Bearer <your_jwt_token>" \
     -d '{
           "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
           "ssh_pub_keys": ["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC..."],
           "container_config": {
             "image": "nginx:latest",
             "docker_auth": {
               "server": "docker.private.io",
               "login": "",
               "password": ""
             },
             "ports": [80, 443],
             "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.