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 :, 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-) 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- 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"