two/api/agent.yaml
GnomeZworc 6ecac451ee
f-88: api: nom obligatoire des interfaces de VM, migration nic-<i> #88
Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
2026-10-30 21:49:50 +01:00

792 lines
26 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
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"
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": accepted and routed like vxlan for DHCP purposes, but its host network
setup is not implemented yet — creating such a subnet currently fails in Execute.
"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
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"
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"