693 lines
19 KiB
YAML
693 lines
19 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
title: Orchard
|
|
description: Orchard orchestration API
|
|
version: 0.1.0
|
|
paths:
|
|
/controller/info:
|
|
get:
|
|
summary: "Retrieve controller's information"
|
|
tags:
|
|
- controller
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ControllerInfo'
|
|
/cluster-settings:
|
|
get:
|
|
summary: "Retrieve cluster settings"
|
|
tags:
|
|
- cluster-settings
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ClusterSettings'
|
|
put:
|
|
summary: "Update cluster settings"
|
|
tags:
|
|
- cluster-settings
|
|
responses:
|
|
'200':
|
|
description: Cluster settings were successfully updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ClusterSettings'
|
|
/service-accounts:
|
|
post:
|
|
summary: "Create a Service Account"
|
|
tags:
|
|
- service-accounts
|
|
responses:
|
|
'200':
|
|
description: Service Account resource was successfully created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceAccount'
|
|
'409':
|
|
description: Service Account resource with with the same name already exists
|
|
get:
|
|
summary: "List Service Accounts"
|
|
tags:
|
|
- service-accounts
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ServiceAccount'
|
|
/service-accounts/{name}:
|
|
parameters:
|
|
- in: path
|
|
name: name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
summary: "Retrieve a Service Account"
|
|
tags:
|
|
- service-accounts
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceAccount'
|
|
'404':
|
|
description: Service Account resource with the given name doesn't exist
|
|
put:
|
|
summary: "Update a Service Account"
|
|
tags:
|
|
- service-accounts
|
|
responses:
|
|
'200':
|
|
description: Service Account object was successfully updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceAccount'
|
|
'404':
|
|
description: Service Account resource with the given name doesn't exist
|
|
delete:
|
|
summary: "Delete a Service Account"
|
|
tags:
|
|
- service-accounts
|
|
responses:
|
|
'200':
|
|
description: Service Account resource was successfully deleted
|
|
'404':
|
|
description: Service Account resource with the given name doesn't exist
|
|
/workers:
|
|
post:
|
|
summary: "Create a Worker"
|
|
tags:
|
|
- workers
|
|
responses:
|
|
'200':
|
|
description: Worker resource was successfully created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Worker'
|
|
'409':
|
|
description: Worker resource with with the same name already exists
|
|
get:
|
|
summary: "List Workers"
|
|
tags:
|
|
- workers
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Worker'
|
|
/workers/{name}:
|
|
parameters:
|
|
- in: path
|
|
name: name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
summary: "Retrieve a Worker"
|
|
tags:
|
|
- workers
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Worker'
|
|
'404':
|
|
description: Worker resource with the given name doesn't exist
|
|
put:
|
|
summary: "Update a Worker"
|
|
tags:
|
|
- workers
|
|
responses:
|
|
'200':
|
|
description: Worker object was successfully updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Worker'
|
|
'404':
|
|
description: Worker resource with the given name doesn't exist
|
|
delete:
|
|
summary: "Delete a Worker"
|
|
tags:
|
|
- workers
|
|
responses:
|
|
'200':
|
|
description: Worker resource was successfully deleted
|
|
'404':
|
|
description: Worker resource with the given name doesn't exist
|
|
/workers/{name}/port-forward:
|
|
parameters:
|
|
- in: path
|
|
name: name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
summary: "Port-forward to a worker using WebSocket protocol"
|
|
tags:
|
|
- workers
|
|
parameters:
|
|
- in: query
|
|
name: port
|
|
description: Worker's TCP port number to connect to
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 65535
|
|
required: true
|
|
- in: query
|
|
name: wait
|
|
description: Duration in seconds for the worker to become available if it's not available already
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 65535
|
|
default: 10
|
|
required: false
|
|
- in: header
|
|
name: Connection
|
|
description: WebSocket protocol required header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- in: header
|
|
name: Upgrade
|
|
description: WebSocket protocol required header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'400':
|
|
description: Invalid port specified
|
|
'404':
|
|
description: Worker resource with the given name doesn't exist
|
|
'503':
|
|
description: Failed to establish connection with the requested worker
|
|
/vms:
|
|
post:
|
|
summary: "Create a VM"
|
|
tags:
|
|
- vms
|
|
responses:
|
|
'200':
|
|
description: VM resource was successfully created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VM'
|
|
'409':
|
|
description: VM resource with with the same name already exists
|
|
get:
|
|
summary: "List VMs"
|
|
tags:
|
|
- vms
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/VM'
|
|
/vms/{name}:
|
|
parameters:
|
|
- in: path
|
|
name: name
|
|
description: VM name to retrieve
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- in: query
|
|
name: watch
|
|
description: Watch for changes a VM resource and return them a stream of ADDED, MODIFIED and DELETED notifications
|
|
schema:
|
|
type: boolean
|
|
get:
|
|
summary: "Retrieve a VM"
|
|
tags:
|
|
- vms
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VM'
|
|
application/x-ndjson:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [ADDED, MODIFIED, DELETED]
|
|
object:
|
|
$ref: '#/components/schemas/VM'
|
|
'404':
|
|
description: VM resource with the given name doesn't exist
|
|
put:
|
|
summary: "Update a VM"
|
|
tags:
|
|
- vms
|
|
responses:
|
|
'200':
|
|
description: VM object was successfully updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VM'
|
|
'404':
|
|
description: VM resource with the given name doesn't exist
|
|
delete:
|
|
summary: "Delete a VM"
|
|
tags:
|
|
- vms
|
|
responses:
|
|
'200':
|
|
description: VM resource was successfully deleted
|
|
'404':
|
|
description: VM resource with the given name doesn't exist
|
|
/vms/{name}/events:
|
|
parameters:
|
|
- in: path
|
|
name: name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
summary: "Retrieve events for a given VM"
|
|
tags:
|
|
- vms
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Events'
|
|
'404':
|
|
description: VM resource with the given name doesn't exist
|
|
post:
|
|
summary: "Add new events to a VM"
|
|
tags:
|
|
- vms
|
|
responses:
|
|
'200':
|
|
description: Events were successfully added
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Events'
|
|
'404':
|
|
description: VM resource with the given name doesn't exist
|
|
/vms/{name}/port-forward:
|
|
parameters:
|
|
- in: path
|
|
name: name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
summary: "Port-forward to a VM using WebSocket protocol"
|
|
tags:
|
|
- vms
|
|
parameters:
|
|
- in: query
|
|
name: port
|
|
description: VM's TCP port number to connect to
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 65535
|
|
required: true
|
|
- in: query
|
|
name: wait
|
|
description: Duration in seconds to wait for the VM to transition into "running" state if not already running.
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 65535
|
|
default: 10
|
|
required: false
|
|
- in: header
|
|
name: Connection
|
|
description: WebSocket protocol required header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- in: header
|
|
name: Upgrade
|
|
description: WebSocket protocol required header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'400':
|
|
description: Invalid port specified
|
|
'404':
|
|
description: VM resource with the given name doesn't exist
|
|
'503':
|
|
description: Failed to establish connection with the worker responsible for the specified VM
|
|
/vms/{name}/ip:
|
|
parameters:
|
|
- in: path
|
|
name: name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
summary: "Resolve the VM's IP address on the worker"
|
|
tags:
|
|
- vms
|
|
parameters:
|
|
- in: query
|
|
name: wait
|
|
description: Duration in seconds to wait for the VM to transition into "running" state if not already running.
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 65535
|
|
default: 0
|
|
required: false
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/IP'
|
|
'404':
|
|
description: VM resource with the given name doesn't exist
|
|
'503':
|
|
description: Failed to resolve the IP address on the worker responsible for the specified VM
|
|
/vms/{name}/restart:
|
|
parameters:
|
|
- in: path
|
|
name: name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
post:
|
|
summary: "Restart a VM"
|
|
tags:
|
|
- vms
|
|
responses:
|
|
'202':
|
|
description: VM restart was requested
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VM'
|
|
'404':
|
|
description: VM resource with the given name doesn't exist
|
|
'412':
|
|
description: VM is not assigned to a worker and cannot be restarted
|
|
components:
|
|
schemas:
|
|
Worker:
|
|
title: Worker node
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Node name
|
|
resources:
|
|
type: object
|
|
description: |
|
|
Dictionary that maps the resource name to the
|
|
amount of this resource provided by the worker
|
|
for running VMs.
|
|
additionalProperties:
|
|
type: integer
|
|
VM:
|
|
title: Virtual Machine
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: VM name
|
|
example: macos-tahoe-base
|
|
readOnly: true
|
|
image:
|
|
type: string
|
|
description: VM image for this VM
|
|
example: ghcr.io/cirruslabs/macos-tahoe-base:latest
|
|
imagePullPolicy:
|
|
type: string
|
|
description: VM image pull policy
|
|
default: IfNotPresent
|
|
enum: [IfNotPresent, Always]
|
|
cpu:
|
|
type: number
|
|
description: Number of CPUs assigned to this VM
|
|
default: 4
|
|
memory:
|
|
type: number
|
|
description: Amount of RAM in megabytes assigned to this VM
|
|
default: 8192
|
|
diskSize:
|
|
type: number
|
|
description: Disk size for this VM
|
|
example: 100
|
|
net-softnet:
|
|
type: boolean
|
|
description: Please use `netSoftnet` instead
|
|
default: false
|
|
deprecated: true
|
|
netSoftnet:
|
|
type: boolean
|
|
description: |
|
|
Whether to use Softnet network isolation.
|
|
|
|
See `tart run`'s help for `--net-softnet` for more details.
|
|
default: false
|
|
netSoftnetAllow:
|
|
type: array
|
|
description: |
|
|
List of CIDRs to allow the traffic to when using Softnet isolation.
|
|
|
|
See `tart run`'s help for `--net-softnet-allow` for more details.
|
|
|
|
Enables `netSoftnet`.
|
|
example:
|
|
- "192.168.0.0/24"
|
|
items:
|
|
type: string
|
|
netSoftnetBlock:
|
|
type: array
|
|
description: |
|
|
List of CIDRs to block the traffic to when using Softnet isolation.
|
|
|
|
See `tart run`'s help for `--net-softnet-block` for more details.
|
|
|
|
Enables `netSoftnet`.
|
|
example:
|
|
- "66.66.0.0/16"
|
|
items:
|
|
type: string
|
|
net-bridged:
|
|
type: string
|
|
description: Whether to use bridged network mode
|
|
example: en0
|
|
headless:
|
|
type: boolean
|
|
description: Whether to run without graphics
|
|
default: false
|
|
nested:
|
|
type: boolean
|
|
description: Enable nested virtualization
|
|
default: false
|
|
suspendable:
|
|
type: boolean
|
|
description: Whether to allow suspending the VM via `tart run --suspendable`
|
|
default: false
|
|
status:
|
|
type: string
|
|
description: VM status
|
|
enum: [pending, running, failed]
|
|
readOnly: true
|
|
status_message:
|
|
type: string
|
|
description: VM status message
|
|
readOnly: true
|
|
worker:
|
|
type: string
|
|
description: Worker on which the VM was assigned to
|
|
readOnly: true
|
|
username:
|
|
type: string
|
|
description: SSH username to use when connecting to a VM
|
|
default: admin
|
|
password:
|
|
type: string
|
|
description: SSH password to use when connecting to a VM
|
|
default: admin
|
|
startup_script:
|
|
type: object
|
|
description: Startup script to run after the VM boots and becomes accessible via SSH
|
|
properties:
|
|
script_content:
|
|
type: string
|
|
env:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
example:
|
|
script_content: |
|
|
#!/bin/zsh
|
|
|
|
echo $GREETING
|
|
env:
|
|
GREETING: "Hello, World!"
|
|
restart_policy:
|
|
type: string
|
|
description: |
|
|
VM restart policy: specify "Never" to never restart or "OnFailure" to only restart when the VM fails
|
|
default: Never
|
|
enum: [Never, OnFailure]
|
|
restart_requested:
|
|
type: boolean
|
|
description: Indicates that the worker should restart this VM in-place
|
|
readOnly: true
|
|
resources:
|
|
type: object
|
|
description: Resources required by this VM on the worker
|
|
additionalProperties:
|
|
type: integer
|
|
example:
|
|
org.cirruslabs.logical-cores: 4
|
|
org.cirruslabs.memory-mib: 8192
|
|
labels:
|
|
type: object
|
|
description: Labels required by this VM on the worker
|
|
additionalProperties:
|
|
type: string
|
|
example:
|
|
model: macstudio
|
|
hostDirs:
|
|
type: array
|
|
description: Directories on the Orchard Worker host to mount to a VM
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
path:
|
|
type: string
|
|
ro:
|
|
type: boolean
|
|
example:
|
|
- path: /path/on/host/to/sources
|
|
ro: true
|
|
- path: /path/on/host/to/builds
|
|
Events:
|
|
title: Events
|
|
type: object
|
|
items:
|
|
$ref: '#/components/schemas/Event'
|
|
IP:
|
|
title: Result of VM's IP resolution
|
|
type: object
|
|
properties:
|
|
ip:
|
|
type: string
|
|
description: The resolved IP address
|
|
Event:
|
|
title: Generic Resource Event
|
|
type: object
|
|
properties:
|
|
kind:
|
|
type: string
|
|
description: Kind of the event
|
|
payload:
|
|
type: string
|
|
description: Payload of the event
|
|
timestamp:
|
|
type: integer
|
|
description: Unix timestamp of the event
|
|
ServiceAccount:
|
|
title: Service Account
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Name
|
|
token:
|
|
type: string
|
|
description: Secret token used to access the API
|
|
roles:
|
|
type: array
|
|
items:
|
|
type: string
|
|
ControllerInfo:
|
|
title: Controller's Information
|
|
type: object
|
|
properties:
|
|
version:
|
|
type: string
|
|
description: Version number
|
|
commit:
|
|
type: string
|
|
description: Commit hash
|
|
capabilities:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Supported capabilities
|
|
ClusterSettings:
|
|
title: Cluster settings
|
|
type: object
|
|
properties:
|
|
hostDirPolicies:
|
|
type: array
|
|
description: If not empty, enables instantiating VMs with hostDir volumes that match the policies listed in this array.
|
|
items:
|
|
type: object
|
|
properties:
|
|
pathPrefix:
|
|
type: string
|
|
ro:
|
|
type: boolean
|