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: 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
        required: true
        schema:
          type: string
    get:
      summary: "Retrieve a VM"
      tags:
        - vms
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $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
          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
          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
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
        resources:
          type: object
          description: |
            Dictionary that maps the resource name to the
            amount of this resource required on the worker
            for this VM to be scheduled
          additionalProperties:
            type: integer
        hostDirs:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              path:
                type: string
              ro:
                type: boolean
    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
    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