1092 lines
36 KiB
YAML
1092 lines
36 KiB
YAML
openapi: "3.1.0"
|
|
info:
|
|
title: Two API
|
|
version: "0.2.0"
|
|
description: REST API for managing VPCs, Subnets and VMs in the Two orchestrator.
|
|
|
|
servers:
|
|
- url: http://localhost:8080
|
|
description: Local development server
|
|
|
|
paths:
|
|
|
|
# ── VPC ────────────────────────────────────────────────────────────────────
|
|
|
|
/vpcs:
|
|
get:
|
|
summary: List all VPCs
|
|
operationId: listVPCs
|
|
responses:
|
|
"200":
|
|
description: List of VPCs
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/VPC"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
post:
|
|
summary: Create a VPC
|
|
operationId: createVPC
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/VPCCreateRequest"
|
|
responses:
|
|
"202":
|
|
description: VPC creation accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/VPC"
|
|
"400":
|
|
description: Missing required field, invalid request body, invalid CIDR, or l3vni out of range
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"409":
|
|
description: VPC already exists, l3vni already used by another VPC, or l3vni requested on an agent without a bgp section
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
/vpcs/{name}:
|
|
parameters:
|
|
- $ref: "#/components/parameters/ResourceName"
|
|
|
|
get:
|
|
summary: Get VPC status and info
|
|
operationId: getVPC
|
|
responses:
|
|
"200":
|
|
description: VPC found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/VPC"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
delete:
|
|
summary: Delete a VPC
|
|
operationId: deleteVPC
|
|
responses:
|
|
"202":
|
|
description: VPC deletion accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/VPC"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"409":
|
|
description: VPC not deletable — only running or error states can be deleted, all its subnets must be deleted or deleting (subnets still deleting are awaited by the asynchronous deletion), and its NAT gateway, if any, must be deleted first
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
# ── VM ─────────────────────────────────────────────────────────────────────
|
|
|
|
/vms:
|
|
get:
|
|
summary: List all VMs
|
|
operationId: listVMs
|
|
responses:
|
|
"200":
|
|
description: List of VMs
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/VM"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
post:
|
|
summary: Start a VM
|
|
operationId: startVM
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/VMCreateRequest"
|
|
responses:
|
|
"202":
|
|
description: VM start accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/VM"
|
|
"400":
|
|
description: Missing required field or invalid request body
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"409":
|
|
description: VM already exists
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"422":
|
|
description: >
|
|
Subnet not found, or not in creating/running state; or an interface IP outside the
|
|
subnet CIDR, equal to its network or broadcast address, or reserved by the subnet
|
|
(interface_ip, relay_ip, gateway)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
/vms/{name}:
|
|
parameters:
|
|
- $ref: "#/components/parameters/ResourceName"
|
|
|
|
get:
|
|
summary: Get VM status and info
|
|
operationId: getVM
|
|
responses:
|
|
"200":
|
|
description: VM found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/VM"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
delete:
|
|
summary: Stop a VM
|
|
operationId: stopVM
|
|
responses:
|
|
"202":
|
|
description: VM stop accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/VM"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"409":
|
|
description: VM not stoppable — only running or error states can be stopped, and its floating IPs must be deleted first
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
# ── Subnet ─────────────────────────────────────────────────────────────────
|
|
|
|
/subnets:
|
|
get:
|
|
summary: List all subnets
|
|
operationId: listSubnets
|
|
responses:
|
|
"200":
|
|
description: List of subnets
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Subnet"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
post:
|
|
summary: Create a subnet
|
|
operationId: createSubnet
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SubnetCreateRequest"
|
|
responses:
|
|
"202":
|
|
description: Subnet creation accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Subnet"
|
|
"400":
|
|
description: >
|
|
Missing required field; interface_ip missing on a bridge or public_ip subnet, or
|
|
supplied on a vxlan subnet (it is computed); default_route true without gateway on a
|
|
vxlan or public_ip subnet
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"409":
|
|
description: Subnet already exists
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"422":
|
|
description: >
|
|
Unknown mode; parent VPC does not exist or is not ready; invalid CIDR, or a vxlan
|
|
CIDR smaller than /29
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
/subnets/{name}:
|
|
parameters:
|
|
- $ref: "#/components/parameters/ResourceName"
|
|
|
|
get:
|
|
summary: Get subnet status and info
|
|
operationId: getSubnet
|
|
responses:
|
|
"200":
|
|
description: Subnet found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Subnet"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
delete:
|
|
summary: Delete a subnet
|
|
operationId: deleteSubnet
|
|
responses:
|
|
"202":
|
|
description: Subnet deletion accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Subnet"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"409":
|
|
description: Subnet not deletable — only running or error states can be deleted, and every VM with an interface on it must be deleted or deleting; VMs still deleting are awaited by the asynchronous deletion
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
# ── Components ──────────────────────────────────────────────────────────────
|
|
|
|
# ── NAT gateway ────────────────────────────────────────────────────────────
|
|
|
|
/nat-gateways:
|
|
get:
|
|
summary: List all NAT gateways of this agent
|
|
operationId: listNATGateways
|
|
responses:
|
|
"200":
|
|
description: List of NAT gateways
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/NATGateway"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
post:
|
|
summary: Create the NAT gateway of a VPC on this agent
|
|
operationId: createNATGateway
|
|
description: >-
|
|
Gives the VMs of a VPC without a public IP an Internet exit through this host. The
|
|
gateway owns the given public IP on the public bridge (interfaces.internet) and announces
|
|
a type-5 default route in the VRF of the VPC. Only VPCs created by this version or later
|
|
route their default traffic to the VRF, and can use it. To move the gateway, delete it on
|
|
the old host if it answers, then create it on the new one.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/NATGatewayCreateRequest"
|
|
responses:
|
|
"202":
|
|
description: NAT gateway creation accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/NATGateway"
|
|
"400":
|
|
description: Missing required field, invalid request body, ip without prefix length or not IPv4, or gateway not IPv4
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"409":
|
|
description: NAT gateway already exists, VPC unknown on this agent or not running, VPC without l3vni, or VPC that already has a NAT gateway on this agent
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
/nat-gateways/{name}:
|
|
parameters:
|
|
- $ref: "#/components/parameters/ResourceName"
|
|
|
|
get:
|
|
summary: Get NAT gateway status and info
|
|
operationId: getNATGateway
|
|
responses:
|
|
"200":
|
|
description: NAT gateway found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/NATGateway"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
delete:
|
|
summary: Delete a NAT gateway
|
|
operationId: deleteNATGateway
|
|
responses:
|
|
"202":
|
|
description: NAT gateway deletion accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/NATGateway"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"409":
|
|
description: NAT gateway not deletable — only running or error states can be deleted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
# ── Floating IP ────────────────────────────────────────────────────────────
|
|
|
|
/floating-ips:
|
|
get:
|
|
summary: List all floating IPs of this agent
|
|
operationId: listFloatingIPs
|
|
responses:
|
|
"200":
|
|
description: List of floating IPs
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/FloatingIP"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
post:
|
|
summary: Attach a floating IP to an interface of a VM of this agent
|
|
operationId: createFloatingIP
|
|
description: >-
|
|
Makes an interface of a VM reachable through a public IP it does not carry: stateless 1:1
|
|
translation in the netns of the VPC, on the host of the VM, the public IP answering ARP on
|
|
the public bridge (interfaces.internet). The VM leaves through its floating IP, even in a
|
|
VPC with a NAT gateway. To move it with the VM, delete it on the old host, then create it
|
|
on the new one. Attach and detach without touching the VM.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/FloatingIPCreateRequest"
|
|
responses:
|
|
"202":
|
|
description: Floating IP creation accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/FloatingIP"
|
|
"400":
|
|
description: Missing required field, invalid request body, ip without prefix length or not IPv4, or gateway not IPv4
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"409":
|
|
description: Floating IP already exists, VM unknown on this agent or not running, no interface of that name on the VM, interface on a public_ip subnet (it carries its public IP itself), interface that already has a floating IP, or public IP already used by another floating IP of this agent
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
/floating-ips/{name}:
|
|
parameters:
|
|
- $ref: "#/components/parameters/ResourceName"
|
|
|
|
get:
|
|
summary: Get floating IP status and info
|
|
operationId: getFloatingIP
|
|
responses:
|
|
"200":
|
|
description: Floating IP found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/FloatingIP"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
delete:
|
|
summary: Detach and delete a floating IP
|
|
operationId: deleteFloatingIP
|
|
responses:
|
|
"202":
|
|
description: Floating IP deletion accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/FloatingIP"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"409":
|
|
description: Floating IP not deletable — only running or error states can be deleted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
|
|
# ── Host ───────────────────────────────────────────────────────────────────
|
|
|
|
/register:
|
|
get:
|
|
summary: Facts of the host that do not change while it runs
|
|
operationId: getRegister
|
|
description: >-
|
|
Read once when the agent starts and kept in memory. Will also be sent to the broker of the
|
|
orchestrator at startup.
|
|
responses:
|
|
"200":
|
|
description: Host facts
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/HostRegister"
|
|
"405":
|
|
description: Method other than GET
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"503":
|
|
description: Host facts could not be read when the agent started (the error says why)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
/ping:
|
|
get:
|
|
summary: Current state of the host and of the agent
|
|
operationId: getPing
|
|
description: >-
|
|
Last reading, taken when the agent starts then every times.host_state_interval seconds and
|
|
kept in memory; collected_at gives its age. boot_time and agent_start_time tell a host
|
|
reboot from an agent restart; boot_time plus uptime_seconds give the clock of the host.
|
|
responses:
|
|
"200":
|
|
description: Last host state
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/HostPing"
|
|
"405":
|
|
description: Method other than GET
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
"503":
|
|
description: No reading has succeeded yet
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
components:
|
|
|
|
parameters:
|
|
ResourceName:
|
|
name: name
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Resource name
|
|
|
|
schemas:
|
|
|
|
VPCCreateRequest:
|
|
type: object
|
|
required: [name, cidr]
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Unique name for the VPC, must follow the format vp-[id]
|
|
pattern: '^vp-.+'
|
|
example: vp-00001
|
|
cidr:
|
|
type: string
|
|
description: CIDR block for the entire VPC address space
|
|
example: "10.0.0.0/16"
|
|
l3vni:
|
|
type: integer
|
|
format: int32
|
|
minimum: 1
|
|
maximum: 65535
|
|
description: >-
|
|
Optional. L3VNI of the VPC, used for inter-subnet routing between hypervisors
|
|
(symmetric IRB). Also the id of the routing table of the VPC VRF, so 253-255 are
|
|
rejected, and the number of the route distinguisher <vtep>:<l3vni>, which holds 16 bits. Requires the bgp section in the agent configuration, and must not be used
|
|
by another VPC of the agent. Absent: the VPC has no L3VNI.
|
|
example: 4001
|
|
|
|
VPC:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: vp-00001
|
|
state:
|
|
type: string
|
|
enum: [creating, running, error, deleting, deleted]
|
|
example: running
|
|
cidr:
|
|
type: string
|
|
example: "10.0.0.0/16"
|
|
l3vni:
|
|
type: integer
|
|
description: L3VNI of the VPC, absent when the VPC has none
|
|
example: 4001
|
|
|
|
SubnetCreateRequest:
|
|
type: object
|
|
required: [name, vpc, cidr]
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: >
|
|
Unique name for the subnet. Must contain a "-": the system id (bridge br-<id>) is
|
|
what follows the first one. Not validated by the agent (caller's responsibility): a name
|
|
without "-" makes the agent worker panic.
|
|
pattern: '^[^-]+-.+'
|
|
example: sn-00001
|
|
vpc:
|
|
type: string
|
|
description: Parent VPC name
|
|
example: vpc1
|
|
mode:
|
|
type: string
|
|
description: >
|
|
Subnet mode. "vxlan" (default): creates a VXLAN tunnel and a host bridge.
|
|
"bridge": attaches directly to an existing bridge resolved from iface_type in the agent config.
|
|
"public_ip": attached like bridge, but always to the public bridge (interfaces.internet,
|
|
br-public when absent); iface_type is ignored. The VMs carry public IPs; the VPC route
|
|
keeps interface_ip as next-hop. Several VPCs may use the same range with the same
|
|
interface_ip: each has its own subnet, whose name the caller keeps unique on the agent.
|
|
"vlan" is reserved for future use.
|
|
enum: [vxlan, bridge, public_ip]
|
|
default: vxlan
|
|
example: vxlan
|
|
vxlan_id:
|
|
type: integer
|
|
description: VXLAN VNI identifier. Required when mode is "vxlan", ignored otherwise.
|
|
example: 100
|
|
iface_type:
|
|
type: string
|
|
description: Interface type key defined in the agent config (e.g. vms, internet, admin). Falls back to default_interface if omitted or unknown.
|
|
example: vms
|
|
interface_ip:
|
|
type: string
|
|
format: ipv4
|
|
description: >
|
|
Gateway IP for the subnet. Required in bridge and public_ip modes. Rejected in vxlan
|
|
mode (400): the agent computes it as the last usable address of the CIDR
|
|
(broadcast - 1), carried by an anycast gateway identical on every host.
|
|
example: "10.10.10.1"
|
|
cidr:
|
|
type: string
|
|
description: >
|
|
Subnet CIDR block. In vxlan mode, without host bits and at most /29: the last two
|
|
usable addresses are reserved for the gateway and the relay address.
|
|
example: "10.10.10.0/24"
|
|
default_route:
|
|
type: boolean
|
|
description: >
|
|
A default route is always advertised via DHCP; this flag only chooses its next-hop.
|
|
When false, the next-hop is the subnet interface_ip. When true, it is the `gateway`
|
|
field if supplied, otherwise the gateway read from the host routing table — this last
|
|
case is bridge mode only (400 in vxlan and public_ip modes, whose guests do not share
|
|
the L2 segment of the host gateway). The route to the VPC CIDR always keeps interface_ip as its next-hop (except in bridge
|
|
mode, which has no VPC route), so VPC traffic never leaves through a public gateway.
|
|
default: false
|
|
gateway:
|
|
type: string
|
|
format: ipv4
|
|
description: >
|
|
Optional next-hop for the default route. Only used when default_route is true;
|
|
supplied with default_route false, it is ignored. Not validated by the agent:
|
|
reachability and coherence with the subnet CIDR are the caller's responsibility.
|
|
example: "10.10.10.1"
|
|
|
|
Subnet:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: sn-00001
|
|
state:
|
|
type: string
|
|
enum: [creating, running, error, deleting, deleted]
|
|
example: running
|
|
vpc:
|
|
type: string
|
|
example: vpc1
|
|
mode:
|
|
type: string
|
|
enum: [vxlan, bridge, public_ip]
|
|
example: vxlan
|
|
vxlan_id:
|
|
type: integer
|
|
description: VXLAN VNI. Present only when mode is "vxlan".
|
|
example: 100
|
|
local_iface:
|
|
type: string
|
|
description: Resolved interface name from agent config
|
|
example: br-000000
|
|
interface_ip:
|
|
type: string
|
|
description: Subnet gateway. In vxlan mode, computed by the agent (broadcast - 1).
|
|
example: "10.10.10.254"
|
|
relay_ip:
|
|
type: string
|
|
description: >
|
|
vxlan mode only (broadcast - 2): address the subnet uses to reach guests on other
|
|
hosts, carried by the bridge of each host. Absent on subnets created before it existed.
|
|
example: "10.10.10.253"
|
|
cidr:
|
|
type: string
|
|
example: "10.10.10.0/24"
|
|
default_route:
|
|
type: boolean
|
|
example: false
|
|
gateway:
|
|
type: string
|
|
example: "10.10.10.1"
|
|
|
|
VMCreateRequest:
|
|
type: object
|
|
required: [name, interfaces, storage]
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: vm-00001
|
|
memory:
|
|
type: integer
|
|
description: Memory in MB (default 512)
|
|
example: 1024
|
|
cpus:
|
|
type: integer
|
|
description: Number of vCPUs (default 1)
|
|
example: 2
|
|
metadata:
|
|
$ref: "#/components/schemas/VMMetadata"
|
|
interfaces:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 27
|
|
description: >
|
|
Network interfaces, in order. The position determines the PCI slot
|
|
(0x03 + index) and therefore the interface name inside the guest.
|
|
**Exactly one** interface must be marked primary: it carries the
|
|
default route and the metadata server. All subnets must belong to
|
|
the same VPC.
|
|
items:
|
|
$ref: "#/components/schemas/VMInterface"
|
|
storage:
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
$ref: "#/components/schemas/VMStorage"
|
|
uefi:
|
|
type: boolean
|
|
description: Boot with UEFI firmware (OVMF). Defaults to false (SeaBIOS).
|
|
example: false
|
|
|
|
VMMetadata:
|
|
type: object
|
|
description: >
|
|
cloud-init inputs for this VM. Every field is optional. The served
|
|
user-data is user_data when given, empty otherwise: an empty
|
|
user_data is the same as no user_data. meta-data, network-config and
|
|
vendor-data always come from the agent's built-in templates
|
|
(vendor-data creates the syonad account from password and sshkey).
|
|
properties:
|
|
password:
|
|
type: string
|
|
description: >
|
|
Password *hash* for the syonad account, as expected by the
|
|
cloud-config `passwd` key (e.g. `$6$...`) — not a plaintext
|
|
password. When omitted, the account is created locked
|
|
(`lock_passwd: true`); when neither password nor sshkey is given,
|
|
no account is created at all.
|
|
example: "$6$rounds=4096$saltsalt$hash..."
|
|
sshkey:
|
|
type: string
|
|
description: Public SSH key added to the syonad account. Sent as-is, not encoded.
|
|
example: "ssh-ed25519 AAAA..."
|
|
user_data:
|
|
type: string
|
|
format: byte
|
|
description: >
|
|
cloud-init user-data, **base64-encoded**. Encoding keeps multi-line
|
|
documents out of JSON escaping and allows gzip+base64 payloads.
|
|
Invalid base64 is rejected with 400 rather than silently serving an
|
|
empty document. The agent never interprets this content.
|
|
example: "I2Nsb3VkLWNvbmZpZwpwYWNrYWdlczoKICAtIG5naW54Cg=="
|
|
|
|
VMInterface:
|
|
type: object
|
|
required: [name, subnet, ip, mac, primary]
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: >
|
|
Name of the interface, chosen by the caller and unique within the VM. It is an API
|
|
identifier only, used to point at the interface (a floating IP for instance): no
|
|
Linux interface is named after it, neither in the guest nor on the host. The agent
|
|
does not check its format. Missing, empty or used twice in the VM → 400. Interfaces
|
|
of VMs created before it was required are named nic-<index> at agent start.
|
|
example: nic-a1b2
|
|
subnet:
|
|
type: string
|
|
example: sn-00001
|
|
ip:
|
|
type: string
|
|
format: ipv4
|
|
example: "10.0.0.5"
|
|
mac:
|
|
type: string
|
|
pattern: '^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$'
|
|
description: >
|
|
MAC address of the interface, chosen by the caller. It is given to
|
|
QEMU and to the DHCP reservation as is, and returned unchanged by
|
|
GET. The agent does not check its format nor its uniqueness: that
|
|
is the caller's job. Missing or empty → 400.
|
|
example: "52:54:00:00:00:05"
|
|
primary:
|
|
type: boolean
|
|
example: true
|
|
dhcp_server:
|
|
type: boolean
|
|
default: false
|
|
description: >
|
|
Lets the VM answer DHCP (UDP from port 67) on this interface, for
|
|
instance a PXE server for diskless hosts on a `bridge` subnet. Every
|
|
other interface may not send DHCP answers. The interface still sends
|
|
only from its own MAC and IP. The agent applies it whatever the mode
|
|
of the subnet: restricting it is the caller's job. Always returned
|
|
by GET.
|
|
example: false
|
|
floating_ip:
|
|
readOnly: true
|
|
description: >
|
|
Floating IP attached to this interface, computed on read from /floating-ips; absent
|
|
when the interface has none. Refused in a creation request (400): a floating IP is
|
|
attached with /floating-ips.
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: fip-7
|
|
ip:
|
|
type: string
|
|
example: "203.0.113.20/24"
|
|
state:
|
|
type: string
|
|
enum: [creating, running, error, deleting, deleted]
|
|
example: running
|
|
|
|
VMStorage:
|
|
type: object
|
|
required: [path, dev]
|
|
properties:
|
|
path:
|
|
type: string
|
|
description: Path to the disk image on the host
|
|
example: /var/lib/two/volumes/abc.qcow2
|
|
dev:
|
|
type: string
|
|
description: >-
|
|
vda is the virtio-blk root disk, seen as /dev/vda and booted
|
|
first. xvdX is an additional disk on SCSI target X (xvda → 0),
|
|
seen by the guest kernel as some /dev/sdY in detection order. The
|
|
disk serial is set to dev: an image that follows the two image
|
|
requirements links it to /dev/xvdX, and udev always exposes it as
|
|
/dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_xvdX (virtio-vda for the
|
|
root disk). Anything else → 400; sdX is no longer accepted.
|
|
pattern: '^(vda|xvd[a-z])$'
|
|
example: vda
|
|
|
|
VM:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: vm-00001
|
|
state:
|
|
type: string
|
|
enum: [creating, running, error, deleting, deleted]
|
|
example: running
|
|
metadata_port:
|
|
type: string
|
|
example: "80"
|
|
memory:
|
|
type: integer
|
|
example: 1024
|
|
cpus:
|
|
type: integer
|
|
example: 2
|
|
interfaces:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/VMInterface"
|
|
storage:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/VMStorage"
|
|
uefi:
|
|
type: boolean
|
|
example: false
|
|
|
|
NATGatewayCreateRequest:
|
|
type: object
|
|
required: [name, vpc, ip, gateway]
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: ng-42
|
|
vpc:
|
|
type: string
|
|
description: VPC of the gateway; must be running on this agent and have an l3vni
|
|
example: vp-42
|
|
ip:
|
|
type: string
|
|
description: Public exit IP of the VPC with its prefix length, chosen by the caller and not checked by the agent
|
|
example: "198.51.100.50/24"
|
|
gateway:
|
|
type: string
|
|
description: Gateway of the border routers on the public segment, not checked by the agent
|
|
example: "198.51.100.1"
|
|
|
|
NATGateway:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: ng-42
|
|
state:
|
|
type: string
|
|
enum: [creating, running, error, deleting, deleted]
|
|
example: running
|
|
vpc:
|
|
type: string
|
|
example: vp-42
|
|
ip:
|
|
type: string
|
|
example: "198.51.100.50/24"
|
|
gateway:
|
|
type: string
|
|
example: "198.51.100.1"
|
|
|
|
FloatingIPCreateRequest:
|
|
type: object
|
|
required: [name, vm, interface, ip, gateway]
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: fip-7
|
|
vm:
|
|
type: string
|
|
description: VM of the interface; must be running on this agent
|
|
example: vm-7
|
|
interface:
|
|
type: string
|
|
description: Name of the interface of the VM (VMInterface.name), not a Linux interface
|
|
example: nic-a1b2
|
|
ip:
|
|
type: string
|
|
description: Public IP with its prefix length, chosen by the caller and not checked by the agent
|
|
example: "203.0.113.20/24"
|
|
gateway:
|
|
type: string
|
|
description: Gateway of the border routers on the public segment, not checked by the agent
|
|
example: "203.0.113.1"
|
|
|
|
FloatingIP:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: fip-7
|
|
state:
|
|
type: string
|
|
enum: [creating, running, error, deleting, deleted]
|
|
example: running
|
|
vm:
|
|
type: string
|
|
example: vm-7
|
|
interface:
|
|
type: string
|
|
example: nic-a1b2
|
|
ip:
|
|
type: string
|
|
example: "203.0.113.20/24"
|
|
gateway:
|
|
type: string
|
|
example: "203.0.113.1"
|
|
|
|
HostRegister:
|
|
type: object
|
|
properties:
|
|
hostname:
|
|
type: string
|
|
example: hv1
|
|
cpu:
|
|
type: object
|
|
properties:
|
|
vendor:
|
|
type: string
|
|
example: AuthenticAMD
|
|
model:
|
|
type: string
|
|
example: AMD EPYC 7272 12-Core Processor
|
|
sockets:
|
|
type: integer
|
|
example: 1
|
|
cores:
|
|
type: integer
|
|
description: Physical cores, all sockets together
|
|
example: 12
|
|
threads:
|
|
type: integer
|
|
description: Logical processors, all sockets together
|
|
example: 24
|
|
memory_bytes:
|
|
type: integer
|
|
format: int64
|
|
example: 134217728000
|
|
os:
|
|
type: object
|
|
description: From /etc/os-release
|
|
properties:
|
|
id:
|
|
type: string
|
|
example: debian
|
|
version_id:
|
|
type: string
|
|
example: "12"
|
|
pretty_name:
|
|
type: string
|
|
example: Debian GNU/Linux 12 (bookworm)
|
|
kernel:
|
|
type: string
|
|
example: 6.1.0-26-amd64
|
|
|
|
HostPing:
|
|
type: object
|
|
properties:
|
|
agent_version:
|
|
type: string
|
|
description: Release tag, commit for a lab build, undefined when not set at build time
|
|
example: 0.3.0
|
|
collected_at:
|
|
type: integer
|
|
format: int64
|
|
description: Unix time (seconds) of the reading
|
|
example: 1793520853
|
|
boot_time:
|
|
type: integer
|
|
format: int64
|
|
description: Unix time (seconds) the host booted
|
|
example: 1793499123
|
|
agent_start_time:
|
|
type: integer
|
|
format: int64
|
|
description: Unix time (seconds) the agent started
|
|
example: 1793499190
|
|
uptime_seconds:
|
|
type: number
|
|
example: 21730.4
|
|
load:
|
|
type: array
|
|
description: Load average over 1, 5 and 15 minutes
|
|
minItems: 3
|
|
maxItems: 3
|
|
items:
|
|
type: number
|
|
example: [0.12, 0.3, 0.25]
|
|
|
|
Error:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "resource not found"
|
|
|
|
responses:
|
|
NotFound:
|
|
description: Resource not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
InternalError:
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|