propolis-server.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Oxide Propolis Server API",
    "description": "API for interacting with the Propolis hypervisor frontend.",
    "contact": {
      "url": "https://oxide.computer",
      "email": "api@oxide.computer"
    },
    "version": "0.0.1"
  },
  "paths": {
    "/instance": {
      "get": {
        "operationId": "instance_get",
        "responses": {
          "200": {
            "description": "successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstanceGetResponse"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "put": {
        "operationId": "instance_ensure",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstanceEnsureRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "successful creation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstanceEnsureResponse"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/instance/disk/{id}/snapshot/{snapshot_id}": {
      "post": {
        "summary": "Issues a snapshot request to a crucible backend.",
        "operationId": "instance_issue_crucible_snapshot_request",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "snapshot_id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "title": "Null",
                  "type": "string",
                  "enum": [
                    null
                  ]
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/instance/disk/{id}/status": {
      "get": {
        "summary": "Gets the status of a Crucible volume backing a disk",
        "operationId": "disk_volume_status",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VolumeStatus"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/instance/disk/{id}/vcr": {
      "put": {
        "summary": "Issues a volume_construction_request replace to a crucible backend.",
        "operationId": "instance_issue_crucible_vcr_request",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstanceVCRReplace"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReplaceResult"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/instance/migration-status": {
      "get": {
        "operationId": "instance_migrate_status",
        "responses": {
          "200": {
            "description": "successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstanceMigrateStatusResponse"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/instance/nmi": {
      "post": {
        "summary": "Issues an NMI to the instance.",
        "operationId": "instance_issue_nmi",
        "responses": {
          "200": {
            "description": "successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "title": "Null",
                  "type": "string",
                  "enum": [
                    null
                  ]
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/instance/serial": {
      "get": {
        "operationId": "instance_serial",
        "parameters": [
          {
            "in": "query",
            "name": "from_start",
            "description": "Character index in the serial buffer from which to read, counting the bytes output since instance start. If this is provided, `most_recent` must *not* be provided.",
            "schema": {
              "nullable": true,
              "type": "integer",
              "format": "uint64",
              "minimum": 0
            }
          },
          {
            "in": "query",
            "name": "most_recent",
            "description": "Character index in the serial buffer from which to read, counting *backward* from the most recently buffered data retrieved from the instance. (See note on `from_start` about mutual exclusivity)",
            "schema": {
              "nullable": true,
              "type": "integer",
              "format": "uint64",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "default": {
            "description": "",
            "content": {
              "*/*": {
                "schema": {}
              }
            }
          }
        },
        "x-dropshot-websocket": {}
      }
    },
    "/instance/serial/history": {
      "get": {
        "operationId": "instance_serial_history_get",
        "parameters": [
          {
            "in": "query",
            "name": "from_start",
            "description": "Character index in the serial buffer from which to read, counting the bytes output since instance start. If this is not provided, `most_recent` must be provided, and if this *is* provided, `most_recent` must *not* be provided.",
            "schema": {
              "nullable": true,
              "type": "integer",
              "format": "uint64",
              "minimum": 0
            }
          },
          {
            "in": "query",
            "name": "max_bytes",
            "description": "Maximum number of bytes of buffered serial console contents to return. If the requested range runs to the end of the available buffer, the data returned will be shorter than `max_bytes`.",
            "schema": {
              "nullable": true,
              "type": "integer",
              "format": "uint64",
              "minimum": 0
            }
          },
          {
            "in": "query",
            "name": "most_recent",
            "description": "Character index in the serial buffer from which to read, counting *backward* from the most recently buffered data retrieved from the instance. (See note on `from_start` about mutual exclusivity)",
            "schema": {
              "nullable": true,
              "type": "integer",
              "format": "uint64",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstanceSerialConsoleHistoryResponse"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/instance/spec": {
      "get": {
        "operationId": "instance_spec_get",
        "responses": {
          "200": {
            "description": "successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstanceSpecGetResponse"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/instance/state": {
      "put": {
        "operationId": "instance_state_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstanceStateRequested"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "resource updated"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/instance/state-monitor": {
      "get": {
        "operationId": "instance_state_monitor",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstanceStateMonitorRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstanceStateMonitorResponse"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BlobStorageBackend": {
        "description": "A storage backend for a disk whose initial contents are given explicitly by the specification.",
        "type": "object",
        "properties": {
          "base64": {
            "description": "The disk's initial contents, encoded as a base64 string.",
            "type": "string"
          },
          "readonly": {
            "description": "Indicates whether the storage is read-only.",
            "type": "boolean"
          }
        },
        "required": [
          "base64",
          "readonly"
        ],
        "additionalProperties": false
      },
      "Board": {
        "description": "A VM's mainboard.",
        "type": "object",
        "properties": {
          "chipset": {
            "description": "The chipset to expose to guest software.",
            "allOf": [
              {
                "$ref": "#/components/schemas/Chipset"
              }
            ]
          },
          "cpuid": {
            "nullable": true,
            "description": "The CPUID values to expose to the guest. If `None`, bhyve will derive default values from the host's CPUID values.",
            "allOf": [
              {
                "$ref": "#/components/schemas/Cpuid"
              }
            ]
          },
          "cpus": {
            "description": "The number of virtual logical processors attached to this VM.",
            "type": "integer",
            "format": "uint8",
            "minimum": 0
          },
          "guest_hv_interface": {
            "description": "The hypervisor platform to expose to the guest. The default is a bhyve-compatible interface with no additional features.\n\nFor compatibility with older versions of Propolis, this field is only serialized if it specifies a non-default interface.",
            "allOf": [
              {
                "$ref": "#/components/schemas/GuestHypervisorInterface"
              }
            ]
          },
          "memory_mb": {
            "description": "The amount of guest RAM attached to this VM.",
            "type": "integer",
            "format": "uint64",
            "minimum": 0
          }
        },
        "required": [
          "chipset",
          "cpus",
          "memory_mb"
        ],
        "additionalProperties": false
      },
      "BootOrderEntry": {
        "description": "An entry in the boot order stored in a [`BootSettings`] component.",
        "type": "object",
        "properties": {
          "id": {
            "description": "The ID of another component in the spec that Propolis should try to boot from.\n\nCurrently, only disk device components are supported.",
            "allOf": [
              {
                "$ref": "#/components/schemas/SpecKey"
              }
            ]
          }
        },
        "required": [
          "id"
        ]
      },
      "BootSettings": {
        "description": "Settings supplied to the guest's firmware image that specify the order in which it should consider its options when selecting a device to try to boot from.",
        "type": "object",
        "properties": {
          "order": {
            "description": "An ordered list of components to attempt to boot from.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BootOrderEntry"
            }
          }
        },
        "required": [
          "order"
        ],
        "additionalProperties": false
      },
      "Chipset": {
        "description": "A kind of virtual chipset.",
        "oneOf": [
          {
            "description": "An Intel 440FX-compatible chipset.",
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "i440_fx"
                ]
              },
              "value": {
                "$ref": "#/components/schemas/I440Fx"
              }
            },
            "required": [
              "type",
              "value"
            ],
            "additionalProperties": false
          }
        ]
      },
      "ComponentV0": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/VirtioDisk"
              },
              "type": {
                "type": "string",
                "enum": [
                  "VirtioDisk"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/NvmeDisk"
              },
              "type": {
                "type": "string",
                "enum": [
                  "NvmeDisk"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/VirtioNic"
              },
              "type": {
                "type": "string",
                "enum": [
                  "VirtioNic"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/SerialPort"
              },
              "type": {
                "type": "string",
                "enum": [
                  "SerialPort"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/PciPciBridge"
              },
              "type": {
                "type": "string",
                "enum": [
                  "PciPciBridge"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/QemuPvpanic"
              },
              "type": {
                "type": "string",
                "enum": [
                  "QemuPvpanic"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/BootSettings"
              },
              "type": {
                "type": "string",
                "enum": [
                  "BootSettings"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/SoftNpuPciPort"
              },
              "type": {
                "type": "string",
                "enum": [
                  "SoftNpuPciPort"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/SoftNpuPort"
              },
              "type": {
                "type": "string",
                "enum": [
                  "SoftNpuPort"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/SoftNpuP9"
              },
              "type": {
                "type": "string",
                "enum": [
                  "SoftNpuP9"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/P9fs"
              },
              "type": {
                "type": "string",
                "enum": [
                  "P9fs"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/MigrationFailureInjector"
              },
              "type": {
                "type": "string",
                "enum": [
                  "MigrationFailureInjector"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/CrucibleStorageBackend"
              },
              "type": {
                "type": "string",
                "enum": [
                  "CrucibleStorageBackend"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/FileStorageBackend"
              },
              "type": {
                "type": "string",
                "enum": [
                  "FileStorageBackend"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/BlobStorageBackend"
              },
              "type": {
                "type": "string",
                "enum": [
                  "BlobStorageBackend"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/VirtioNetworkBackend"
              },
              "type": {
                "type": "string",
                "enum": [
                  "VirtioNetworkBackend"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "$ref": "#/components/schemas/DlpiNetworkBackend"
              },
              "type": {
                "type": "string",
                "enum": [
                  "DlpiNetworkBackend"
                ]
              }
            },
            "required": [
              "component",
              "type"
            ],
            "additionalProperties": false
          }
        ]
      },
      "Cpuid": {
        "description": "A set of CPUID values to expose to a guest.",
        "type": "object",
        "properties": {
          "entries": {
            "description": "A list of CPUID leaves/subleaves and their associated values.\n\nPropolis servers require that each entry's `leaf` be unique and that it falls in either the \"standard\" (0 to 0xFFFF) or \"extended\" (0x8000_0000 to 0x8000_FFFF) function ranges, since these are the only valid input ranges currently defined by Intel and AMD. See the Intel 64 and IA-32 Architectures Software Developer's Manual (June 2024) Table 3-17 and the AMD64 Architecture Programmer's Manual (March 2024) Volume 3's documentation of the CPUID instruction.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CpuidEntry"
            }
          },
          "vendor": {
            "description": "The CPU vendor to emulate.\n\nCPUID leaves in the extended range (0x8000_0000 to 0x8000_FFFF) have vendor-defined semantics. Propolis uses this value to determine these semantics when deciding whether it needs to specialize the supplied template values for these leaves.",
            "allOf": [
              {
                "$ref": "#/components/schemas/CpuidVendor"
              }
            ]
          }
        },
        "required": [
          "entries",
          "vendor"
        ],
        "additionalProperties": false
      },
      "CpuidEntry": {
        "description": "A full description of a CPUID leaf/subleaf and the values it produces.",
        "type": "object",
        "properties": {
          "eax": {
            "description": "The value to return in eax.",
            "type": "integer",
            "format": "uint32",
            "minimum": 0
          },
          "ebx": {
            "description": "The value to return in ebx.",
            "type": "integer",
            "format": "uint32",
            "minimum": 0
          },
          "ecx": {
            "description": "The value to return in ecx.",
            "type": "integer",
            "format": "uint32",
            "minimum": 0
          },
          "edx": {
            "description": "The value to return in edx.",
            "type": "integer",
            "format": "uint32",
            "minimum": 0
          },
          "leaf": {
            "description": "The leaf (function) number for this entry.",
            "type": "integer",
            "format": "uint32",
            "minimum": 0
          },
          "subleaf": {
            "nullable": true,
            "description": "The subleaf (index) number for this entry, if it uses subleaves.",
            "type": "integer",
            "format": "uint32",
            "minimum": 0
          }
        },
        "required": [
          "eax",
          "ebx",
          "ecx",
          "edx",
          "leaf"
        ],
        "additionalProperties": false
      },
      "CpuidVendor": {
        "description": "A CPU vendor to use when interpreting the meanings of CPUID leaves in the extended ID range (0x80000000 to 0x8000FFFF).",
        "type": "string",
        "enum": [
          "Amd",
          "Intel"
        ]
      },
      "CrucibleStorageBackend": {
        "description": "A Crucible storage backend.",
        "type": "object",
        "properties": {
          "readonly": {
            "description": "Indicates whether the storage is read-only.",
            "type": "boolean"
          },
          "request_json": {
            "description": "A serialized `[crucible_client_types::VolumeConstructionRequest]`. This is stored in serialized form so that breaking changes to the definition of a `VolumeConstructionRequest` do not inadvertently break instance spec deserialization.\n\nWhen using a spec to initialize a new instance, the spec author must ensure this request is well-formed and can be deserialized by the version of `crucible_client_types` used by the target Propolis.",
            "type": "string"
          }
        },
        "required": [
          "readonly",
          "request_json"
        ],
        "additionalProperties": false
      },
      "DlpiNetworkBackend": {
        "description": "A network backend associated with a DLPI VNIC on the host.",
        "type": "object",
        "properties": {
          "vnic_name": {
            "description": "The name of the VNIC to use as a backend.",
            "type": "string"
          }
        },
        "required": [
          "vnic_name"
        ],
        "additionalProperties": false
      },
      "Error": {
        "description": "Error information from a response.",
        "type": "object",
        "properties": {
          "error_code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "message",
          "request_id"
        ]
      },
      "FileStorageBackend": {
        "description": "A storage backend backed by a file in the host system's file system.",
        "type": "object",
        "properties": {
          "path": {
            "description": "A path to a file that backs a disk.",
            "type": "string"
          },
          "readonly": {
            "description": "Indicates whether the storage is read-only.",
            "type": "boolean"
          }
        },
        "required": [
          "path",
          "readonly"
        ],
        "additionalProperties": false
      },
      "GuestHypervisorInterface": {
        "description": "A hypervisor interface to expose to the guest.",
        "oneOf": [
          {
            "description": "Expose a bhyve-like interface (\"bhyve bhyve \" as the hypervisor ID in leaf 0x4000_0000 and no additional leaves or features).",
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "Bhyve"
                ]
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          },
          {
            "description": "Expose a Hyper-V-compatible hypervisor interface with the supplied features enabled.",
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "HyperV"
                ]
              },
              "value": {
                "type": "object",
                "properties": {
                  "features": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/HyperVFeatureFlag"
                    },
                    "uniqueItems": true
                  }
                },
                "required": [
                  "features"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "type",
              "value"
            ],
            "additionalProperties": false
          }
        ]
      },
      "HyperVFeatureFlag": {
        "description": "Flags that enable \"simple\" Hyper-V enlightenments that require no feature-specific configuration.",
        "type": "string",
        "enum": [
          "ReferenceTsc"
        ]
      },
      "I440Fx": {
        "description": "An Intel 440FX-compatible chipset.",
        "type": "object",
        "properties": {
          "enable_pcie": {
            "description": "Specifies whether the chipset should allow PCI configuration space to be accessed through the PCIe extended configuration mechanism.",
            "type": "boolean"
          }
        },
        "required": [
          "enable_pcie"
        ],
        "additionalProperties": false
      },
      "Instance": {
        "type": "object",
        "properties": {
          "properties": {
            "$ref": "#/components/schemas/InstanceProperties"
          },
          "state": {
            "$ref": "#/components/schemas/InstanceState"
          }
        },
        "required": [
          "properties",
          "state"
        ]
      },
      "InstanceEnsureRequest": {
        "type": "object",
        "properties": {
          "init": {
            "$ref": "#/components/schemas/InstanceInitializationMethod"
          },
          "properties": {
            "$ref": "#/components/schemas/InstanceProperties"
          }
        },
        "required": [
          "init",
          "properties"
        ]
      },
      "InstanceEnsureResponse": {
        "type": "object",
        "properties": {
          "migrate": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/InstanceMigrateInitiateResponse"
              }
            ]
          }
        }
      },
      "InstanceGetResponse": {
        "type": "object",
        "properties": {
          "instance": {
            "$ref": "#/components/schemas/Instance"
          }
        },
        "required": [
          "instance"
        ]
      },
      "InstanceInitializationMethod": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "Spec"
                ]
              },
              "value": {
                "type": "object",
                "properties": {
                  "spec": {
                    "$ref": "#/components/schemas/InstanceSpecV0"
                  }
                },
                "required": [
                  "spec"
                ]
              }
            },
            "required": [
              "method",
              "value"
            ]
          },
          {
            "type": "object",
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "MigrationTarget"
                ]
              },
              "value": {
                "type": "object",
                "properties": {
                  "migration_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "replace_components": {
                    "type": "object",
                    "additionalProperties": {
                      "$ref": "#/components/schemas/ReplacementComponent"
                    }
                  },
                  "src_addr": {
                    "type": "string"
                  }
                },
                "required": [
                  "migration_id",
                  "replace_components",
                  "src_addr"
                ]
              }
            },
            "required": [
              "method",
              "value"
            ]
          }
        ]
      },
      "InstanceMetadata": {
        "type": "object",
        "properties": {
          "project_id": {
            "type": "string",
            "format": "uuid"
          },
          "silo_id": {
            "type": "string",
            "format": "uuid"
          },
          "sled_id": {
            "type": "string",
            "format": "uuid"
          },
          "sled_model": {
            "type": "string"
          },
          "sled_revision": {
            "type": "integer",
            "format": "uint32",
            "minimum": 0
          },
          "sled_serial": {
            "type": "string"
          }
        },
        "required": [
          "project_id",
          "silo_id",
          "sled_id",
          "sled_model",
          "sled_revision",
          "sled_serial"
        ]
      },
      "InstanceMigrateInitiateResponse": {
        "type": "object",
        "properties": {
          "migration_id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "migration_id"
        ]
      },
      "InstanceMigrateStatusResponse": {
        "description": "The statuses of the most recent attempts to live migrate into and out of this Propolis.\n\nIf a VM is initialized by migration in and then begins to migrate out, this structure will contain statuses for both migrations. This ensures that clients can always obtain the status of a successful migration in even after a migration out begins.\n\nThis structure only reports the status of the most recent migration in a single direction. That is, if a migration in or out fails, and a new migration attempt begins, the new migration's status replaces the old's.",
        "type": "object",
        "properties": {
          "migration_in": {
            "nullable": true,
            "description": "The status of the most recent attempt to initialize the current instance via migration in, or `None` if the instance has never been a migration target.",
            "allOf": [
              {
                "$ref": "#/components/schemas/InstanceMigrationStatus"
              }
            ]
          },
          "migration_out": {
            "nullable": true,
            "description": "The status of the most recent attempt to migrate out of the current instance, or `None` if the instance has never been a migration source.",
            "allOf": [
              {
                "$ref": "#/components/schemas/InstanceMigrationStatus"
              }
            ]
          }
        }
      },
      "InstanceMigrationStatus": {
        "description": "The status of an individual live migration.",
        "type": "object",
        "properties": {
          "id": {
            "description": "The ID of this migration, supplied either by the external migration requester (for targets) or the other side of the migration (for sources).",
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "description": "The current phase the migration is in.",
            "allOf": [
              {
                "$ref": "#/components/schemas/MigrationState"
              }
            ]
          }
        },
        "required": [
          "id",
          "state"
        ]
      },
      "InstanceProperties": {
        "type": "object",
        "properties": {
          "description": {
            "description": "Free-form text description of an Instance.",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for this Instance.",
            "type": "string",
            "format": "uuid"
          },
          "metadata": {
            "description": "Metadata used to track statistics for this Instance.",
            "allOf": [
              {
                "$ref": "#/components/schemas/InstanceMetadata"
              }
            ]
          },
          "name": {
            "description": "Human-readable name of the Instance.",
            "type": "string"
          }
        },
        "required": [
          "description",
          "id",
          "metadata",
          "name"
        ]
      },
      "InstanceSerialConsoleHistoryResponse": {
        "description": "Contents of an Instance's serial console buffer.",
        "type": "object",
        "properties": {
          "data": {
            "description": "The bytes starting from the requested offset up to either the end of the buffer or the request's `max_bytes`. Provided as a u8 array rather than a string, as it may not be UTF-8.",
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint8",
              "minimum": 0
            }
          },
          "last_byte_offset": {
            "description": "The absolute offset since boot (suitable for use as `byte_offset` in a subsequent request) of the last byte returned in `data`.",
            "type": "integer",
            "format": "uint64",
            "minimum": 0
          }
        },
        "required": [
          "data",
          "last_byte_offset"
        ]
      },
      "InstanceSpecGetResponse": {
        "type": "object",
        "properties": {
          "properties": {
            "$ref": "#/components/schemas/InstanceProperties"
          },
          "spec": {
            "$ref": "#/components/schemas/InstanceSpecStatus"
          },
          "state": {
            "$ref": "#/components/schemas/InstanceState"
          }
        },
        "required": [
          "properties",
          "spec",
          "state"
        ]
      },
      "InstanceSpecStatus": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "WaitingForMigrationSource"
                ]
              }
            },
            "required": [
              "type"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "Present"
                ]
              },
              "value": {
                "$ref": "#/components/schemas/VersionedInstanceSpec"
              }
            },
            "required": [
              "type",
              "value"
            ]
          }
        ]
      },
      "InstanceSpecV0": {
        "type": "object",
        "properties": {
          "board": {
            "$ref": "#/components/schemas/Board"
          },
          "components": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/ComponentV0"
            }
          }
        },
        "required": [
          "board",
          "components"
        ],
        "additionalProperties": false
      },
      "InstanceState": {
        "description": "Current state of an Instance.",
        "type": "string",
        "enum": [
          "Creating",
          "Starting",
          "Running",
          "Stopping",
          "Stopped",
          "Rebooting",
          "Migrating",
          "Repairing",
          "Failed",
          "Destroyed"
        ]
      },
      "InstanceStateMonitorRequest": {
        "type": "object",
        "properties": {
          "gen": {
            "type": "integer",
            "format": "uint64",
            "minimum": 0
          }
        },
        "required": [
          "gen"
        ]
      },
      "InstanceStateMonitorResponse": {
        "type": "object",
        "properties": {
          "gen": {
            "type": "integer",
            "format": "uint64",
            "minimum": 0
          },
          "migration": {
            "$ref": "#/components/schemas/InstanceMigrateStatusResponse"
          },
          "state": {
            "$ref": "#/components/schemas/InstanceState"
          }
        },
        "required": [
          "gen",
          "migration",
          "state"
        ]
      },
      "InstanceStateRequested": {
        "type": "string",
        "enum": [
          "Run",
          "Stop",
          "Reboot"
        ]
      },
      "InstanceVCRReplace": {
        "type": "object",
        "properties": {
          "vcr_json": {
            "type": "string"
          }
        },
        "required": [
          "vcr_json"
        ]
      },
      "MigrationFailureInjector": {
        "description": "Describes a synthetic device that registers for VM lifecycle notifications and returns errors during attempts to migrate.\n\nThis is only supported by Propolis servers compiled with the `failure-injection` feature.",
        "type": "object",
        "properties": {
          "fail_exports": {
            "description": "The number of times this device should fail requests to export state.",
            "type": "integer",
            "format": "uint32",
            "minimum": 0
          },
          "fail_imports": {
            "description": "The number of times this device should fail requests to import state.",
            "type": "integer",
            "format": "uint32",
            "minimum": 0
          }
        },
        "required": [
          "fail_exports",
          "fail_imports"
        ],
        "additionalProperties": false
      },
      "MigrationState": {
        "type": "string",
        "enum": [
          "Sync",
          "RamPush",
          "Pause",
          "RamPushDirty",
          "Device",
          "Resume",
          "RamPull",
          "Server",
          "Finish",
          "Error"
        ]
      },
      "NvmeDisk": {
        "description": "A disk that presents an NVMe interface to the guest.",
        "type": "object",
        "properties": {
          "backend_id": {
            "description": "The name of the disk's backend component.",
            "allOf": [
              {
                "$ref": "#/components/schemas/SpecKey"
              }
            ]
          },
          "pci_path": {
            "description": "The PCI bus/device/function at which this disk should be attached.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PciPath"
              }
            ]
          },
          "serial_number": {
            "description": "The serial number to return in response to an NVMe Identify Controller command.",
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint8",
              "minimum": 0
            },
            "minItems": 20,
            "maxItems": 20
          }
        },
        "required": [
          "backend_id",
          "pci_path",
          "serial_number"
        ],
        "additionalProperties": false
      },
      "P9fs": {
        "description": "Describes a filesystem to expose through a P9 device.\n\nThis is only supported by Propolis servers compiled with the `falcon` feature.",
        "type": "object",
        "properties": {
          "chunk_size": {
            "description": "The chunk size to use in the 9P protocol. Vanilla Helios images should use 8192. Falcon Helios base images and Linux can use up to 65536.",
            "type": "integer",
            "format": "uint32",
            "minimum": 0
          },
          "pci_path": {
            "description": "The PCI path at which to attach the guest to this P9 filesystem.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PciPath"
              }
            ]
          },
          "source": {
            "description": "The host source path to mount into the guest.",
            "type": "string"
          },
          "target": {
            "description": "The 9P target filesystem tag.",
            "type": "string"
          }
        },
        "required": [
          "chunk_size",
          "pci_path",
          "source",
          "target"
        ],
        "additionalProperties": false
      },
      "PciPath": {
        "description": "A PCI bus/device/function tuple.",
        "type": "object",
        "properties": {
          "bus": {
            "type": "integer",
            "format": "uint8",
            "minimum": 0
          },
          "device": {
            "type": "integer",
            "format": "uint8",
            "minimum": 0
          },
          "function": {
            "type": "integer",
            "format": "uint8",
            "minimum": 0
          }
        },
        "required": [
          "bus",
          "device",
          "function"
        ]
      },
      "PciPciBridge": {
        "description": "A PCI-PCI bridge.",
        "type": "object",
        "properties": {
          "downstream_bus": {
            "description": "The logical bus number of this bridge's downstream bus. Other devices may use this bus number in their PCI paths to indicate they should be attached to this bridge's bus.",
            "type": "integer",
            "format": "uint8",
            "minimum": 0
          },
          "pci_path": {
            "description": "The PCI path at which to attach this bridge.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PciPath"
              }
            ]
          }
        },
        "required": [
          "downstream_bus",
          "pci_path"
        ],
        "additionalProperties": false
      },
      "QemuPvpanic": {
        "type": "object",
        "properties": {
          "enable_isa": {
            "description": "Enable the QEMU PVPANIC ISA bus device (I/O port 0x505).",
            "type": "boolean"
          }
        },
        "required": [
          "enable_isa"
        ],
        "additionalProperties": false
      },
      "ReplaceResult": {
        "type": "string",
        "enum": [
          "started",
          "started_already",
          "completed_already",
          "missing",
          "vcr_matches"
        ]
      },
      "ReplacementComponent": {
        "description": "An instance spec component that should be replaced during a live migration.",
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "component": {
                "type": "string",
                "enum": [
                  "MigrationFailureInjector"
                ]
              },
              "spec": {
                "$ref": "#/components/schemas/MigrationFailureInjector"
              }
            },
            "required": [
              "component",
              "spec"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "type": "string",
                "enum": [
                  "CrucibleStorageBackend"
                ]
              },
              "spec": {
                "$ref": "#/components/schemas/CrucibleStorageBackend"
              }
            },
            "required": [
              "component",
              "spec"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "component": {
                "type": "string",
                "enum": [
                  "VirtioNetworkBackend"
                ]
              },
              "spec": {
                "$ref": "#/components/schemas/VirtioNetworkBackend"
              }
            },
            "required": [
              "component",
              "spec"
            ],
            "additionalProperties": false
          }
        ]
      },
      "SerialPort": {
        "description": "A serial port device.",
        "type": "object",
        "properties": {
          "num": {
            "description": "The serial port number for this port.",
            "allOf": [
              {
                "$ref": "#/components/schemas/SerialPortNumber"
              }
            ]
          }
        },
        "required": [
          "num"
        ],
        "additionalProperties": false
      },
      "SerialPortNumber": {
        "description": "A serial port identifier, which determines what I/O ports a guest can use to access a port.",
        "type": "string",
        "enum": [
          "com1",
          "com2",
          "com3",
          "com4"
        ]
      },
      "SoftNpuP9": {
        "description": "Describes a PCI device that shares host files with the guest using the P9 protocol.\n\nThis is only supported by Propolis servers compiled with the `falcon` feature.",
        "type": "object",
        "properties": {
          "pci_path": {
            "description": "The PCI path at which to attach the guest to this port.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PciPath"
              }
            ]
          }
        },
        "required": [
          "pci_path"
        ],
        "additionalProperties": false
      },
      "SoftNpuPciPort": {
        "description": "Describes a SoftNPU PCI device.\n\nThis is only supported by Propolis servers compiled with the `falcon` feature.",
        "type": "object",
        "properties": {
          "pci_path": {
            "description": "The PCI path at which to attach the guest to this port.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PciPath"
              }
            ]
          }
        },
        "required": [
          "pci_path"
        ],
        "additionalProperties": false
      },
      "SoftNpuPort": {
        "description": "Describes a port in a SoftNPU emulated ASIC.\n\nThis is only supported by Propolis servers compiled with the `falcon` feature.",
        "type": "object",
        "properties": {
          "backend_id": {
            "description": "The name of the port's associated DLPI backend.",
            "allOf": [
              {
                "$ref": "#/components/schemas/SpecKey"
              }
            ]
          },
          "link_name": {
            "description": "The data link name for this port.",
            "type": "string"
          }
        },
        "required": [
          "backend_id",
          "link_name"
        ],
        "additionalProperties": false
      },
      "SpecKey": {
        "description": "A key identifying a component in an instance spec.",
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "Uuid": {
                "type": "string",
                "format": "uuid"
              }
            },
            "required": [
              "Uuid"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "Name": {
                "type": "string"
              }
            },
            "required": [
              "Name"
            ],
            "additionalProperties": false
          }
        ]
      },
      "VersionedInstanceSpec": {
        "description": "A versioned instance spec.",
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "spec": {
                "$ref": "#/components/schemas/InstanceSpecV0"
              },
              "version": {
                "type": "string",
                "enum": [
                  "V0"
                ]
              }
            },
            "required": [
              "spec",
              "version"
            ],
            "additionalProperties": false
          }
        ]
      },
      "VirtioDisk": {
        "description": "A disk that presents a virtio-block interface to the guest.",
        "type": "object",
        "properties": {
          "backend_id": {
            "description": "The name of the disk's backend component.",
            "allOf": [
              {
                "$ref": "#/components/schemas/SpecKey"
              }
            ]
          },
          "pci_path": {
            "description": "The PCI bus/device/function at which this disk should be attached.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PciPath"
              }
            ]
          }
        },
        "required": [
          "backend_id",
          "pci_path"
        ],
        "additionalProperties": false
      },
      "VirtioNetworkBackend": {
        "description": "A network backend associated with a virtio-net (viona) VNIC on the host.",
        "type": "object",
        "properties": {
          "vnic_name": {
            "description": "The name of the viona VNIC to use as a backend.",
            "type": "string"
          }
        },
        "required": [
          "vnic_name"
        ],
        "additionalProperties": false
      },
      "VirtioNic": {
        "description": "A network card that presents a virtio-net interface to the guest.",
        "type": "object",
        "properties": {
          "backend_id": {
            "description": "The name of the device's backend.",
            "allOf": [
              {
                "$ref": "#/components/schemas/SpecKey"
              }
            ]
          },
          "interface_id": {
            "description": "A caller-defined correlation identifier for this interface. If Propolis is configured to collect network interface kstats in its Oximeter metrics, the metric series for this interface will be associated with this identifier.",
            "type": "string",
            "format": "uuid"
          },
          "pci_path": {
            "description": "The PCI path at which to attach this device.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PciPath"
              }
            ]
          }
        },
        "required": [
          "backend_id",
          "interface_id",
          "pci_path"
        ],
        "additionalProperties": false
      },
      "VolumeStatus": {
        "type": "object",
        "properties": {
          "active": {
            "type": "boolean"
          }
        },
        "required": [
          "active"
        ]
      }
    },
    "responses": {
      "Error": {
        "description": "Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}