diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b78210992d..b7861ceca25 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,8 @@ and this project adheres to [#4741](https://github.com/firecracker-microvm/firecracker/pull/4741), [#4746](https://github.com/firecracker-microvm/firecracker/pull/4746): Added official support for 6.1 microVM guest kernels. +- [#4763](https://github.com/firecracker-microvm/firecracker/pull/4763): Migrated + API specification from Swagger 2.0 to OpenAPI 3.1. ### Changed diff --git a/README.md b/README.md index 2045853a900..7735d71558c 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ Firecracker's overall architecture is described in Firecracker consists of a single micro Virtual Machine Manager process that exposes an API endpoint to the host once started. The API is -[specified in OpenAPI format](src/firecracker/swagger/firecracker.yaml). Read +[specified in OpenAPI 3.1 format](src/firecracker/openapi/firecracker.yaml). Read more about it in the [API docs](docs/api_requests). The **API endpoint** can be used to: diff --git a/SPECIFICATION.md b/SPECIFICATION.md index a33ce321a28..0102981bd28 100644 --- a/SPECIFICATION.md +++ b/SPECIFICATION.md @@ -19,7 +19,7 @@ on the following: they are logged[^2] by the Firecracker process. 1. **API Stability:** The API socket is always available and the API conforms to the in-tree - [Open API specification](src/firecracker/swagger/firecracker.yaml). API + [Open API specification](src/firecracker/openapi/firecracker.yaml). API failures are logged in the Firecracker log. 1. **Overhead:** For a Firecracker virtual machine manager running a microVM with `1 CPUs and 128 MiB of RAM`, and a guest OS with the Firecracker-tuned diff --git a/docs/api-change-runbook.md b/docs/api-change-runbook.md index 5455834b117..4a836e1b826 100644 --- a/docs/api-change-runbook.md +++ b/docs/api-change-runbook.md @@ -143,19 +143,19 @@ conditions, there are 2 major cases where we need to deprecate an endpoint: but doing so immediately would be a breaking change. - We just mark the endpoint as deprecated. -### Keeping Swagger updated +### Keeping OpenAPI specification updated Make sure that any changes you make in the code are also reflected in the -swagger specification. +OpenAPI specification. Some tips: -- There is nothing in the swagger file that shows whether an endpoint is +- There is nothing in the OpenAPI file that shows whether an endpoint is mandatory or optional, it’s all code logic. - Mandatory fields in a request or response body are marked with - `required: true` in the swagger definition. All other fields are optional. + the `required` array. All other fields are optional. - If you need to redirect an endpoint, you have to clone the old one under the - new URI in the swagger specification. + new URI in the OpenAPI specification. ### Marking endpoints as deprecated @@ -234,7 +234,7 @@ Firecracker API. deprecation case. - Add a unit test where you test your new code paths. - Fix all other failing unit tests. - - Update the swagger file to reflect the change, in this case by removing the + - Update the OpenAPI specification to reflect the change, in this case by removing the `vsock_id` field from the required parameter list in the `Vsock` definition and adding a description to it stating that it is deprecated since the current version. diff --git a/docs/api_requests/actions.md b/docs/api_requests/actions.md index c72f12372dc..db25d5ae19e 100644 --- a/docs/api_requests/actions.md +++ b/docs/api_requests/actions.md @@ -4,7 +4,7 @@ Firecracker microVMs can execute actions that can be triggered via `PUT` requests on the `/actions` resource. Details about the required fields can be found in the -[swagger definition](../../src/firecracker/swagger/firecracker.yaml). +[OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml). ## InstanceStart diff --git a/docs/api_requests/patch-network-interface.md b/docs/api_requests/patch-network-interface.md index 59d16c62ab5..859eab12d6c 100644 --- a/docs/api_requests/patch-network-interface.md +++ b/docs/api_requests/patch-network-interface.md @@ -56,7 +56,7 @@ Accept: application/json ``` The full specification of the data structures available for this call can be -found in our [OpenAPI spec](../../src/firecracker/swagger/firecracker.yaml). +found in our [OpenAPI spec](../../src/firecracker/openapi/firecracker.yaml). **Note**: The data provided for the update is merged with the existing data. In the above example, the RX rate limit is updated, but the TX rate limit remains diff --git a/docs/device-api.md b/docs/device-api.md index dd2b5e4c9f6..15e77881510 100644 --- a/docs/device-api.md +++ b/docs/device-api.md @@ -33,9 +33,9 @@ BadRequest - HTTP response. ## Input Schema -All input schema fields can be found in the [Swagger](https://swagger.io) +All input schema fields can be found in the [OpenAPI](https://www.openapis.org/) specification: -[firecracker.yaml](./../src/firecracker/swagger/firecracker.yaml). +[firecracker.yaml](./../src/firecracker/openapi/firecracker.yaml). | Schema | Property | keyboard | serial console | virtio-block | vhost-user-block | virtio-net | virtio-vsock | virtio-rng | | ------------------------- | --------------------- | :------: | :------------: | :----------: | :--------------: | :--------: | :----------: | :--------: | @@ -108,9 +108,9 @@ virtio-block and virtio-rng devices. ## Output Schema -All output schema fields can be found in the [Swagger](https://swagger.io) +All output schema fields can be found in the [OpenAPI](https://www.openapis.org/) specification: -[firecracker.yaml](./../src/firecracker/swagger/firecracker.yaml). +[firecracker.yaml](./../src/firecracker/openapi/firecracker.yaml). | Schema | Property | keyboard | serial console | virtio-block | vhost-user-block | virtio-net | virtio-vsock | | ---------------------- | ----------------- | :------: | :------------: | :----------: | :--------------: | :--------: | :----------: | @@ -133,9 +133,9 @@ If more than 64 devices are configured for a VM in total on aarch64, only first ## Instance Actions -All instance actions can be found in the [Swagger](https://swagger.io) +All instance actions can be found in the [OpenAPI](https://www.openapis.org/) specification: -[firecracker.yaml](./../src/firecracker/swagger/firecracker.yaml). +[firecracker.yaml](./../src/firecracker/openapi/firecracker.yaml). | Action | keyboard | serial console | virtio-block | vhost-user-block | virtio-net | virtio-vsock | | ---------------- | :------: | :------------: | :----------: | :--------------: | :--------: | :----------: | diff --git a/docs/getting-started.md b/docs/getting-started.md index dfbfecf83cf..4574e1a5b8d 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -311,7 +311,7 @@ configuration for the guest kernel and rootfs, all of the other resources are optional. This configuration method will also start the microVM, as such you need to specify all desired pre-boot configurable resources in the JSON. The names of the resources can be seen in \[`firecracker.yaml`\] -(../src/firecracker/swagger/firecracker.yaml) and the names of their fields are +(../src/firecracker/openapi/firecracker.yaml) and the names of their fields are the same that are used in the API requests. An example of configuration file is provided: diff --git a/docs/images/api_change_flowchart.png b/docs/images/api_change_flowchart.png index 500e1ac7f07..7b79f82f7ed 100644 Binary files a/docs/images/api_change_flowchart.png and b/docs/images/api_change_flowchart.png differ diff --git a/docs/images/fc_decal_icon-dark_dark-bg.png b/docs/images/fc_decal_icon-dark_dark-bg.png index 81c3561dcf0..0da16ec80ff 100644 Binary files a/docs/images/fc_decal_icon-dark_dark-bg.png and b/docs/images/fc_decal_icon-dark_dark-bg.png differ diff --git a/docs/images/fc_decal_icon-dark_dark-bg.svg b/docs/images/fc_decal_icon-dark_dark-bg.svg index 2be18adbf8c..f0b123811b2 100644 --- a/docs/images/fc_decal_icon-dark_dark-bg.svg +++ b/docs/images/fc_decal_icon-dark_dark-bg.svg @@ -1,697 +1 @@ - - - -image/svg+xml \ No newline at end of file + \ No newline at end of file diff --git a/docs/images/fc_logo_full.svg b/docs/images/fc_logo_full.svg index ab5edbd8e50..3e9e1900c85 100644 --- a/docs/images/fc_logo_full.svg +++ b/docs/images/fc_logo_full.svg @@ -1,907 +1 @@ - - - -image/svg+xml \ No newline at end of file + \ No newline at end of file diff --git a/docs/images/fc_logo_full_transparent-bg.png b/docs/images/fc_logo_full_transparent-bg.png index 3c9fe96a6dc..045a1fc8e63 100644 Binary files a/docs/images/fc_logo_full_transparent-bg.png and b/docs/images/fc_logo_full_transparent-bg.png differ diff --git a/docs/images/fc_logo_full_transparent-bg_white-fg.png b/docs/images/fc_logo_full_transparent-bg_white-fg.png index 6cc90e36044..2372610339f 100644 Binary files a/docs/images/fc_logo_full_transparent-bg_white-fg.png and b/docs/images/fc_logo_full_transparent-bg_white-fg.png differ diff --git a/docs/images/fc_logo_full_white-bg.png b/docs/images/fc_logo_full_white-bg.png index da0bf0e05af..ac125f915f5 100644 Binary files a/docs/images/fc_logo_full_white-bg.png and b/docs/images/fc_logo_full_white-bg.png differ diff --git a/docs/images/fc_logo_full_white-bg_tiny.png b/docs/images/fc_logo_full_white-bg_tiny.png index a1d96250706..24c9bafa81c 100644 Binary files a/docs/images/fc_logo_full_white-bg_tiny.png and b/docs/images/fc_logo_full_white-bg_tiny.png differ diff --git a/docs/images/fc_logo_icon-dark.svg b/docs/images/fc_logo_icon-dark.svg index 93698df195c..da18b97b4d2 100644 --- a/docs/images/fc_logo_icon-dark.svg +++ b/docs/images/fc_logo_icon-dark.svg @@ -1,692 +1 @@ - - - -image/svg+xml \ No newline at end of file + \ No newline at end of file diff --git a/docs/images/fc_logo_icon.svg b/docs/images/fc_logo_icon.svg index 5e5a0a5c7b9..8970be39253 100644 --- a/docs/images/fc_logo_icon.svg +++ b/docs/images/fc_logo_icon.svg @@ -1,521 +1 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + \ No newline at end of file diff --git a/docs/images/fc_logo_icon_transparent-bg.png b/docs/images/fc_logo_icon_transparent-bg.png index a1035f64afa..3b49f3c99a1 100644 Binary files a/docs/images/fc_logo_icon_transparent-bg.png and b/docs/images/fc_logo_icon_transparent-bg.png differ diff --git a/docs/images/fc_logo_icon_transparent-bg_square.png b/docs/images/fc_logo_icon_transparent-bg_square.png index d62c5505f7c..95b5f4c4817 100644 Binary files a/docs/images/fc_logo_icon_transparent-bg_square.png and b/docs/images/fc_logo_icon_transparent-bg_square.png differ diff --git a/docs/images/fc_logo_icon_white-bg.png b/docs/images/fc_logo_icon_white-bg.png index 7775472991b..0bb36393733 100644 Binary files a/docs/images/fc_logo_icon_white-bg.png and b/docs/images/fc_logo_icon_white-bg.png differ diff --git a/docs/images/fc_logo_icon_white-bg_square.png b/docs/images/fc_logo_icon_white-bg_square.png index 86159c894bc..a576681a133 100644 Binary files a/docs/images/fc_logo_icon_white-bg_square.png and b/docs/images/fc_logo_icon_white-bg_square.png differ diff --git a/docs/images/fc_sticker_full_white-bg.png b/docs/images/fc_sticker_full_white-bg.png index 61a18412260..8545c1d158e 100644 Binary files a/docs/images/fc_sticker_full_white-bg.png and b/docs/images/fc_sticker_full_white-bg.png differ diff --git a/docs/images/fc_sticker_full_white-bg.svg b/docs/images/fc_sticker_full_white-bg.svg index 1e86371e0f8..3004dc150d9 100644 --- a/docs/images/fc_sticker_full_white-bg.svg +++ b/docs/images/fc_sticker_full_white-bg.svg @@ -1,912 +1 @@ - - - -image/svg+xml \ No newline at end of file + \ No newline at end of file diff --git a/docs/images/fc_sticker_icon_white-bg.png b/docs/images/fc_sticker_icon_white-bg.png index d0b8278c7f5..2f62101dc40 100644 Binary files a/docs/images/fc_sticker_icon_white-bg.png and b/docs/images/fc_sticker_icon_white-bg.png differ diff --git a/docs/images/fc_sticker_icon_white-bg.svg b/docs/images/fc_sticker_icon_white-bg.svg index 38d48c35779..18bb431cf16 100644 --- a/docs/images/fc_sticker_icon_white-bg.svg +++ b/docs/images/fc_sticker_icon_white-bg.svg @@ -1,835 +1 @@ - - - -image/svg+xml \ No newline at end of file + \ No newline at end of file diff --git a/docs/images/firecracker_host_integration.png b/docs/images/firecracker_host_integration.png index f294f7ff897..fcadabfeb58 100644 Binary files a/docs/images/firecracker_host_integration.png and b/docs/images/firecracker_host_integration.png differ diff --git a/docs/images/firecracker_threat_containment.png b/docs/images/firecracker_threat_containment.png index d4078e6e550..fb2f9972d9b 100644 Binary files a/docs/images/firecracker_threat_containment.png and b/docs/images/firecracker_threat_containment.png differ diff --git a/docs/images/uffd_flow1.png b/docs/images/uffd_flow1.png index a8150769a50..91fe5919f55 100644 Binary files a/docs/images/uffd_flow1.png and b/docs/images/uffd_flow1.png differ diff --git a/docs/images/uffd_flow2.png b/docs/images/uffd_flow2.png index 9486db63546..7663d33037e 100644 Binary files a/docs/images/uffd_flow2.png and b/docs/images/uffd_flow2.png differ diff --git a/docs/images/uffd_flow3.png b/docs/images/uffd_flow3.png index a4c401b8845..e6debae0c68 100644 Binary files a/docs/images/uffd_flow3.png and b/docs/images/uffd_flow3.png differ diff --git a/docs/images/uffd_flow4.png b/docs/images/uffd_flow4.png index 3400dfe8f7e..b00184fc9cd 100644 Binary files a/docs/images/uffd_flow4.png and b/docs/images/uffd_flow4.png differ diff --git a/docs/images/vsock-connections.png b/docs/images/vsock-connections.png index 657e469507e..52223035c04 100644 Binary files a/docs/images/vsock-connections.png and b/docs/images/vsock-connections.png differ diff --git a/docs/logger.md b/docs/logger.md index 4585c4f3f67..10c5cd7a896 100644 --- a/docs/logger.md +++ b/docs/logger.md @@ -36,7 +36,7 @@ curl --unix-socket /tmp/firecracker.socket -i \ ``` Details about the required and optional fields can be found in the -[swagger definition](../src/firecracker/swagger/firecracker.yaml). +[OpenAPI specification](../src/firecracker/openapi/firecracker.yaml). ## Using command line parameters for configuration diff --git a/docs/metrics.md b/docs/metrics.md index 98047e19f55..9956bebfb44 100644 --- a/docs/metrics.md +++ b/docs/metrics.md @@ -43,7 +43,7 @@ curl --unix-socket /tmp/firecracker.socket -i \ ``` Details about this configuration can be found in the -[swagger definition](../src/firecracker/swagger/firecracker.yaml). +[OpenAPI specification](../src/firecracker/openapi/firecracker.yaml). The metrics are written to the `metrics_path` in JSON format. diff --git a/docs/mmds/mmds-design.md b/docs/mmds/mmds-design.md index 7ee9cff0a1c..89dcb949c81 100644 --- a/docs/mmds/mmds-design.md +++ b/docs/mmds/mmds-design.md @@ -116,7 +116,7 @@ reply. Somewhat confusingly, this is the name of the component which taps the device model. It has a user-configured IPv4 address (see -[Firecracker MMDS configuration API](../../src/firecracker/swagger/firecracker.yaml)) +[Firecracker MMDS configuration API](../../src/firecracker/openapi/firecracker.yaml)) and MAC (`06:01:23:45:67:01`) addresses. The latter is also used to respond to ARP requests. For every frame coming from the guest, the following steps take place: diff --git a/docs/mmds/mmds-user-guide.md b/docs/mmds/mmds-user-guide.md index 50eeb9e41e2..3c7439b0b4d 100644 --- a/docs/mmds/mmds-user-guide.md +++ b/docs/mmds/mmds-user-guide.md @@ -15,12 +15,12 @@ two steps: 1. Attach one (or more) network interfaces through an HTTP `PUT` request to `/network-interfaces/${MMDS_NET_IF}`. The full network configuration API can be found in the - [firecracker swagger file](../../src/firecracker/swagger/firecracker.yaml). -1. Configure MMDS through an HTTP `PUT` request to `/mmds/config` resource and + [Firecracker OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml). +2. Configure MMDS through an HTTP `PUT` request to `/mmds/config` resource and include the IDs of the network interfaces that should allow forwarding requests to MMDS in the `network_interfaces` list. The complete MMDS API is described in the - [firecracker swagger file](../../src/firecracker/swagger/firecracker.yaml). + [Firecracker OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml). ### Examples @@ -115,7 +115,7 @@ structured in [JSON](https://tools.ietf.org/html/rfc7159) format. To replace existing metadata, a subsequent HTTP `PUT` request to the `/mmds` resource must be issued, using as a payload the new metadata. A complete description of metadata insertion firecracker API can be found in the -[firecracker swagger file](../../src/firecracker/swagger/firecracker.yaml). +[Firecracker OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml). An example of an API request for inserting metadata is provided below: @@ -150,7 +150,7 @@ To partially update existing metadata, an HTTP `PATCH` request to the `/mmds` resource has to be issued, using as a payload the metadata patch, as [JSON Merge Patch](https://tools.ietf.org/html/rfc7396) functionality describes. A complete description of updating metadata Firecracker API can be found in the -[firecracker swagger file](../../src/firecracker/swagger/firecracker.yaml). +[Firecracker OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml). An example API for how to update existing metadata is offered below: @@ -191,7 +191,7 @@ To retrieve existing MMDS metadata from host operating system, an HTTP `GET` request to the `/mmds` resource must be issued. The HTTP response returns the existing metadata, as a JSON formatted text. A complete description of retrieving metadata Firecracker API can be found in the -[firecracker swagger file](../../src/firecracker/swagger/firecracker.yaml). +[Firecracker OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml). Below you can see how to retrieve metadata from the host: diff --git a/docs/snapshotting/snapshot-support.md b/docs/snapshotting/snapshot-support.md index 3119ffcc264..63deb0905e0 100644 --- a/docs/snapshotting/snapshot-support.md +++ b/docs/snapshotting/snapshot-support.md @@ -271,7 +271,7 @@ curl --unix-socket /tmp/firecracker.socket -i \ ``` Details about the required and optional fields can be found in the -[swagger definition](../../src/firecracker/swagger/firecracker.yaml). +[OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml). *Note*: If the files indicated by `snapshot_path` and `mem_file_path` don't exist at the specified paths, then they will be created right before generating @@ -446,7 +446,7 @@ curl --unix-socket /tmp/firecracker.socket -i \ ``` Details about the required and optional fields can be found in the -[swagger definition](../../src/firecracker/swagger/firecracker.yaml). +[OpenAPI specification](../../src/firecracker/openapi/firecracker.yaml). **Prerequisites**: A full memory snapshot and a microVM state file **must** be provided. The disk backing files, network interfaces backing TAPs and/or vsock diff --git a/src/firecracker/openapi/firecracker.yaml b/src/firecracker/openapi/firecracker.yaml new file mode 100644 index 00000000000..37af3a981ac --- /dev/null +++ b/src/firecracker/openapi/firecracker.yaml @@ -0,0 +1,1418 @@ +openapi: 3.1.0 +info: + title: Firecracker API + description: RESTful public-facing API. The API is accessible through HTTP calls + on specific URLs carrying JSON modeled data. The transport medium is a Unix Domain + Socket. + termsOfService: "" + contact: + email: compute-capsule@amazon.com + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html + version: 1.10.0-dev +servers: +- url: http://localhost/ +paths: + /: + get: + summary: Returns general information about an instance. + operationId: describeInstance + responses: + "200": + description: The instance information + content: + application/json: + schema: + $ref: '#/components/schemas/InstanceInfo' + default: + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /actions: + put: + summary: Creates a synchronous action. + operationId: createSyncAction + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/InstanceActionInfo' + required: true + responses: + "204": + description: The update was successful + content: {} + "400": + description: The action cannot be executed due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: info + /balloon: + get: + summary: Returns the current balloon device configuration. + operationId: describeBalloonConfig + responses: + "200": + description: The balloon device configuration + content: + application/json: + schema: + $ref: '#/components/schemas/Balloon' + "400": + description: Balloon device not configured. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + put: + summary: Creates or updates a balloon device. + description: "Creates a new balloon device if one does not already exist, otherwise\ + \ updates it, before machine startup. This will fail after machine startup.\ + \ Will fail if update is not possible." + operationId: putBalloon + requestBody: + description: Balloon properties + content: + application/json: + schema: + $ref: '#/components/schemas/Balloon' + required: true + responses: + "204": + description: Balloon device created/updated + content: {} + "400": + description: Balloon device cannot be created/updated due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + patch: + summary: Updates a balloon device. + description: "Updates an existing balloon device, before or after machine startup.\ + \ Will fail if update is not possible." + operationId: patchBalloon + requestBody: + description: Balloon properties + content: + application/json: + schema: + $ref: '#/components/schemas/BalloonUpdate' + required: true + responses: + "204": + description: Balloon device updated + content: {} + "400": + description: Balloon device cannot be updated due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /balloon/statistics: + get: + summary: "Returns the latest balloon device statistics, only if enabled pre-boot." + operationId: describeBalloonStats + responses: + "200": + description: The balloon device statistics + content: + application/json: + schema: + $ref: '#/components/schemas/BalloonStats' + "400": + description: The balloon device statistics were not enabled when the device + was configured. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + patch: + summary: Updates a balloon device statistics polling interval. + description: "Updates an existing balloon device statistics interval, before\ + \ or after machine startup. Will fail if update is not possible." + operationId: patchBalloonStatsInterval + requestBody: + description: Balloon properties + content: + application/json: + schema: + $ref: '#/components/schemas/BalloonStatsUpdate' + required: true + responses: + "204": + description: Balloon statistics interval updated + content: {} + "400": + description: Balloon statistics interval cannot be updated due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /boot-source: + put: + summary: Creates or updates the boot source. Pre-boot only. + description: "Creates new boot source if one does not already exist, otherwise\ + \ updates it. Will fail if update is not possible." + operationId: putGuestBootSource + requestBody: + description: Guest boot source properties + content: + application/json: + schema: + $ref: '#/components/schemas/BootSource' + required: true + responses: + "204": + description: Boot source created/updated + content: {} + "400": + description: Boot source cannot be created due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /cpu-config: + put: + summary: Configures CPU features flags for the vCPUs of the guest VM. Pre-boot + only. + description: Provides configuration to the Firecracker process to specify vCPU + resource configuration prior to launching the guest machine. + operationId: putCpuConfiguration + requestBody: + description: CPU configuration request + content: + application/json: + schema: + $ref: '#/components/schemas/CpuConfig' + required: false + responses: + "204": + description: CPU configuration set successfully + content: {} + "400": + description: CPU configuration cannot be updated due to invalid input format + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /drives/{drive_id}: + put: + summary: Creates or updates a drive. Pre-boot only. + description: "Creates new drive with ID specified by drive_id path parameter.\ + \ If a drive with the specified ID already exists, updates its state based\ + \ on new input. Will fail if update is not possible." + operationId: putGuestDriveByID + parameters: + - name: drive_id + in: path + description: The id of the guest drive + required: true + schema: + type: string + requestBody: + description: Guest drive properties + content: + application/json: + schema: + $ref: '#/components/schemas/Drive' + required: true + responses: + "204": + description: Drive created/updated + content: {} + "400": + description: Drive cannot be created/updated due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + patch: + summary: Updates the properties of a drive. Post-boot only. + description: Updates the properties of the drive with the ID specified by drive_id + path parameter. Will fail if update is not possible. + operationId: patchGuestDriveByID + parameters: + - name: drive_id + in: path + description: The id of the guest drive + required: true + schema: + type: string + requestBody: + description: Guest drive properties + content: + application/json: + schema: + $ref: '#/components/schemas/PartialDrive' + required: true + responses: + "204": + description: Drive updated + content: {} + "400": + description: Drive cannot be updated due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /logger: + put: + summary: Initializes the logger by specifying a named pipe or a file for the + logs output. + operationId: putLogger + requestBody: + description: Logging system description + content: + application/json: + schema: + $ref: '#/components/schemas/Logger' + required: true + responses: + "204": + description: Logger created. + content: {} + "400": + description: Logger cannot be initialized due to bad input. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /machine-config: + get: + summary: Gets the machine configuration of the VM. + description: "Gets the machine configuration of the VM. When called before the\ + \ PUT operation, it will return the default values for the vCPU count (=1),\ + \ memory size (=128 MiB). By default SMT is disabled and there is no CPU Template." + operationId: getMachineConfiguration + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/MachineConfiguration' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + put: + summary: Updates the Machine Configuration of the VM. Pre-boot only. + description: "Updates the Virtual Machine Configuration with the specified input.\ + \ Firecracker starts with default values for vCPU count (=1) and memory size\ + \ (=128 MiB). The vCPU count is restricted to the [1, 32] range. With SMT\ + \ enabled, the vCPU count is required to be either 1 or an even number in\ + \ the range. otherwise there are no restrictions regarding the vCPU count.\ + \ If 2M hugetlbfs pages are specified, then `mem_size_mib` must be a multiple\ + \ of 2. If any of the parameters has an incorrect value, the whole update\ + \ fails. All parameters that are optional and are not specified are set to\ + \ their default values (smt = false, track_dirty_pages = false, cpu_template\ + \ = None, huge_pages = None)." + operationId: putMachineConfiguration + requestBody: + description: Machine Configuration Parameters + content: + application/json: + schema: + $ref: '#/components/schemas/MachineConfiguration' + required: false + responses: + "204": + description: Machine Configuration created/updated + content: {} + "400": + description: Machine Configuration cannot be updated due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + patch: + summary: Partially updates the Machine Configuration of the VM. Pre-boot only. + description: "Partially updates the Virtual Machine Configuration with the specified\ + \ input. If any of the parameters has an incorrect value, the whole update\ + \ fails." + operationId: patchMachineConfiguration + requestBody: + description: A subset of Machine Configuration Parameters + content: + application/json: + schema: + $ref: '#/components/schemas/MachineConfiguration' + required: false + responses: + "204": + description: Machine Configuration created/updated + content: {} + "400": + description: Machine Configuration cannot be updated due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /metrics: + put: + summary: Initializes the metrics system by specifying a named pipe or a file + for the metrics output. + operationId: putMetrics + requestBody: + description: Metrics system description + content: + application/json: + schema: + $ref: '#/components/schemas/Metrics' + required: true + responses: + "204": + description: Metrics system created. + content: {} + "400": + description: Metrics system cannot be initialized due to bad input request + or metrics system already initialized. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /mmds: + get: + summary: Get the MMDS data store. + operationId: getMmds + responses: + "200": + description: The MMDS data store JSON. + content: + application/json: + schema: + type: object + "404": + description: The MMDS data store content can not be found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + put: + summary: Creates a MMDS (Microvm Metadata Service) data store. + operationId: putMmds + requestBody: + description: The MMDS data store as JSON. + content: + application/json: + schema: + $ref: '#/components/schemas/MmdsContentsObject' + required: false + responses: + "204": + description: MMDS data store created/updated. + content: {} + "400": + description: MMDS data store cannot be created due to bad input. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + patch: + summary: Updates the MMDS data store. + operationId: patchMmds + requestBody: + description: The MMDS data store patch JSON. + content: + application/json: + schema: + $ref: '#/components/schemas/MmdsContentsObject' + required: false + responses: + "204": + description: MMDS data store updated. + content: {} + "400": + description: MMDS data store cannot be updated due to bad input. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /mmds/config: + put: + summary: Set MMDS configuration. Pre-boot only. + description: "Configures MMDS version, IPv4 address used by the MMDS network\ + \ stack and interfaces that allow MMDS requests." + operationId: putMmdsConfig + requestBody: + description: The MMDS configuration as JSON. + content: + application/json: + schema: + $ref: '#/components/schemas/MmdsConfig' + required: true + responses: + "204": + description: MMDS configuration was created/updated. + content: {} + "400": + description: MMDS configuration cannot be updated due to bad input. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /entropy: + put: + summary: Creates an entropy device. Pre-boot only. + description: Enables an entropy device that provides high-quality random data + to the guest. + operationId: putEntropyDevice + requestBody: + description: Guest entropy device properties + content: + application/json: + schema: + $ref: '#/components/schemas/EntropyDevice' + required: true + responses: + "204": + description: Entropy device created + content: {} + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /network-interfaces/{iface_id}: + put: + summary: Creates a network interface. Pre-boot only. + description: Creates new network interface with ID specified by iface_id path + parameter. + operationId: putGuestNetworkInterfaceByID + parameters: + - name: iface_id + in: path + description: The id of the guest network interface + required: true + schema: + type: string + requestBody: + description: Guest network interface properties + content: + application/json: + schema: + $ref: '#/components/schemas/NetworkInterface' + required: true + responses: + "204": + description: Network interface created/updated + content: {} + "400": + description: Network interface cannot be created due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + patch: + summary: Updates the rate limiters applied to a network interface. Post-boot + only. + description: Updates the rate limiters applied to a network interface. + operationId: patchGuestNetworkInterfaceByID + parameters: + - name: iface_id + in: path + description: The id of the guest network interface + required: true + schema: + type: string + requestBody: + description: A subset of the guest network interface properties + content: + application/json: + schema: + $ref: '#/components/schemas/PartialNetworkInterface' + required: true + responses: + "204": + description: Network interface updated + content: {} + "400": + description: Network interface cannot be updated due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /snapshot/create: + put: + summary: Creates a full or diff snapshot. Post-boot only. + description: Creates a snapshot of the microVM state. The microVM should be + in the `Paused` state. + operationId: createSnapshot + requestBody: + description: The configuration used for creating a snaphot. + content: + application/json: + schema: + $ref: '#/components/schemas/SnapshotCreateParams' + required: true + responses: + "204": + description: Snapshot created + content: {} + "400": + description: Snapshot cannot be created due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /snapshot/load: + put: + summary: Loads a snapshot. Pre-boot only. + description: Loads the microVM state from a snapshot. Only accepted on a fresh + Firecracker process (before configuring any resource other than the Logger + and Metrics). + operationId: loadSnapshot + requestBody: + description: The configuration used for loading a snaphot. + content: + application/json: + schema: + $ref: '#/components/schemas/SnapshotLoadParams' + required: true + responses: + "204": + description: Snapshot loaded + content: {} + "400": + description: Snapshot cannot be loaded due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /version: + get: + summary: Gets the Firecracker version. + operationId: getFirecrackerVersion + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/FirecrackerVersion' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /vm: + patch: + summary: Updates the microVM state. + description: Sets the desired state (Paused or Resumed) for the microVM. + operationId: patchVm + requestBody: + description: The microVM state + content: + application/json: + schema: + $ref: '#/components/schemas/Vm' + required: true + responses: + "204": + description: Vm state updated + content: {} + "400": + description: Vm state cannot be updated due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body + /vm/config: + get: + summary: Gets the full VM configuration. + description: "Gets configuration for all VM resources. If the VM is restored\ + \ from a snapshot, the boot-source, machine-config.smt and machine-config.cpu_template\ + \ will be empty." + operationId: getExportVmConfig + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/FullVmConfiguration' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /vsock: + put: + summary: Creates/updates a vsock device. Pre-boot only. + description: The first call creates the device with the configuration specified + in body. Subsequent calls will update the device configuration. May fail if + update is not possible. + operationId: putGuestVsock + requestBody: + description: Guest vsock properties + content: + application/json: + schema: + $ref: '#/components/schemas/Vsock' + required: true + responses: + "204": + description: Vsock created/updated + content: {} + "400": + description: Vsock cannot be created due to bad input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: body +components: + schemas: + Balloon: + required: + - amount_mib + - deflate_on_oom + type: object + properties: + amount_mib: + type: integer + description: Target balloon size in MiB. + deflate_on_oom: + type: boolean + description: Whether the balloon should deflate when the guest has memory + pressure. + stats_polling_interval_s: + type: integer + description: Interval in seconds between refreshing statistics. A non-zero + value will enable the statistics. Defaults to 0. + description: Balloon device descriptor. + BalloonUpdate: + required: + - amount_mib + type: object + properties: + amount_mib: + type: integer + description: Target balloon size in MiB. + description: Balloon device descriptor. + BalloonStats: + required: + - actual_mib + - actual_pages + - target_mib + - target_pages + type: object + properties: + target_pages: + type: integer + description: Target number of pages the device aims to hold. + actual_pages: + type: integer + description: Actual number of pages the device is holding. + target_mib: + type: integer + description: Target amount of memory (in MiB) the device aims to hold. + actual_mib: + type: integer + description: Actual amount of memory (in MiB) the device is holding. + swap_in: + type: integer + description: The amount of memory that has been swapped in (in bytes). + format: int64 + swap_out: + type: integer + description: The amount of memory that has been swapped out to disk (in + bytes). + format: int64 + major_faults: + type: integer + description: The number of major page faults that have occurred. + format: int64 + minor_faults: + type: integer + description: The number of minor page faults that have occurred. + format: int64 + free_memory: + type: integer + description: The amount of memory not being used for any purpose (in bytes). + format: int64 + total_memory: + type: integer + description: The total amount of memory available (in bytes). + format: int64 + available_memory: + type: integer + description: "An estimate of how much memory is available (in bytes) for\ + \ starting new applications, without pushing the system to swap." + format: int64 + disk_caches: + type: integer + description: "The amount of memory, in bytes, that can be quickly reclaimed\ + \ without additional I/O. Typically these pages are used for caching files\ + \ from disk." + format: int64 + hugetlb_allocations: + type: integer + description: The number of successful hugetlb page allocations in the guest. + format: int64 + hugetlb_failures: + type: integer + description: The number of failed hugetlb page allocations in the guest. + format: int64 + description: Describes the balloon device statistics. + BalloonStatsUpdate: + required: + - stats_polling_interval_s + type: object + properties: + stats_polling_interval_s: + type: integer + description: Interval in seconds between refreshing statistics. + description: "Update the statistics polling interval, with the first statistics\ + \ update scheduled immediately. Statistics cannot be turned on/off after boot." + BootSource: + required: + - kernel_image_path + type: object + properties: + boot_args: + type: string + description: Kernel boot arguments + initrd_path: + type: string + description: Host level path to the initrd image used to boot the guest + kernel_image_path: + type: string + description: Host level path to the kernel image used to boot the guest + description: Boot source descriptor. + CpuTemplate: + type: string + description: The CPU Template defines a set of flags to be disabled from the + microvm so that the features exposed to the guest are the same as in the selected + instance type. This parameter has been deprecated and it will be removed in + future Firecracker release. + default: None + enum: + - C3 + - T2 + - T2S + - T2CL + - T2A + - V1N1 + - None + CpuConfig: + type: string + properties: + cpuid_modifiers: + type: object + properties: {} + description: A collection of CPUIDs to be modified. (x86_64) + msr_modifiers: + type: object + properties: {} + description: A collection of model specific registers to be modified. (x86_64) + reg_modifiers: + type: object + properties: {} + description: A collection of registers to be modified. (aarch64) + description: The CPU configuration template defines a set of bit maps as modifiers + of flags accessed by register to be disabled/enabled for the microvm. + Drive: + required: + - drive_id + - is_root_device + type: object + properties: + drive_id: + type: string + partuuid: + type: string + description: Represents the unique id of the boot partition of this device. + It is optional and it will be taken into account only if the is_root_device + field is true. + is_root_device: + type: boolean + cache_type: + type: string + description: Represents the caching strategy for the block device. + default: Unsafe + enum: + - Unsafe + - Writeback + is_read_only: + type: boolean + description: Is block read only. This field is required for virtio-block + config and should be omitted for vhost-user-block configuration. + path_on_host: + type: string + description: Host level path for the guest drive. This field is required + for virtio-block config and should be omitted for vhost-user-block configuration. + rate_limiter: + $ref: '#/components/schemas/RateLimiter' + io_engine: + type: string + description: Type of the IO engine used by the device. "Async" is supported + on host kernels newer than 5.10.51. This field is optional for virtio-block + config and should be omitted for vhost-user-block configuration. + default: Sync + enum: + - Sync + - Async + socket: + type: string + description: Path to the socket of vhost-user-block backend. This field + is required for vhost-user-block config should be omitted for virtio-block + configuration. + Error: + type: object + properties: + fault_message: + type: string + description: A description of the error condition + readOnly: true + FullVmConfiguration: + type: object + properties: + balloon: + $ref: '#/components/schemas/Balloon' + drives: + type: array + description: Configurations for all block devices. + items: + $ref: '#/components/schemas/Drive' + boot-source: + $ref: '#/components/schemas/BootSource' + logger: + $ref: '#/components/schemas/Logger' + machine-config: + $ref: '#/components/schemas/MachineConfiguration' + metrics: + $ref: '#/components/schemas/Metrics' + mmds-config: + $ref: '#/components/schemas/MmdsConfig' + network-interfaces: + type: array + description: Configurations for all net devices. + items: + $ref: '#/components/schemas/NetworkInterface' + vsock: + $ref: '#/components/schemas/Vsock' + InstanceActionInfo: + required: + - action_type + type: object + properties: + action_type: + type: string + description: Enumeration indicating what type of action is contained in + the payload + enum: + - FlushMetrics + - InstanceStart + - SendCtrlAltDel + description: Variant wrapper containing the real action. + InstanceInfo: + required: + - app_name + - id + - state + - vmm_version + type: object + properties: + app_name: + type: string + description: Application name. + id: + type: string + description: MicroVM / instance ID. + state: + type: string + description: "The current detailed state (Not started, Running, Paused)\ + \ of the Firecracker instance. This value is read-only for the control-plane." + enum: + - Not started + - Running + - Paused + vmm_version: + type: string + description: MicroVM hypervisor build version. + description: Describes MicroVM instance information. + Logger: + type: object + properties: + level: + type: string + description: Set the level. The possible values are case-insensitive. + default: Info + enum: + - Error + - Warning + - Info + - Debug + - Trace + log_path: + type: string + description: Path to the named pipe or file for the human readable log output. + show_level: + type: boolean + description: Whether or not to output the level in the logs. + default: false + show_log_origin: + type: boolean + description: Whether or not to include the file path and line number of + the log's origin. + default: false + module: + type: string + description: The module path to filter log messages by. + examples: + - api_server::request + description: Describes the configuration option for the logging capability. + MachineConfiguration: + required: + - mem_size_mib + - vcpu_count + type: object + properties: + cpu_template: + $ref: '#/components/schemas/CpuTemplate' + smt: + type: boolean + description: Flag for enabling/disabling simultaneous multithreading. Can + be enabled only on x86. + default: false + mem_size_mib: + type: integer + description: Memory size of VM + track_dirty_pages: + type: boolean + description: "Enable dirty page tracking. If this is enabled, then incremental\ + \ guest memory snapshots can be created. These belong to diff snapshots,\ + \ which contain, besides the microVM state, only the memory dirtied since\ + \ a previous snapshot. Full snapshots each contain a full copy of the\ + \ guest memory." + default: false + vcpu_count: + maximum: 32 + minimum: 1 + type: integer + description: Number of vCPUs (either 1 or an even number) + huge_pages: + type: string + description: Which huge pages configuration (if any) should be used to back + guest memory. + enum: + - None + - 2M + description: "Describes the number of vCPUs, memory size, SMT capabilities,\ + \ huge page configuration and the CPU template." + MemoryBackend: + required: + - backend_path + - backend_type + type: object + properties: + backend_type: + type: string + enum: + - File + - Uffd + backend_path: + type: string + description: Based on 'backend_type' it is either 1) Path to the file that + contains the guest memory to be loaded 2) Path to the UDS where a process + is listening for a UFFD initialization control payload and open file descriptor + that it can use to serve this process's guest memory page faults + Metrics: + required: + - metrics_path + type: object + properties: + metrics_path: + type: string + description: Path to the named pipe or file where the JSON-formatted metrics + are flushed. + description: Describes the configuration option for the metrics capability. + MmdsConfig: + required: + - network_interfaces + type: object + properties: + version: + type: string + description: Enumeration indicating the MMDS version to be configured. + default: V1 + enum: + - V1 + - V2 + network_interfaces: + type: array + description: "List of the network interface IDs capable of forwarding packets\ + \ to the MMDS. Network interface IDs mentioned must be valid at the time\ + \ of this request. The net device model will reply to HTTP GET requests\ + \ sent to the MMDS address via the interfaces mentioned. In this case,\ + \ both ARP requests and TCP segments heading to `ipv4_address` are intercepted\ + \ by the device model, and do not reach the associated TAP device." + items: + type: string + ipv4_address: + type: string + description: A valid IPv4 link-local address. + format: "169.254.([1-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-4]).([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])" + default: 169.254.169.254 + description: Defines the MMDS configuration. + MmdsContentsObject: + type: object + description: Describes the contents of MMDS in JSON format. + NetworkInterface: + required: + - host_dev_name + - iface_id + type: object + properties: + guest_mac: + type: string + host_dev_name: + type: string + description: Host level path for the guest network interface + iface_id: + type: string + rx_rate_limiter: + $ref: '#/components/schemas/RateLimiter' + tx_rate_limiter: + $ref: '#/components/schemas/RateLimiter' + description: Defines a network interface. + PartialDrive: + required: + - drive_id + type: object + properties: + drive_id: + type: string + path_on_host: + type: string + description: Host level path for the guest drive. This field is optional + for virtio-block config and should be omitted for vhost-user-block configuration. + rate_limiter: + $ref: '#/components/schemas/RateLimiter' + PartialNetworkInterface: + required: + - iface_id + type: object + properties: + iface_id: + type: string + rx_rate_limiter: + $ref: '#/components/schemas/RateLimiter' + tx_rate_limiter: + $ref: '#/components/schemas/RateLimiter' + description: "Defines a partial network interface structure, used to update\ + \ the rate limiters for that interface, after microvm start." + RateLimiter: + type: object + properties: + bandwidth: + $ref: '#/components/schemas/TokenBucket' + ops: + $ref: '#/components/schemas/TokenBucket' + description: Defines an IO rate limiter with independent bytes/s and ops/s limits. + Limits are defined by configuring each of the _bandwidth_ and _ops_ token + buckets. This field is optional for virtio-block config and should be omitted + for vhost-user-block configuration. + SnapshotCreateParams: + required: + - mem_file_path + - snapshot_path + type: object + properties: + mem_file_path: + type: string + description: Path to the file that will contain the guest memory. + snapshot_path: + type: string + description: Path to the file that will contain the microVM state. + snapshot_type: + type: string + description: "Type of snapshot to create. It is optional and by default,\ + \ a full snapshot is created." + enum: + - Full + - Diff + SnapshotLoadParams: + required: + - snapshot_path + type: object + properties: + enable_diff_snapshots: + type: boolean + description: Enable support for incremental (diff) snapshots by tracking + dirty guest pages. + mem_file_path: + type: string + description: Path to the file that contains the guest memory to be loaded. + It is only allowed if `mem_backend` is not present. This parameter has + been deprecated and it will be removed in future Firecracker release. + mem_backend: + $ref: '#/components/schemas/MemoryBackend' + snapshot_path: + type: string + description: Path to the file that contains the microVM state to be loaded. + resume_vm: + type: boolean + description: "When set to true, the vm is also resumed if the snapshot load\ + \ is successful." + description: Defines the configuration used for handling snapshot resume. Exactly + one of the two `mem_*` fields must be present in the body of the request. + TokenBucket: + required: + - refill_time + - size + type: object + properties: + one_time_burst: + minimum: 0 + type: integer + description: The initial size of a token bucket. + format: int64 + refill_time: + minimum: 0 + type: integer + description: The amount of milliseconds it takes for the bucket to refill. + format: int64 + size: + minimum: 0 + type: integer + description: The total number of tokens this bucket can hold. + format: int64 + description: "Defines a token bucket with a maximum capacity (size), an initial\ + \ burst size (one_time_burst) and an interval for refilling purposes (refill_time).\ + \ The refill-rate is derived from size and refill_time, and it is the constant\ + \ rate at which the tokens replenish. The refill process only starts happening\ + \ after the initial burst budget is consumed. Consumption from the token bucket\ + \ is unbounded in speed which allows for bursts bound in size by the amount\ + \ of tokens available. Once the token bucket is empty, consumption speed is\ + \ bound by the refill_rate." + Vm: + required: + - state + type: object + properties: + state: + type: string + enum: + - Paused + - Resumed + description: Defines the microVM running state. It is especially useful in the + snapshotting context. + EntropyDevice: + type: object + properties: + rate_limiter: + $ref: '#/components/schemas/RateLimiter' + description: Defines an entropy device. + FirecrackerVersion: + required: + - firecracker_version + type: object + properties: + firecracker_version: + type: string + description: Firecracker build version. + description: Describes the Firecracker version. + Vsock: + required: + - guest_cid + - uds_path + type: object + properties: + guest_cid: + minimum: 3 + type: integer + description: Guest Vsock CID + uds_path: + type: string + description: "Path to UNIX domain socket, used to proxy vsock connections." + vsock_id: + type: string + description: This parameter has been deprecated and it will be removed in + future Firecracker release. + description: "Defines a vsock device, backed by a set of Unix Domain Sockets,\ + \ on the host side. For host-initiated connections, Firecracker will be listening\ + \ on the Unix socket identified by the path `uds_path`. Firecracker will create\ + \ this socket, bind and listen on it. Host-initiated connections will be performed\ + \ by connection to this socket and issuing a connection forwarding request\ + \ to the desired guest-side vsock port (i.e. `CONNECT 52\\n`, to connect to\ + \ port 52). For guest-initiated connections, Firecracker will expect host\ + \ software to be bound and listening on Unix sockets at `uds_path_`.\ + \ E.g. \"/path/to/host_vsock.sock_52\" for port number 52." +x-original-swagger-version: "2.0" diff --git a/src/firecracker/swagger/firecracker.yaml b/src/firecracker/swagger/firecracker.yaml deleted file mode 100644 index 61c7a28caab..00000000000 --- a/src/firecracker/swagger/firecracker.yaml +++ /dev/null @@ -1,1328 +0,0 @@ -swagger: "2.0" -info: - title: Firecracker API - description: RESTful public-facing API. - The API is accessible through HTTP calls on specific URLs - carrying JSON modeled data. - The transport medium is a Unix Domain Socket. - version: 1.10.0-dev - termsOfService: "" - contact: - email: "compute-capsule@amazon.com" - license: - name: "Apache 2.0" - url: "http://www.apache.org/licenses/LICENSE-2.0.html" - -host: "localhost" -basePath: "/" - -schemes: - - http -consumes: - - application/json -produces: - - application/json - -paths: - /: - get: - summary: Returns general information about an instance. - operationId: describeInstance - responses: - 200: - description: The instance information - schema: - $ref: "#/definitions/InstanceInfo" - default: - description: Internal Server Error - schema: - $ref: "#/definitions/Error" - - /actions: - put: - summary: Creates a synchronous action. - operationId: createSyncAction - parameters: - - name: info - in: body - required: true - schema: - $ref: "#/definitions/InstanceActionInfo" - responses: - 204: - description: The update was successful - 400: - description: The action cannot be executed due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal Server Error - schema: - $ref: "#/definitions/Error" - - /balloon: - get: - summary: Returns the current balloon device configuration. - operationId: describeBalloonConfig - responses: - 200: - description: The balloon device configuration - schema: - $ref: "#/definitions/Balloon" - 400: - description: Balloon device not configured. - schema: - $ref: "#/definitions/Error" - default: - description: Internal Server Error - schema: - $ref: "#/definitions/Error" - put: - summary: Creates or updates a balloon device. - description: - Creates a new balloon device if one does not already exist, otherwise updates it, before machine startup. - This will fail after machine startup. - Will fail if update is not possible. - operationId: putBalloon - parameters: - - name: body - in: body - description: Balloon properties - required: true - schema: - $ref: "#/definitions/Balloon" - responses: - 204: - description: Balloon device created/updated - 400: - description: Balloon device cannot be created/updated due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - patch: - summary: Updates a balloon device. - description: - Updates an existing balloon device, before or after machine startup. - Will fail if update is not possible. - operationId: patchBalloon - parameters: - - name: body - in: body - description: Balloon properties - required: true - schema: - $ref: "#/definitions/BalloonUpdate" - responses: - 204: - description: Balloon device updated - 400: - description: Balloon device cannot be updated due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /balloon/statistics: - get: - summary: Returns the latest balloon device statistics, only if enabled pre-boot. - operationId: describeBalloonStats - responses: - 200: - description: The balloon device statistics - schema: - $ref: "#/definitions/BalloonStats" - 400: - description: The balloon device statistics were not enabled when the device was configured. - schema: - $ref: "#/definitions/Error" - default: - description: Internal Server Error - schema: - $ref: "#/definitions/Error" - patch: - summary: Updates a balloon device statistics polling interval. - description: - Updates an existing balloon device statistics interval, before or after machine startup. - Will fail if update is not possible. - operationId: patchBalloonStatsInterval - parameters: - - name: body - in: body - description: Balloon properties - required: true - schema: - $ref: "#/definitions/BalloonStatsUpdate" - responses: - 204: - description: Balloon statistics interval updated - 400: - description: Balloon statistics interval cannot be updated due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /boot-source: - put: - summary: Creates or updates the boot source. Pre-boot only. - description: - Creates new boot source if one does not already exist, otherwise updates it. - Will fail if update is not possible. - operationId: putGuestBootSource - parameters: - - name: body - in: body - description: Guest boot source properties - required: true - schema: - $ref: "#/definitions/BootSource" - responses: - 204: - description: Boot source created/updated - 400: - description: Boot source cannot be created due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /cpu-config: - put: - summary: Configures CPU features flags for the vCPUs of the guest VM. Pre-boot only. - description: - Provides configuration to the Firecracker process to specify vCPU resource configuration prior to - launching the guest machine. - operationId: putCpuConfiguration - parameters: - - name: body - in: body - description: CPU configuration request - schema: - $ref: "#/definitions/CpuConfig" - responses: - 204: - description: CPU configuration set successfully - 400: - description: CPU configuration cannot be updated due to invalid input format - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - - /drives/{drive_id}: - put: - summary: Creates or updates a drive. Pre-boot only. - description: - Creates new drive with ID specified by drive_id path parameter. - If a drive with the specified ID already exists, updates its state based on new input. - Will fail if update is not possible. - operationId: putGuestDriveByID - parameters: - - name: drive_id - in: path - description: The id of the guest drive - required: true - type: string - - name: body - in: body - description: Guest drive properties - required: true - schema: - $ref: "#/definitions/Drive" - responses: - 204: - description: Drive created/updated - 400: - description: Drive cannot be created/updated due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error. - schema: - $ref: "#/definitions/Error" - patch: - summary: Updates the properties of a drive. Post-boot only. - description: - Updates the properties of the drive with the ID specified by drive_id path parameter. - Will fail if update is not possible. - operationId: patchGuestDriveByID - parameters: - - name: drive_id - in: path - description: The id of the guest drive - required: true - type: string - - name: body - in: body - description: Guest drive properties - required: true - schema: - $ref: "#/definitions/PartialDrive" - responses: - 204: - description: Drive updated - 400: - description: Drive cannot be updated due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error. - schema: - $ref: "#/definitions/Error" - - /logger: - put: - summary: Initializes the logger by specifying a named pipe or a file for the logs output. - operationId: putLogger - parameters: - - name: body - in: body - description: Logging system description - required: true - schema: - $ref: "#/definitions/Logger" - responses: - 204: - description: Logger created. - 400: - description: Logger cannot be initialized due to bad input. - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error. - schema: - $ref: "#/definitions/Error" - - /machine-config: - get: - summary: Gets the machine configuration of the VM. - description: - Gets the machine configuration of the VM. When called before the PUT operation, it - will return the default values for the vCPU count (=1), memory size (=128 MiB). - By default SMT is disabled and there is no CPU Template. - operationId: getMachineConfiguration - responses: - 200: - description: OK - schema: - $ref: "#/definitions/MachineConfiguration" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - put: - summary: Updates the Machine Configuration of the VM. Pre-boot only. - description: - Updates the Virtual Machine Configuration with the specified input. - Firecracker starts with default values for vCPU count (=1) and memory size (=128 MiB). - The vCPU count is restricted to the [1, 32] range. - With SMT enabled, the vCPU count is required to be either 1 or an even number in the range. - otherwise there are no restrictions regarding the vCPU count. - If 2M hugetlbfs pages are specified, then `mem_size_mib` must be a multiple of 2. - If any of the parameters has an incorrect value, the whole update fails. - All parameters that are optional and are not specified are set to their default values - (smt = false, track_dirty_pages = false, cpu_template = None, huge_pages = None). - operationId: putMachineConfiguration - parameters: - - name: body - in: body - description: Machine Configuration Parameters - schema: - $ref: "#/definitions/MachineConfiguration" - responses: - 204: - description: Machine Configuration created/updated - 400: - description: Machine Configuration cannot be updated due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - patch: - summary: Partially updates the Machine Configuration of the VM. Pre-boot only. - description: - Partially updates the Virtual Machine Configuration with the specified input. - If any of the parameters has an incorrect value, the whole update fails. - operationId: patchMachineConfiguration - parameters: - - name: body - in: body - description: A subset of Machine Configuration Parameters - schema: - $ref: "#/definitions/MachineConfiguration" - responses: - 204: - description: Machine Configuration created/updated - 400: - description: Machine Configuration cannot be updated due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /metrics: - put: - summary: Initializes the metrics system by specifying a named pipe or a file for the metrics output. - operationId: putMetrics - parameters: - - name: body - in: body - description: Metrics system description - required: true - schema: - $ref: "#/definitions/Metrics" - responses: - 204: - description: Metrics system created. - 400: - description: Metrics system cannot be initialized due to bad input request or metrics system already initialized. - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error. - schema: - $ref: "#/definitions/Error" - - /mmds: - put: - summary: Creates a MMDS (Microvm Metadata Service) data store. - operationId: putMmds - parameters: - - name: body - in: body - description: The MMDS data store as JSON. - schema: - $ref: "#/definitions/MmdsContentsObject" - responses: - 204: - description: MMDS data store created/updated. - 400: - description: MMDS data store cannot be created due to bad input. - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - patch: - summary: Updates the MMDS data store. - operationId: patchMmds - parameters: - - name: body - in: body - description: The MMDS data store patch JSON. - schema: - $ref: "#/definitions/MmdsContentsObject" - responses: - 204: - description: MMDS data store updated. - 400: - description: MMDS data store cannot be updated due to bad input. - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - get: - summary: Get the MMDS data store. - operationId: getMmds - responses: - 200: - description: The MMDS data store JSON. - schema: - type: object - 404: - description: The MMDS data store content can not be found. - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /mmds/config: - put: - summary: Set MMDS configuration. Pre-boot only. - operationId: putMmdsConfig - description: - Configures MMDS version, IPv4 address used by the MMDS network stack - and interfaces that allow MMDS requests. - parameters: - - name: body - in: body - description: The MMDS configuration as JSON. - required: true - schema: - $ref: "#/definitions/MmdsConfig" - responses: - 204: - description: MMDS configuration was created/updated. - 400: - description: MMDS configuration cannot be updated due to bad input. - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /entropy: - put: - summary: Creates an entropy device. Pre-boot only. - description: - Enables an entropy device that provides high-quality random data to the guest. - operationId: putEntropyDevice - parameters: - - name: body - in: body - description: Guest entropy device properties - required: true - schema: - $ref: "#/definitions/EntropyDevice" - responses: - 204: - description: Entropy device created - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - - /network-interfaces/{iface_id}: - put: - summary: Creates a network interface. Pre-boot only. - description: - Creates new network interface with ID specified by iface_id path parameter. - operationId: putGuestNetworkInterfaceByID - parameters: - - name: iface_id - in: path - description: The id of the guest network interface - required: true - type: string - - name: body - in: body - description: Guest network interface properties - required: true - schema: - $ref: "#/definitions/NetworkInterface" - responses: - 204: - description: Network interface created/updated - 400: - description: Network interface cannot be created due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - patch: - summary: Updates the rate limiters applied to a network interface. Post-boot only. - description: - Updates the rate limiters applied to a network interface. - operationId: patchGuestNetworkInterfaceByID - parameters: - - name: iface_id - in: path - description: The id of the guest network interface - required: true - type: string - - name: body - in: body - description: A subset of the guest network interface properties - required: true - schema: - $ref: "#/definitions/PartialNetworkInterface" - responses: - 204: - description: Network interface updated - 400: - description: Network interface cannot be updated due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /snapshot/create: - put: - summary: Creates a full or diff snapshot. Post-boot only. - description: - Creates a snapshot of the microVM state. The microVM should be - in the `Paused` state. - operationId: createSnapshot - parameters: - - name: body - in: body - description: The configuration used for creating a snaphot. - required: true - schema: - $ref: "#/definitions/SnapshotCreateParams" - responses: - 204: - description: Snapshot created - 400: - description: Snapshot cannot be created due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /snapshot/load: - put: - summary: Loads a snapshot. Pre-boot only. - description: - Loads the microVM state from a snapshot. - Only accepted on a fresh Firecracker process (before configuring - any resource other than the Logger and Metrics). - operationId: loadSnapshot - parameters: - - name: body - in: body - description: The configuration used for loading a snaphot. - required: true - schema: - $ref: "#/definitions/SnapshotLoadParams" - responses: - 204: - description: Snapshot loaded - 400: - description: Snapshot cannot be loaded due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /version: - get: - summary: Gets the Firecracker version. - operationId: getFirecrackerVersion - responses: - 200: - description: OK - schema: - $ref: "#/definitions/FirecrackerVersion" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /vm: - patch: - summary: Updates the microVM state. - description: - Sets the desired state (Paused or Resumed) for the microVM. - operationId: patchVm - parameters: - - name: body - in: body - description: The microVM state - required: true - schema: - $ref: "#/definitions/Vm" - responses: - 204: - description: Vm state updated - 400: - description: Vm state cannot be updated due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /vm/config: - get: - summary: Gets the full VM configuration. - description: - Gets configuration for all VM resources. If the VM is restored from a snapshot, the boot-source, - machine-config.smt and machine-config.cpu_template will be empty. - operationId: getExportVmConfig - responses: - 200: - description: OK - schema: - $ref: "#/definitions/FullVmConfiguration" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - - /vsock: - put: - summary: Creates/updates a vsock device. Pre-boot only. - description: - The first call creates the device with the configuration specified - in body. Subsequent calls will update the device configuration. - May fail if update is not possible. - operationId: putGuestVsock - parameters: - - name: body - in: body - description: Guest vsock properties - required: true - schema: - $ref: "#/definitions/Vsock" - responses: - 204: - description: Vsock created/updated - 400: - description: Vsock cannot be created due to bad input - schema: - $ref: "#/definitions/Error" - default: - description: Internal server error - schema: - $ref: "#/definitions/Error" - -definitions: - Balloon: - type: object - required: - - amount_mib - - deflate_on_oom - description: - Balloon device descriptor. - properties: - amount_mib: - type: integer - description: Target balloon size in MiB. - deflate_on_oom: - type: boolean - description: Whether the balloon should deflate when the guest has memory pressure. - stats_polling_interval_s: - type: integer - description: Interval in seconds between refreshing statistics. A non-zero value will enable the statistics. Defaults to 0. - - BalloonUpdate: - type: object - required: - - amount_mib - description: - Balloon device descriptor. - properties: - amount_mib: - type: integer - description: Target balloon size in MiB. - - BalloonStats: - type: object - description: - Describes the balloon device statistics. - required: - - target_pages - - actual_pages - - target_mib - - actual_mib - properties: - target_pages: - description: Target number of pages the device aims to hold. - type: integer - actual_pages: - description: Actual number of pages the device is holding. - type: integer - target_mib: - description: Target amount of memory (in MiB) the device aims to hold. - type: integer - actual_mib: - description: Actual amount of memory (in MiB) the device is holding. - type: integer - swap_in: - description: The amount of memory that has been swapped in (in bytes). - type: integer - format: int64 - swap_out: - description: The amount of memory that has been swapped out to disk (in bytes). - type: integer - format: int64 - major_faults: - description: The number of major page faults that have occurred. - type: integer - format: int64 - minor_faults: - description: The number of minor page faults that have occurred. - type: integer - format: int64 - free_memory: - description: The amount of memory not being used for any purpose (in bytes). - type: integer - format: int64 - total_memory: - description: The total amount of memory available (in bytes). - type: integer - format: int64 - available_memory: - description: An estimate of how much memory is available (in bytes) for starting new applications, without pushing the system to swap. - type: integer - format: int64 - disk_caches: - description: The amount of memory, in bytes, that can be quickly reclaimed without additional I/O. Typically these pages are used for caching files from disk. - type: integer - format: int64 - hugetlb_allocations: - description: The number of successful hugetlb page allocations in the guest. - type: integer - format: int64 - hugetlb_failures: - description: The number of failed hugetlb page allocations in the guest. - type: integer - format: int64 - - BalloonStatsUpdate: - type: object - required: - - stats_polling_interval_s - description: - Update the statistics polling interval, with the first statistics update scheduled immediately. Statistics cannot be turned on/off after boot. - properties: - stats_polling_interval_s: - type: integer - description: Interval in seconds between refreshing statistics. - - BootSource: - type: object - required: - - kernel_image_path - description: - Boot source descriptor. - properties: - boot_args: - type: string - description: Kernel boot arguments - initrd_path: - type: string - description: Host level path to the initrd image used to boot the guest - kernel_image_path: - type: string - description: Host level path to the kernel image used to boot the guest - - CpuTemplate: - type: string - description: - The CPU Template defines a set of flags to be disabled from the microvm so that - the features exposed to the guest are the same as in the selected instance type. - This parameter has been deprecated and it will be removed in future Firecracker - release. - enum: - - C3 - - T2 - - T2S - - T2CL - - T2A - - V1N1 - - None - default: "None" - - CpuConfig: - type: string - description: - The CPU configuration template defines a set of bit maps as modifiers of flags accessed by register - to be disabled/enabled for the microvm. - properties: - cpuid_modifiers: - type: object - description: A collection of CPUIDs to be modified. (x86_64) - msr_modifiers: - type: object - description: A collection of model specific registers to be modified. (x86_64) - reg_modifiers: - type: object - description: A collection of registers to be modified. (aarch64) - - Drive: - type: object - required: - - drive_id - - is_root_device - properties: - drive_id: - type: string - partuuid: - type: string - description: - Represents the unique id of the boot partition of this device. It is - optional and it will be taken into account only if the is_root_device - field is true. - is_root_device: - type: boolean - cache_type: - type: string - description: - Represents the caching strategy for the block device. - enum: ["Unsafe", "Writeback"] - default: "Unsafe" - - # VirtioBlock specific parameters - is_read_only: - type: boolean - description: - Is block read only. - This field is required for virtio-block config and should be omitted for vhost-user-block configuration. - path_on_host: - type: string - description: - Host level path for the guest drive. - This field is required for virtio-block config and should be omitted for vhost-user-block configuration. - rate_limiter: - $ref: "#/definitions/RateLimiter" - io_engine: - type: string - description: - Type of the IO engine used by the device. "Async" is supported on - host kernels newer than 5.10.51. - This field is optional for virtio-block config and should be omitted for vhost-user-block configuration. - enum: ["Sync", "Async"] - default: "Sync" - - # VhostUserBlock specific parameters - socket: - type: string - description: - Path to the socket of vhost-user-block backend. - This field is required for vhost-user-block config should be omitted for virtio-block configuration. - - Error: - type: object - properties: - fault_message: - type: string - description: A description of the error condition - readOnly: true - - FullVmConfiguration: - type: object - properties: - balloon: - $ref: "#/definitions/Balloon" - drives: - type: array - description: Configurations for all block devices. - items: - $ref: "#/definitions/Drive" - boot-source: - $ref: "#/definitions/BootSource" - logger: - $ref: "#/definitions/Logger" - machine-config: - $ref: "#/definitions/MachineConfiguration" - metrics: - $ref: "#/definitions/Metrics" - mmds-config: - $ref: "#/definitions/MmdsConfig" - network-interfaces: - type: array - description: Configurations for all net devices. - items: - $ref: "#/definitions/NetworkInterface" - vsock: - $ref: "#/definitions/Vsock" - - InstanceActionInfo: - type: object - description: - Variant wrapper containing the real action. - required: - - action_type - properties: - action_type: - description: Enumeration indicating what type of action is contained in the payload - type: string - enum: - - FlushMetrics - - InstanceStart - - SendCtrlAltDel - - InstanceInfo: - type: object - description: - Describes MicroVM instance information. - required: - - app_name - - id - - state - - vmm_version - properties: - app_name: - description: Application name. - type: string - id: - description: MicroVM / instance ID. - type: string - state: - description: - The current detailed state (Not started, Running, Paused) of the Firecracker instance. - This value is read-only for the control-plane. - type: string - enum: - - Not started - - Running - - Paused - vmm_version: - description: MicroVM hypervisor build version. - type: string - - Logger: - type: object - description: - Describes the configuration option for the logging capability. - properties: - level: - type: string - description: Set the level. The possible values are case-insensitive. - enum: [Error, Warning, Info, Debug, Trace, Off] - default: Info - log_path: - type: string - description: Path to the named pipe or file for the human readable log output. - show_level: - type: boolean - description: Whether or not to output the level in the logs. - default: false - show_log_origin: - type: boolean - description: Whether or not to include the file path and line number of the log's origin. - default: false - module: - type: string - description: The module path to filter log messages by. - example: api_server::request - - MachineConfiguration: - type: object - description: - Describes the number of vCPUs, memory size, SMT capabilities, huge page configuration and - the CPU template. - required: - - mem_size_mib - - vcpu_count - properties: - cpu_template: - $ref: "#/definitions/CpuTemplate" - smt: - type: boolean - description: Flag for enabling/disabling simultaneous multithreading. Can be enabled only on x86. - default: false - mem_size_mib: - type: integer - description: Memory size of VM - track_dirty_pages: - type: boolean - description: - Enable dirty page tracking. If this is enabled, then incremental guest memory - snapshots can be created. These belong to diff snapshots, which contain, besides - the microVM state, only the memory dirtied since a previous snapshot. Full snapshots - each contain a full copy of the guest memory. - default: false - vcpu_count: - type: integer - minimum: 1 - maximum: 32 - description: Number of vCPUs (either 1 or an even number) - huge_pages: - type: string - enum: - - None - - 2M - description: Which huge pages configuration (if any) should be used to back guest memory. - - MemoryBackend: - type: object - required: - - backend_type - - backend_path - properties: - backend_type: - type: string - enum: - - File - - Uffd - backend_path: - type: string - description: Based on 'backend_type' it is either - 1) Path to the file that contains the guest memory to be loaded - 2) Path to the UDS where a process is listening for a UFFD initialization - control payload and open file descriptor that it can use to serve this - process's guest memory page faults - - Metrics: - type: object - description: - Describes the configuration option for the metrics capability. - required: - - metrics_path - properties: - metrics_path: - type: string - description: Path to the named pipe or file where the JSON-formatted metrics are flushed. - - MmdsConfig: - type: object - description: - Defines the MMDS configuration. - required: - - network_interfaces - properties: - version: - description: Enumeration indicating the MMDS version to be configured. - type: string - enum: - - V1 - - V2 - default: V1 - network_interfaces: - description: - List of the network interface IDs capable of forwarding packets to - the MMDS. Network interface IDs mentioned must be valid at the time - of this request. The net device model will reply to HTTP GET requests - sent to the MMDS address via the interfaces mentioned. In this - case, both ARP requests and TCP segments heading to `ipv4_address` - are intercepted by the device model, and do not reach the associated - TAP device. - type: array - items: - type: string - ipv4_address: - type: string - format: "169.254.([1-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-4]).([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])" - default: "169.254.169.254" - description: A valid IPv4 link-local address. - - MmdsContentsObject: - type: object - description: - Describes the contents of MMDS in JSON format. - - NetworkInterface: - type: object - description: - Defines a network interface. - required: - - host_dev_name - - iface_id - properties: - guest_mac: - type: string - host_dev_name: - type: string - description: Host level path for the guest network interface - iface_id: - type: string - rx_rate_limiter: - $ref: "#/definitions/RateLimiter" - tx_rate_limiter: - $ref: "#/definitions/RateLimiter" - - PartialDrive: - type: object - required: - - drive_id - properties: - drive_id: - type: string - path_on_host: - type: string - description: - Host level path for the guest drive. - This field is optional for virtio-block config and should be omitted for vhost-user-block configuration. - rate_limiter: - $ref: "#/definitions/RateLimiter" - - PartialNetworkInterface: - type: object - description: - Defines a partial network interface structure, used to update the rate limiters - for that interface, after microvm start. - required: - - iface_id - properties: - iface_id: - type: string - rx_rate_limiter: - $ref: "#/definitions/RateLimiter" - tx_rate_limiter: - $ref: "#/definitions/RateLimiter" - - RateLimiter: - type: object - description: - Defines an IO rate limiter with independent bytes/s and ops/s limits. - Limits are defined by configuring each of the _bandwidth_ and _ops_ token buckets. - This field is optional for virtio-block config and should be omitted for vhost-user-block configuration. - properties: - bandwidth: - $ref: "#/definitions/TokenBucket" - description: Token bucket with bytes as tokens - ops: - $ref: "#/definitions/TokenBucket" - description: Token bucket with operations as tokens - - SnapshotCreateParams: - type: object - required: - - mem_file_path - - snapshot_path - properties: - mem_file_path: - type: string - description: Path to the file that will contain the guest memory. - snapshot_path: - type: string - description: Path to the file that will contain the microVM state. - snapshot_type: - type: string - enum: - - Full - - Diff - description: - Type of snapshot to create. It is optional and by default, a full - snapshot is created. - - SnapshotLoadParams: - type: object - description: - Defines the configuration used for handling snapshot resume. Exactly one of - the two `mem_*` fields must be present in the body of the request. - required: - - snapshot_path - properties: - enable_diff_snapshots: - type: boolean - description: - Enable support for incremental (diff) snapshots by tracking dirty guest pages. - mem_file_path: - type: string - description: - Path to the file that contains the guest memory to be loaded. - It is only allowed if `mem_backend` is not present. This parameter has - been deprecated and it will be removed in future Firecracker release. - mem_backend: - $ref: "#/definitions/MemoryBackend" - description: - Configuration for the backend that handles memory load. If this field - is specified, `mem_file_path` is forbidden. Either `mem_backend` or - `mem_file_path` must be present at a time. - snapshot_path: - type: string - description: Path to the file that contains the microVM state to be loaded. - resume_vm: - type: boolean - description: - When set to true, the vm is also resumed if the snapshot load is successful. - - TokenBucket: - type: object - description: - Defines a token bucket with a maximum capacity (size), an initial burst size - (one_time_burst) and an interval for refilling purposes (refill_time). - The refill-rate is derived from size and refill_time, and it is the constant - rate at which the tokens replenish. The refill process only starts happening after - the initial burst budget is consumed. - Consumption from the token bucket is unbounded in speed which allows for bursts - bound in size by the amount of tokens available. - Once the token bucket is empty, consumption speed is bound by the refill_rate. - required: - - refill_time - - size - properties: - one_time_burst: - type: integer - format: int64 - description: The initial size of a token bucket. - minimum: 0 - refill_time: - type: integer - format: int64 - description: The amount of milliseconds it takes for the bucket to refill. - minimum: 0 - size: - type: integer - format: int64 - description: The total number of tokens this bucket can hold. - minimum: 0 - - Vm: - type: object - description: - Defines the microVM running state. It is especially useful in the snapshotting context. - required: - - state - properties: - state: - type: string - enum: - - Paused - - Resumed - - EntropyDevice: - type: object - description: - Defines an entropy device. - properties: - rate_limiter: - $ref: "#/definitions/RateLimiter" - - FirecrackerVersion: - type: object - description: - Describes the Firecracker version. - required: - - firecracker_version - properties: - firecracker_version: - description: Firecracker build version. - type: string - - Vsock: - type: object - description: - Defines a vsock device, backed by a set of Unix Domain Sockets, on the host side. - For host-initiated connections, Firecracker will be listening on the Unix socket - identified by the path `uds_path`. Firecracker will create this socket, bind and - listen on it. Host-initiated connections will be performed by connection to this - socket and issuing a connection forwarding request to the desired guest-side vsock - port (i.e. `CONNECT 52\n`, to connect to port 52). - For guest-initiated connections, Firecracker will expect host software to be - bound and listening on Unix sockets at `uds_path_`. - E.g. "/path/to/host_vsock.sock_52" for port number 52. - required: - - guest_cid - - uds_path - properties: - guest_cid: - type: integer - minimum: 3 - description: Guest Vsock CID - uds_path: - type: string - description: Path to UNIX domain socket, used to proxy vsock connections. - vsock_id: - type: string - description: - This parameter has been deprecated and it will be removed in future - Firecracker release. diff --git a/src/vmm/src/logger/logging.rs b/src/vmm/src/logger/logging.rs index d2958bdb691..d98be185acb 100644 --- a/src/vmm/src/logger/logging.rs +++ b/src/vmm/src/logger/logging.rs @@ -15,8 +15,8 @@ use utils::time::LocalTime; use super::metrics::{IncMetric, METRICS}; -/// Default level filter for logger matching the swagger specification -/// (`src/firecracker/swagger/firecracker.yaml`). +/// Default level filter for logger matching the OpenAPI specification +/// (`src/firecracker/openapi/firecracker.yaml`). pub const DEFAULT_LEVEL: log::LevelFilter = log::LevelFilter::Info; /// Default instance id. pub const DEFAULT_INSTANCE_ID: &str = "anonymous-instance"; @@ -25,7 +25,7 @@ pub static INSTANCE_ID: OnceLock = OnceLock::new(); /// The logger. /// -/// Default values matching the swagger specification (`src/firecracker/swagger/firecracker.yaml`). +/// Default values matching the OpenAPI specification (`src/firecracker/openapi/firecracker.yaml`). pub static LOGGER: Logger = Logger(Mutex::new(LoggerConfiguration { target: None, filter: LogFilter { module: None }, diff --git a/tests/integration_tests/style/test_swagger.py b/tests/integration_tests/style/test_swagger.py index e4eb37b0f5e..ef456336f08 100644 --- a/tests/integration_tests/style/test_swagger.py +++ b/tests/integration_tests/style/test_swagger.py @@ -18,5 +18,5 @@ def test_firecracker_swagger(): """ Test that Firecracker swagger specification is valid. """ - swagger_spec = Path("../src/firecracker/swagger/firecracker.yaml") + swagger_spec = Path("../src/firecracker/openapi/firecracker.yaml") validate_swagger(swagger_spec) diff --git a/tools/bump-version.sh b/tools/bump-version.sh index 31a99cadad6..d5f44667422 100755 --- a/tools/bump-version.sh +++ b/tools/bump-version.sh @@ -32,7 +32,7 @@ prev_ver=$(get_swagger_version) say "Updating from $prev_ver to $version ..." # Update version in files. files_to_change=( - "$FC_ROOT_DIR/src/firecracker/swagger/firecracker.yaml" + "$FC_ROOT_DIR/src/firecracker/openapi/firecracker.yaml" "$FC_ROOT_DIR/src/firecracker/Cargo.toml" "$FC_ROOT_DIR/src/jailer/Cargo.toml" "$FC_ROOT_DIR/src/rebase-snap/Cargo.toml" diff --git a/tools/functions b/tools/functions index 429a082d7a9..5a02120eb55 100644 --- a/tools/functions +++ b/tools/functions @@ -94,7 +94,7 @@ get_user_confirmation() { # Get version from the swagger file function get_swagger_version { - local file=${1:-"$FC_ROOT_DIR/src/firecracker/swagger/firecracker.yaml"} + local file=${1:-"$FC_ROOT_DIR/src/firecracker/openapi/firecracker.yaml"} grep -oP 'version: \K.*' "$file" } diff --git a/tools/release.sh b/tools/release.sh index 53d23366793..3ffc0ba4321 100755 --- a/tools/release.sh +++ b/tools/release.sh @@ -171,8 +171,8 @@ done cp -v "resources/seccomp/$CARGO_TARGET.json" "$RELEASE_DIR/seccomp-filter-$SUFFIX.json" # Copy over arch independent assets cp -v -t "$RELEASE_DIR" LICENSE NOTICE THIRD-PARTY -check_swagger_artifact src/firecracker/swagger/firecracker.yaml "$VERSION" -cp -v src/firecracker/swagger/firecracker.yaml "$RELEASE_DIR/firecracker_spec-$VERSION.yaml" +check_swagger_artifact src/firecracker/openapi/firecracker.yaml "$VERSION" +cp -v src/firecracker/openapi/firecracker.yaml "$RELEASE_DIR/firecracker_spec-$VERSION.yaml" CPU_TEMPLATES=(c3 t2 t2s t2cl t2a v1n1) for template in "${CPU_TEMPLATES[@]}"; do