Référence

Référence#

Cette page est générée depuis api/agent.yaml, à la racine du dépôt. C’est la source unique du contrat : en cas d’écart avec le reste de la documentation, c’est elle qui fait foi.

GET /vpcs#

List all VPCs

Example request:

GET /vpcs HTTP/1.1
Host: example.com
Codes de statut:
  • 200 OK –

    List of VPCs

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "name": "string",
            "state": "creating",
            "cidr": "string",
            "l3vni": 1
        }
    ]
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vpcs#

Create a VPC

Example request:

POST /vpcs HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "cidr": "string",
    "l3vni": 1
}
Codes de statut:
  • 202 Accepted –

    VPC creation accepted

    Example response:

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "cidr": "string",
        "l3vni": 1
    }
    

  • 400 Bad Request –

    Missing required field, invalid request body, invalid CIDR, or l3vni out of range

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 409 Conflict –

    VPC already exists, l3vni already used by another VPC, or l3vni requested on an agent without a bgp section

    Example response:

    HTTP/1.1 409 Conflict
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

GET /vpcs/{name}#

Get VPC status and info

Paramètres:
  • name (string) – Resource name

Example request:

GET /vpcs/{name} HTTP/1.1
Host: example.com
Codes de statut:
  • 200 OK –

    VPC found

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "cidr": "string",
        "l3vni": 1
    }
    

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1 404 Not Found
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

DELETE /vpcs/{name}#

Delete a VPC

Paramètres:
  • name (string) – Resource name

Codes de statut:
  • 202 Accepted –

    VPC deletion accepted

    Example response:

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "cidr": "string",
        "l3vni": 1
    }
    

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1 404 Not Found
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 409 Conflict –

    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

    Example response:

    HTTP/1.1 409 Conflict
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

GET /vms#

List all VMs

Example request:

GET /vms HTTP/1.1
Host: example.com
Codes de statut:
  • 200 OK –

    List of VMs

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "name": "string",
            "state": "creating",
            "metadata_port": "string",
            "memory": 1,
            "cpus": 1,
            "interfaces": [
                {
                    "name": "string",
                    "subnet": "string",
                    "ip": "string",
                    "mac": "string",
                    "primary": true,
                    "dhcp_server": true,
                    "floating_ip": {
                        "name": "string",
                        "ip": "string",
                        "state": "creating"
                    }
                }
            ],
            "storage": [
                {
                    "path": "string",
                    "dev": "string"
                }
            ],
            "uefi": true
        }
    ]
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /vms#

Start a VM

Example request:

POST /vms HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "memory": 1,
    "cpus": 1,
    "metadata": {
        "password": "string",
        "sshkey": "string",
        "user_data": "c3RyaW5n"
    },
    "interfaces": [
        {
            "name": "string",
            "subnet": "string",
            "ip": "string",
            "mac": "string",
            "primary": true,
            "dhcp_server": true
        }
    ],
    "storage": [
        {
            "path": "string",
            "dev": "string"
        }
    ],
    "uefi": true
}
Codes de statut:
  • 202 Accepted –

    VM start accepted

    Example response:

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "metadata_port": "string",
        "memory": 1,
        "cpus": 1,
        "interfaces": [
            {
                "name": "string",
                "subnet": "string",
                "ip": "string",
                "mac": "string",
                "primary": true,
                "dhcp_server": true,
                "floating_ip": {
                    "name": "string",
                    "ip": "string",
                    "state": "creating"
                }
            }
        ],
        "storage": [
            {
                "path": "string",
                "dev": "string"
            }
        ],
        "uefi": true
    }
    

  • 400 Bad Request –

    Missing required field or invalid request body

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 409 Conflict –

    VM already exists

    Example response:

    HTTP/1.1 409 Conflict
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    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)

    Example response:

    HTTP/1.1 422 Unprocessable Content
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

GET /vms/{name}#

Get VM status and info

Paramètres:
  • name (string) – Resource name

Example request:

