{ "swagger": "2.0", "info": { "title": "Flintlock MicroVM API", "description": "The Flintlock MicroVM API handles operations for provisioning and managing microvms", "version": "0.1" }, "tags": [ { "name": "MicroVM" } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/v1alpha1/microvm": { "post": { "operationId": "MicroVM_CreateMicroVM", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1alpha1CreateMicroVMResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "microvm", "in": "body", "required": true, "schema": { "$ref": "#/definitions/typesMicroVMSpec" } }, { "name": "metadata", "description": "This is a request variable of the map type. The query format is \"map_name[key]=value\", e.g. If the map name is Age, the key type is string, and the value type is integer, the query parameter is expressed as Age[\"bob\"]=18", "in": "query", "required": false } ], "tags": [ "MicroVM" ] } }, "/v1alpha1/microvm/{namespace}": { "get": { "operationId": "MicroVM_ListMicroVMs", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1alpha1ListMicroVMsResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "namespace", "in": "path", "required": true, "type": "string" }, { "name": "name", "in": "query", "required": false, "type": "string" } ], "tags": [ "MicroVM" ] } }, "/v1alpha1/microvm/{uid}": { "get": { "operationId": "MicroVM_GetMicroVM", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1alpha1GetMicroVMResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "uid", "in": "path", "required": true, "type": "string" } ], "tags": [ "MicroVM" ] }, "delete": { "operationId": "MicroVM_DeleteMicroVM", "responses": { "200": { "description": "A successful response.", "schema": { "type": "object", "properties": {} } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "uid", "in": "path", "required": true, "type": "string" } ], "tags": [ "MicroVM" ] } } }, "definitions": { "MicroVMStatusMicroVMState": { "type": "string", "enum": [ "PENDING", "CREATED", "FAILED", "DELETING" ], "default": "PENDING" }, "MountMountType": { "type": "string", "enum": [ "DEV", "HOSTPATH" ], "default": "DEV" }, "NetworkInterfaceIfaceType": { "type": "string", "enum": [ "MACVTAP", "TAP" ], "default": "MACVTAP", "description": " - MACVTAP: MACVTAP represents a network interface that is macvtap.\n - TAP: TAP represents a network interface that is a tap." }, "protobufAny": { "type": "object", "properties": { "@type": { "type": "string", "description": "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n URL, or have them precompiled into a binary to avoid any\n lookup. Therefore, binary compatibility needs to be preserved\n on changes to types. (Use versioned type names to manage\n breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics." } }, "additionalProperties": {}, "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(\u0026foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n\nExample 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\nExample 4: Pack and unpack a message in Go\n\n foo := \u0026pb.Foo{...}\n any, err := anypb.New(foo)\n if err != nil {\n ...\n }\n ...\n foo := \u0026pb.Foo{}\n if err := any.UnmarshalTo(foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\n\nJSON\n\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": \u003cstring\u003e,\n \"lastName\": \u003cstring\u003e\n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }" }, "rpcStatus": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/protobufAny" } } } }, "typesInitrd": { "type": "object", "properties": { "image": { "type": "string", "description": "Image is the container image to use." }, "filename": { "type": "string", "title": "Filename is used to specify the name of the kernel file\nin the Image. Defaults to initrd" } }, "description": "Initrd represents the configuration for the initial ramdisk." }, "typesKernel": { "type": "object", "properties": { "image": { "type": "string", "description": "Image is the container image to use." }, "cmdline": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Cmdline is the additional kernel command line args. Each provider has its\nown recommended list, they will be used automatically. This field is for\nadditional values." }, "filename": { "type": "string", "description": "Filename is used to specify the name of the kernel file\nin the Image." }, "addNetworkConfig": { "type": "boolean", "description": "AddNetworkConfig if set to true indicates that the network-config kernel argument should be generated." } }, "description": "Kernel represents the configuration for a kernel." }, "typesMicroVM": { "type": "object", "properties": { "version": { "type": "integer", "format": "int32" }, "spec": { "$ref": "#/definitions/typesMicroVMSpec", "description": "Spec is the specification of the microvm." }, "status": { "$ref": "#/definitions/typesMicroVMStatus", "description": "Status is the runtime status of the microvm." } }, "description": "MicroVM represents a microvm machine that is created via a provider." }, "typesMicroVMSpec": { "type": "object", "properties": { "id": { "type": "string", "description": "ID is the identifier of the microvm.\nIf this empty at creation time a ID will be automatically generated." }, "namespace": { "type": "string", "description": "Namespace is the name of the namespace the microvm belongs to." }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Labels allows you to include extra data for the microvms." }, "vcpu": { "type": "integer", "format": "int32", "description": "VCPU specifies how many vcpu the machine will be allocated." }, "memoryInMb": { "type": "integer", "format": "int32", "description": "MemoryInMb is the amount of memory in megabytes that the machine will be allocated." }, "kernel": { "$ref": "#/definitions/typesKernel", "description": "Kernel is the details of the kernel to use ." }, "initrd": { "$ref": "#/definitions/typesInitrd", "description": "Initrd is the optional details of the initial ramdisk." }, "rootVolume": { "$ref": "#/definitions/typesVolume", "description": "RootVolume specifies the root volume mount for the MicroVM." }, "additionalVolumes": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/typesVolume" }, "description": "AdditionalVolumes specifies the volumes to be attached to the microvm." }, "interfaces": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/typesNetworkInterface" }, "description": "Interfaces specifies the network interfaces to be attached to the microvm.\nDevice names on the guest machine are determined by the order defined in\nthe list starting from eth1, eth2, ..., ethN." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Metadata allows you to specify data to be added to the metadata service. The key is the name\nof the metadata item and the value is the base64 encoded contents of the metadata." }, "createdAt": { "type": "string", "format": "date-time", "description": "CreatedAt indicates the time the microvm was created at." }, "updatedAt": { "type": "string", "format": "date-time", "description": "UpdatedAt indicates the time the microvm was last updated." }, "deletedAt": { "type": "string", "format": "date-time", "description": "DeletedAt indicates the time the microvm was marked as deleted." }, "uid": { "type": "string", "description": "UID is a globally unique identifier of the microvm." }, "provider": { "type": "string", "description": "Provider allows you to specify the name of the microvm provider to use. If this isn't supplied\nthen the default provider will be used." } }, "description": "MicroVMSpec represents the specification for a microvm." }, "typesMicroVMStatus": { "type": "object", "properties": { "state": { "$ref": "#/definitions/MicroVMStatusMicroVMState", "description": "State stores information about the last known state of the vm and the spec." }, "volumes": { "type": "object", "additionalProperties": { "$ref": "#/definitions/typesVolumeStatus" }, "description": "Volumes holds the status of the volumes." }, "kernelMount": { "$ref": "#/definitions/typesMount", "description": "KernelMount holds the status of the kernel mount point." }, "initrdMount": { "$ref": "#/definitions/typesMount", "description": "InitrdMount holds the status of the initrd mount point." }, "networkInterfaces": { "type": "object", "additionalProperties": { "$ref": "#/definitions/typesNetworkInterfaceStatus" }, "description": "NetworkInterfaces holds the status of the network interfaces." }, "retry": { "type": "integer", "format": "int32", "description": "Retry is a counter about how many times we retried to reconcile." } }, "description": "MicroVMStatus contains the runtime status of the microvm." }, "typesMount": { "type": "object", "properties": { "type": { "$ref": "#/definitions/MountMountType", "description": "Type specifies the type of the mount (e.g. device or directory)." }, "source": { "type": "string", "description": "Source is the location of the mounted volume." } }, "description": "Mount represents a volume mount point." }, "typesNetworkInterface": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "DeviceID is the ID of the interface. There is no relation between the ID\nand the name of the interface device on the quest machine." }, "type": { "$ref": "#/definitions/NetworkInterfaceIfaceType", "description": "IfaceType specifies the type of network interface to create for use by the guest." }, "guestMac": { "type": "string", "description": "GuestMAC allows the specifying of a specifi MAC address to use for the interface. If\nnot supplied a autogenerated MAC address will be used." }, "address": { "$ref": "#/definitions/typesStaticAddress", "description": "Address is an optional static IP address to manually assign to this interface. \nIf not supplied then DHCP will be used." }, "overrides": { "$ref": "#/definitions/typesNetworkOverrides", "description": "Overrides is optional overrides applicable for network configuration." } } }, "typesNetworkInterfaceStatus": { "type": "object", "properties": { "hostDeviceName": { "type": "string", "description": "HostDeviceName is the name of the network interface used from the host. This will be\na tuntap or macvtap interface." }, "index": { "type": "integer", "format": "int32", "description": "Index is the index of the network interface on the host." }, "macAddress": { "type": "string", "description": "MACAddress is the MAC address of the host interface." } } }, "typesNetworkOverrides": { "type": "object", "properties": { "bridgeName": { "type": "string", "description": "BridgeName is the name of the Linux bridge to attach TAP devices to. This overrides\nany value set at the overall flintlock level." } }, "description": "NetworkOverrides represents override values for a network interface." }, "typesStaticAddress": { "type": "object", "properties": { "address": { "type": "string", "description": "Address is the static IP address (IPv4 or IPv6) to assign to this interface.\nMust be CIDR notation." }, "gateway": { "type": "string", "description": "Gateway is used to optionaly set the default gateway for IPv4 or IPv6." }, "nameservers": { "type": "array", "items": { "type": "string" }, "description": "Nameservers allows you to optionaly specify nameservers for the interface." } }, "description": "StaticAddress represents a static IPv4 or IPv6 address." }, "typesVolume": { "type": "object", "properties": { "id": { "type": "string", "description": "ID is the uinique identifier of the volume." }, "isReadOnly": { "type": "boolean", "description": "IsReadOnly specifies that the volume is to be mounted readonly." }, "mountPoint": { "type": "string", "description": "MountPoint allows you to optionally specify a mount point for the volume. This only\napplied to additional volumes and it will use cloud-init to mount the volumes." }, "source": { "$ref": "#/definitions/typesVolumeSource", "description": "Source is where the volume will be sourced from." }, "partitionId": { "type": "string", "description": "PartitionID is the uuid of the boot partition." }, "sizeInMb": { "type": "integer", "format": "int32", "description": "Size is the size to resize this volume to.\n\nTODO: add rate limiting" } }, "description": "Volume represents the configuration for a volume to be attached to a microvm." }, "typesVolumeSource": { "type": "object", "properties": { "containerSource": { "type": "string", "description": "Container is used to specify a source of a volume as a OCI container." }, "virtiofsSource": { "type": "string", "title": "Used for the virtiofs source path" } }, "description": "VolumeSource is the source of a volume. Based loosely on the volumes in Kubernetes Pod specs." }, "typesVolumeStatus": { "type": "object", "properties": { "mount": { "$ref": "#/definitions/typesMount", "description": "Mount represents a volume mount point." } } }, "v1alpha1CreateMicroVMResponse": { "type": "object", "properties": { "microvm": { "$ref": "#/definitions/typesMicroVM" } } }, "v1alpha1GetMicroVMResponse": { "type": "object", "properties": { "microvm": { "$ref": "#/definitions/typesMicroVM" } } }, "v1alpha1ListMessage": { "type": "object", "properties": { "microvm": { "$ref": "#/definitions/typesMicroVM" } } }, "v1alpha1ListMicroVMsResponse": { "type": "object", "properties": { "microvm": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/typesMicroVM" } } } } } }