runner/docs/shim.openapi.yaml
Rama master · réplica de lectura del repositorio original.
openapi: 3.1.2
info:
title: dstack-shim API
version: v2/0.21.0
x-logo:
url: https://avatars.githubusercontent.com/u/54146142?s=260
description: >
## Versioning
`dstack-shim` versioning and release cycles are tied to those of `dstack`, meaning that we
cannot use shim version to express shim API versioning. To get around this limitation, we use
two version schemes:
* shim binary version, the same as the server version, in the form of `MAJOR.MINOR.MICRO`, e.g,
`0.18.33`. This version is exposed via the `/healthcheck` endpoint. Used to discriminate
different API versions (`if shim_version >= x.y.z then api_version = 2 else api_version = 1`)
and detect features within one API version (`if shim_version >= x.y.z then has_x_feature = true`)
* shim API version (you can think of it as a “generation”), in the form or `vN`, e.g., `v2`.
Diferrent API versions represent _totally different_ APIs. When two such API versions coexist
in the same shim binary (naturally, they should coexist for some time to ensure seamless migration),
we call the older one “Legacy API” and the newer one “Future API”. These versions are not exposed
via API, clients should figure out them via shim binary version
servers:
- url: http://localhost:10998/api
paths:
/healthcheck:
get:
summary: Ping and API version negotiation
description: >
Serves two roles:
* as the path implies, it's a healthcheck, although there is no field in the response that
indicate if shim is healthy. Basically, it not is a proper healthcheck but
a basic "ping" method
* API version negotiation. Server inspects `version` field to figure out which API features
it should use
**Important**: Since this endpoint is used for negotiation, it should always stay
backward/future compatible, specifically the `version` field
tags: [shim]
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/HealthcheckResponse"
/shutdown:
post:
summary: Request shim shutdown
description: |
(since [0.20.1](https://github.com/dstackai/dstack/releases/tag/0.20.1)) Request shim to shut down itself.
Restart must be handled by an external process supervisor, e.g., `systemd`.
**Note**: background jobs (e.g., component installation) are canceled regardless of the `force` option.
tags: [shim]
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ShutdownRequest"
responses:
"200":
description: Request accepted
$ref: "#/components/responses/PlainTextOk"
"400":
description: Malformed JSON body or validation error
$ref: "#/components/responses/PlainTextBadRequest"
/instance/health:
get:
summary: Get instance health
description: (since [0.19.22](https://github.com/dstackai/dstack/releases/tag/0.19.22)) Returns an object of optional passive system checks
tags: [Instance]
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/InstanceHealthResponse"
/instance/info:
get:
summary: Get instance info
description: >
(since [0.21.0](https://github.com/dstackai/dstack/releases/tag/0.21.0))
Returns facts about the host observed by shim, e.g., the GPU driver version.
Unlike `/components`, the reported entities are not managed by shim.
tags: [Instance]
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/InstanceInfoResponse"
/components:
get:
summary: Get components
description: (since [0.20.0](https://github.com/dstackai/dstack/releases/tag/0.20.0)) Returns a list of software components (e.g., `dstack-runner`)
tags: [Components]
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/ComponentListResponse"
/components/install:
post:
summary: Install component
description: >
(since [0.20.0](https://github.com/dstackai/dstack/releases/tag/0.20.0)) Request installing/updating the software component.
Components are installed asynchronously
tags: [Components]
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ComponentInstallRequest"
responses:
"200":
description: Request accepted
$ref: "#/components/responses/PlainTextOk"
"400":
description: Malformed JSON body or validation error
$ref: "#/components/responses/PlainTextBadRequest"
"409":
description: The component is already being installed
$ref: "#/components/responses/PlainTextConflict"
/tasks:
get:
summary: Get task list
description: Returns a list of all tasks known to shim, including terminated ones
tags: [Tasks]
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/TaskListResponse"
post:
summary: Submit and run new task
tags: [Tasks]
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TaskSubmitRequest"
responses:
"200":
description: Pending task info
$ref: "#/components/responses/TaskInfo"
"400":
description: Malformed JSON body or validation error
$ref: "#/components/responses/PlainTextBadRequest"
"409":
description: Task with the same ID already submitted
$ref: "#/components/responses/PlainTextConflict"
"500":
description: Internal error
$ref: "#/components/responses/PlainTextInternalError"
/tasks/{id}:
get:
summary: Get task info
tags: [Tasks]
parameters:
- $ref: "#/components/parameters/taskId"
responses:
"200":
$ref: "#/components/responses/TaskInfo"
"404":
description: Task not found
$ref: "#/components/responses/PlainTextNotFound"
/tasks/{id}/terminate:
post:
summary: Terminate task
description: >
Stops the task, that is, cancels image pulling if in progress,
stops the container if running, and sets the status to `terminated`.
No-op if the task is already terminated
tags: [Tasks]
parameters:
- in: path
name: id
schema:
$ref: "#/components/schemas/TaskID"
required: true
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TaskTerminateRequest"
responses:
"200":
description: Updated task info
$ref: "#/components/responses/TaskInfo"
"404":
description: Task not found
$ref: "#/components/responses/PlainTextNotFound"
"500":
description: Internal error, e.g., failed to remove a container
$ref: "#/components/responses/PlainTextInternalError"
/tasks/{id}/remove:
post:
summary: Remove task
description: >
Removes the task from in-memory storage and destroys its associated
resources: a container, logs, etc.
tags: [Tasks]
parameters:
- $ref: "#/components/parameters/taskId"
responses:
"200":
description: Task removed
$ref: "#/components/responses/PlainTextOk"
"404":
description: Task not found
$ref: "#/components/responses/PlainTextNotFound"
"409":
description: Task is not terminated, cannot remove
$ref: "#/components/responses/PlainTextConflict"
"500":
description: Internal error, e.g., failed to remove a container
$ref: "#/components/responses/PlainTextInternalError"
components:
parameters:
taskId:
name: id
in: path
schema:
$ref: "#/components/schemas/TaskID"
required: true
schemas:
TaskID:
description: Unique task ID assigned by dstack server
type: string
examples:
- 23a2c7a0-6c88-48ee-8028-b9ad9f6f5c24
TaskStatus:
title: shim.TaskStatus
type: string
enum:
- pending
- preparing
- pulling
- creating
- running
- terminated
TerminationReason:
type: string
enum:
- executor_error
- creating_container_error
- container_exited_with_error
- done_by_runner
- terminated_by_user
- terminated_by_server
- max_duration_exceeded
GpuID:
description: >
A vendor-specific unique identifier of GPU:
* NVIDIA: "globally unique immutable alphanumeric identifier of the GPU",
in the form of `GPU-<UUID>`
* AMD: `/dev/dri/renderD<N>` path
type: string
examples:
- GPU-2b79666e-d81f-f3f8-fd47-9903f118c3f5
- /dev/dri/renderD128
NetworkMode:
title: shim.NetworkMode
type: string
enum:
- host
- bridge
PortMapping:
title: shim.PortMapping
description: Task host:container port mapping pair
type: object
properties:
host:
type: integer
description: host port
examples:
- 32770
container:
type: integer
description: container port
examples:
- 80
required:
- host
- container
additionalProperties: false
VolumeInfo:
title: shim.VolumeInfo
type: object
properties:
backend:
type: string
enum: [aws, gcp]
name:
type: string
default: ""
description: >
`dstack` volume [name](https://dstack.ai/docs/reference/dstack.yml/volume/#name)
volume_id:
type: string
default: ""
init_fs:
type: boolean
default: false
description: >
Create a filesystem when it doesn't exist if `true`, fail with error if `false`
VolumeMountPoint:
title: shim.VolumeMountPoint
type: object
properties:
name:
type: string
default: ""
description: >
`dstack` volume [name](https://dstack.ai/docs/reference/dstack.yml/volume/#name)
path:
type: string
default: ""
description: Mount point inside container
InstanceMountPoint:
title: shim.InstanceMountPoint
type: object
properties:
instance_name:
type: string
default: ""
description: Instance (host) path
path:
type: string
default: ""
description: Mount point inside container
GPUDevice:
title: shim.GPUDevice
type: object
properties:
path_on_host:
type: string
default: ""
description: Instance (host) path
path_in_container:
type: string
default: ""
description: Path inside container
DCGMHealth:
title: shim.dcgm.Health
type: object
properties:
overall_health:
type: integer
description: >
[dcgmHealthWatchResult_enum](https://docs.nvidia.com/datacenter/dcgm/latest/dcgm-api/dcgm-api-data-structs.html#_CPPv426dcgmHealthWatchResult_enum)
examples:
- 10
incidents:
type: array
items:
$ref: "#/components/schemas/DCGMHealthIncident"
required:
- overall_health
- incidents
additionalProperties: false
DCGMHealthIncident:
title: shim.dcgm.HealthIncident
type: object
properties:
system:
type: integer
description: >
[dcgmHealthSystems_enum](https://docs.nvidia.com/datacenter/dcgm/latest/dcgm-api/dcgm-api-data-structs.html#_CPPv422dcgmHealthSystems_enum)
examples:
- 1
health:
type: integer
description: >
[dcgmHealthWatchResult_enum](https://docs.nvidia.com/datacenter/dcgm/latest/dcgm-api/dcgm-api-data-structs.html#_CPPv426dcgmHealthWatchResult_enum)
examples:
- 10
error_message:
type: string
examples:
- >
Detected more than 16 PCIe replays per minute for GPU 0 : 99 Reconnect PCIe card.
Run system side PCIE diagnostic utilities to verify hops off the GPU board. If issue is on the board, run the field diagnostic.
error_code:
type: integer
description: >
[dcgmError_enum](https://github.com/NVIDIA/DCGM/blob/master/dcgmlib/dcgm_errors.h)
examples:
- 3
entity_group_id:
type: integer
description: >
[dcgm_field_entity_group_t](https://docs.nvidia.com/datacenter/dcgm/latest/dcgm-api/dcgm-api-field-entity.html#_CPPv425dcgm_field_entity_group_t)
examples:
- 1
entity_id:
type: integer
examples:
- 0
required:
- system
- health
- error_message
- error_code
- entity_group_id
- entity_id
additionalProperties: false
ComponentName:
title: shim.components.ComponentName
type: string
enum:
- dstack-runner
- dstack-shim
description: |
* (since [0.20.0](https://github.com/dstackai/dstack/releases/tag/0.20.0)) `dstack-runner`
* (since [0.20.1](https://github.com/dstackai/dstack/releases/tag/0.20.1)) `dstack-shim`
ComponentStatus:
title: shim.components.ComponentStatus
type: string
enum:
- not-installed
- installed
- installing
- error
ComponentInfo:
title: shim.components.ComponenInfo
type: object
properties:
name:
$ref: "#/components/schemas/ComponentName"
version:
type: string
description: An empty string if status != installed
examples:
- 0.20.1
status:
allOf:
- $ref: "#/components/schemas/ComponentStatus"
- examples:
- installed
required:
- name
- version
- status
additionalProperties: false
HealthcheckResponse:
title: shim.api.HealthcheckResponse
type: object
properties:
service:
const: dstack-shim
version:
type: string
examples:
- 0.18.34
required:
- service
- version
additionalProperties: false
ShutdownRequest:
title: shim.api.ShutdownRequest
type: object
properties:
force:
type: boolean
examples:
- false
description: If `true`, don't wait for background job coroutines to complete after canceling them and close HTTP server forcefully.
required:
- force
InstanceHealthResponse:
title: shim.api.InstanceHealthResponse
type: object
properties:
dcgm:
$ref: "#/components/schemas/DCGMHealth"
additionalProperties: false
InstanceInfoResponse:
title: shim.api.InstanceInfoResponse
type: object
properties:
gpu_vendor:
description: Host GPU vendor. Omitted on hosts without GPUs.
type: string
examples:
- nvidia
gpu_driver_version:
description: >
Host GPU driver version. Omitted on hosts without GPUs
or if detection failed.
type: string
examples:
- 570.86.15
additionalProperties: false
ComponentListResponse:
title: shim.api.ComponentListResponse
type: object
properties:
components:
type: array
items:
$ref: "#/components/schemas/ComponentInfo"
required:
- components
additionalProperties: false
ComponentInstallRequest:
title: shim.api.ComponentInstallRequest
type: object
properties:
name:
$ref: "#/components/schemas/ComponentName"
url:
type: string
examples:
- https://dstack-runner-downloads.s3.eu-west-1.amazonaws.com/0.20.1/binaries/dstack-runner-linux-amd64
required:
- name
- url
TaskListResponse:
title: shim.api.TaskListResponse
type: object
properties:
tasks:
type: array
items:
type: object
properties:
id:
$ref: "#/components/schemas/TaskID"
status:
$ref: "#/components/schemas/TaskStatus"
required:
- id
- status
description: A list of all tasks tracked by shim, each with its ID and status
required:
- tasks
additionalProperties: false
TaskInfoResponse:
title: shim.api.TaskInfoResponse
description: Same as `shim.TaskInfo`
type: object
properties:
id:
$ref: "#/components/schemas/TaskID"
status:
allOf:
- $ref: "#/components/schemas/TaskStatus"
- examples:
- terminated
termination_reason:
$ref: "#/components/schemas/TerminationReason"
termination_message:
type: string
description: A shim-generated message or N last lines from the container logs
ports:
oneOf:
- type: array
items:
$ref: "#/components/schemas/PortMapping"
- type: "null"
description: >
A host:container port mapping or `null` if this information is not yet available.
In the `host` network mode the array is empty (or `null` if is not ready yet, see above).
container_name:
type: string
examples:
- horrible-mule-1-0-0-44f7cb95
container_id:
type: string
examples:
- a6bb8d4bb8af8ec72482ecd194ff92fac9974521aa5ad8a46abfc4f0ba858775
gpu_ids:
oneOf:
- type: array
items:
$ref: "#/components/schemas/GpuID"
- type: "null"
description: >
An array of GPU identifiers or `null` if this information is not yet available
required:
- id
- status
- termination_reason
- termination_message
- ports
- container_name
- container_id
- gpu_ids
additionalProperties: false
TaskSubmitRequest:
title: shim.api.TaskSubmitRequest
description: Same as `shim.TaskConfig`
type: object
properties:
id:
$ref: "#/components/schemas/TaskID"
name:
type: string
description: Task name. Used to construct unique container name
examples:
- horrible-mule-1-0-0
registry_username:
type: string
default: ""
description: Private container registry username
examples:
- registry-user
registry_password:
type: string
default: ""
description: Private container registry password
examples:
- registry-token
image_name:
type: string
examples:
- ubuntu:22.04
container_user:
type: string
default: root
description: >
If not set, the default image user is used. As of 0.18.24, `dstack` always uses `root`
examples:
- root
privileged:
type: boolean
default: false
description: Start container in privileged mode
gpu:
type: integer
minimum: -1
default: 0
description: >
Number of GPUs allocated for the container. A special value `-1` means "all available,
even if none", `0` means "zero GPUs"
cpu:
type: number
minimum: 0
default: 0
description: >
Amount of CPU resources available to the container. A special value `0` means "all".
Fractional values are allowed, e.g., `1.5` — one and a half CPUs
memory:
type: number
minimum: 0
default: 0
description: >
Amount of memory available to the container, in bytes. A special value `0` means "all"
shm_size:
type: integer
minimum: 0
default: 0
description: >
POSIX shared memory, bytes. A special value `0` means "use the default value (64MiB)".
If > 0, tmpfs is mounted with the `exec` option, unlike the default mount options
examples:
- 1073741824
network_mode:
allOf:
- $ref: "#/components/schemas/NetworkMode"
- default: host
volumes:
type: array
items:
$ref: "#/components/schemas/VolumeInfo"
default: []
volume_mounts:
type: array
items:
$ref: "#/components/schemas/VolumeMountPoint"
default: []
instance_mounts:
type: array
items:
$ref: "#/components/schemas/InstanceMountPoint"
default: []
gpu_devices:
type: array
items:
$ref: "#/components/schemas/GPUDevice"
default: []
host_ssh_user:
type: string
default: ""
description: >
Instance (host) user for SSH access, either directly (`ssh {run_name}-host`)
or for `ProxyJump`ing inside the container. Ignored if `host_ssh_keys` is not set
examples:
- root
host_ssh_keys:
type: array
items:
type: string
default: []
description: >
SSH public keys for access to the instance (host). If set, the keys will be added
to the `host_ssh_user`'s `~/.ssh/authorized_keys` when the run starts and removed
when the run exits.
examples:
- "ssh-ed25519 <BASE64> me@laptop"
container_ssh_keys:
type: array
items:
type: string
default: []
description: >
SSH public keys for `container_user`. As of 0.18.24, `dstack` submits two keys:
project key (generated by the server) and user key (either generated by
the CLI client or provided by the user)
examples:
- ["ssh-rsa <BASE64> project@dstack", "ssh-ed25519 <BASE64> me@laptop"]
required:
- id
- name
- image_name
TaskTerminateRequest:
title: shim.api.TaskTerminateRequest
type: object
properties:
termination_reason:
allOf:
- $ref: "#/components/schemas/TerminationReason"
- examples:
- TERMINATED_BY_USER
- TERMINATED_BY_SERVER
default: ""
termination_message:
type: string
default: ""
timeout:
type: boolean
default: 0
description: >
Seconds to wait before killing the container. If zero, kill
the container immediately (no graceful shutdown)
responses:
TaskInfo:
description: Task info
content:
application/json:
schema:
$ref: "#/components/schemas/TaskInfoResponse"
PlainTextOk:
description: ""
content:
text/plain:
schema:
type: string
examples:
- OK
PlainTextBadRequest:
description: ""
content:
text/plain:
schema:
type: string
examples:
- bad request
PlainTextNotFound:
description: ""
content:
text/plain:
schema:
type: string
examples:
- not found
PlainTextConflict:
description: ""
content:
text/plain:
schema:
type: string
examples:
- conflict
PlainTextInternalError:
description: ""
content:
text/plain:
schema:
type: string
examples:
- internal error