GET /vms/{name} HTTP/1.1
Host: example.com
Codes de statut:
  • 200 OK –

    VM found

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "metadata_port": "string",
        "memory": 1,
        "cpus": 1,
        "interfaces": [
            {
                "name": "string",
                "subnet": "string",
                "ip": "string",
                "mac": "string",
                "primary": true,
                "dhcp_server": true,
                "floating_ip": {
                    "name": "string",
                    "ip": "string",
                    "state": "creating"
                }
            }
        ],
        "storage": [
            {
                "path": "string",
                "dev": "string"
            }
        ],
        "uefi": true
    }
    

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1 404 Not Found
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

DELETE /vms/{name}#

Stop a VM

Paramètres:
  • name (string) – Resource name

Codes de statut:
  • 202 Accepted –

    VM stop accepted

    Example response:

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "metadata_port": "string",
        "memory": 1,
        "cpus": 1,
        "interfaces": [
            {
                "name": "string",
                "subnet": "string",
                "ip": "string",
                "mac": "string",
                "primary": true,
                "dhcp_server": true,
                "floating_ip": {
                    "name": "string",
                    "ip": "string",
                    "state": "creating"
                }
            }
        ],
        "storage": [
            {
                "path": "string",
                "dev": "string"
            }
        ],
        "uefi": true
    }
    

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1 404 Not Found
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 409 Conflict –

    VM not stoppable — only running or error states can be stopped, and its floating IPs must be deleted first

    Example response:

    HTTP/1.1 409 Conflict
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

GET /subnets#

List all subnets

Example request:

GET /subnets HTTP/1.1
Host: example.com
Codes de statut:
  • 200 OK –

    List of subnets

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "name": "string",
            "state": "creating",
            "vpc": "string",
            "mode": "vxlan",
            "vxlan_id": 1,
            "local_iface": "string",
            "interface_ip": "string",
            "relay_ip": "string",
            "cidr": "string",
            "default_route": true,
            "gateway": "string"
        }
    ]
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /subnets#

Create a subnet

Example request:

POST /subnets HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "vpc": "string",
    "mode": "vxlan",
    "vxlan_id": 1,
    "iface_type": "string",
    "interface_ip": "string",
    "cidr": "string",
    "default_route": true,
    "gateway": "string"
}
Codes de statut:
  • 202 Accepted –

    Subnet creation accepted

    Example response:

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "vpc": "string",
        "mode": "vxlan",
        "vxlan_id": 1,
        "local_iface": "string",
        "interface_ip": "string",
        "relay_ip": "string",
        "cidr": "string",
        "default_route": true,
        "gateway": "string"
    }
    

  • 400 Bad Request –

    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

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 409 Conflict –

    Subnet already exists

    Example response:

    HTTP/1.1 409 Conflict
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 422 Unprocessable Entity –

    Unknown mode; parent VPC does not exist or is not ready; invalid CIDR, or a vxlan CIDR smaller than /29

    Example response:

    HTTP/1.1 422 Unprocessable Content
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

GET /subnets/{name}#

Get subnet status and info

Paramètres:
  • name (string) – Resource name

Example request:

GET /subnets/{name} HTTP/1.1
Host: example.com
Codes de statut:
  • 200 OK –

    Subnet found

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "vpc": "string",
        "mode": "vxlan",
        "vxlan_id": 1,
        "local_iface": "string",
        "interface_ip": "string",
        "relay_ip": "string",
        "cidr": "string",
        "default_route": true,
        "gateway": "string"
    }
    

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1 404 Not Found
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

DELETE /subnets/{name}#

Delete a subnet

Paramètres:
  • name (string) – Resource name

Codes de statut:
  • 202 Accepted –

    Subnet deletion accepted

    Example response:

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "vpc": "string",
        "mode": "vxlan",
        "vxlan_id": 1,
        "local_iface": "string",
        "interface_ip": "string",
        "relay_ip": "string",
        "cidr": "string",
        "default_route": true,
        "gateway": "string"
    }
    

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1 404 Not Found
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 409 Conflict –

    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

    Example response:

    HTTP/1.1 409 Conflict
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

GET /nat-gateways#

List all NAT gateways of this agent

Example request:

GET /nat-gateways HTTP/1.1
Host: example.com
Codes de statut:
  • 200 OK –

    List of NAT gateways

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "name": "string",
            "state": "creating",
            "vpc": "string",
            "ip": "string",
            "gateway": "string"
        }
    ]
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /nat-gateways#

Create the NAT gateway of a VPC on this agent

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.

Example request:

POST /nat-gateways HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "vpc": "string",
    "ip": "string",
    "gateway": "string"
}
Codes de statut:
  • 202 Accepted –

    NAT gateway creation accepted

    Example response:

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "vpc": "string",
        "ip": "string",
        "gateway": "string"
    }
    

  • 400 Bad Request –

    Missing required field, invalid request body, ip without prefix length or not IPv4, or gateway not IPv4

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 409 Conflict –

    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

    Example response:

    HTTP/1.1 409 Conflict
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

GET /nat-gateways/{name}#

Get NAT gateway status and info

Paramètres:
  • name (string) – Resource name

Example request:

GET /nat-gateways/{name} HTTP/1.1
Host: example.com
Codes de statut:
  • 200 OK –

    NAT gateway found

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "vpc": "string",
        "ip": "string",
        "gateway": "string"
    }
    

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1 404 Not Found
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

DELETE /nat-gateways/{name}#

Delete a NAT gateway

Paramètres:
  • name (string) – Resource name

Codes de statut:
  • 202 Accepted –

    NAT gateway deletion accepted

    Example response:

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "vpc": "string",
        "ip": "string",
        "gateway": "string"
    }
    

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1 404 Not Found
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 409 Conflict –

    NAT gateway not deletable — only running or error states can be deleted

    Example response:

    HTTP/1.1 409 Conflict
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

GET /floating-ips#

List all floating IPs of this agent

Example request:

GET /floating-ips HTTP/1.1
Host: example.com
Codes de statut:
  • 200 OK –

    List of floating IPs

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
        {
            "name": "string",
            "state": "creating",
            "vm": "string",
            "interface": "string",
            "ip": "string",
            "gateway": "string"
        }
    ]
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

POST /floating-ips#

Attach a floating IP to an interface of a VM of this agent

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.

Example request:

POST /floating-ips HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "vm": "string",
    "interface": "string",
    "ip": "string",
    "gateway": "string"
}
Codes de statut:
  • 202 Accepted –

    Floating IP creation accepted

    Example response:

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "vm": "string",
        "interface": "string",
        "ip": "string",
        "gateway": "string"
    }
    

  • 400 Bad Request –

    Missing required field, invalid request body, ip without prefix length or not IPv4, or gateway not IPv4

    Example response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 409 Conflict –

    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

    Example response:

    HTTP/1.1 409 Conflict
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

GET /floating-ips/{name}#

Get floating IP status and info

Paramètres:
  • name (string) – Resource name

Example request:

GET /floating-ips/{name} HTTP/1.1
Host: example.com
Codes de statut:
  • 200 OK –

    Floating IP found

    Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "vm": "string",
        "interface": "string",
        "ip": "string",
        "gateway": "string"
    }
    

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1 404 Not Found
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

DELETE /floating-ips/{name}#

Detach and delete a floating IP

Paramètres:
  • name (string) – Resource name

Codes de statut:
  • 202 Accepted –

    Floating IP deletion accepted

    Example response:

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
        "name": "string",
        "state": "creating",
        "vm": "string",
        "interface": "string",
        "ip": "string",
        "gateway": "string"
    }
    

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1 404 Not Found
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 409 Conflict –

    Floating IP not deletable — only running or error states can be deleted

    Example response:

    HTTP/1.1 409 Conflict
    Content-Type: application/json
    
    {
        "error": "string"
    }
    

  • 500 Internal Server Error –

    Internal server error

    Example response:

    HTTP/1.1 500 Internal Server Error
    Content-Type: application/json
    
    {
        "error": "string"
    }