Skip to content

13. Networks

The network API calls present the different networks attached to cloud servers and allow the configuration of SDN private networks.

Networks define a secure connections between attached cloud servers using a specialised network interface. A cloud server may belong to any number of virtual networks at the same time. Server interfaces are identified and ordered by their index.

Network types

Public networks

Public networks provide internet connectivity to the cloud servers. Public networks are automatically added as public IP addresses are attached to cloud servers.

Utility network

The Utility network is a simple to use, yet functionally limited network connecting all cloud servers under the same UpCloud account. All cloud servers are connected to the Utility network by default. This way the Utility network forms a secure connection between all servers within one account, no matter where they are located. IP addressing on the Utility network is specified automatically and cannot be changed. The Utility network is limited to one connection per cloud server. SDN private networks are to be used for production workloads and any advanced network setups. The Utility network is added by adding a utility IP address.

Private virtual LAN

SDN private networks provide flexible and customisable network configuration options beyond that of the Utility network and are recommended for production workloads.

These networks provide secure connections between attached cloud servers using dedicated network interfaces. Servers can be attached and detached from SDN private networks at will using the API commands. SDN private networks allow a practically unlimited number of cloud servers to be attached simultaneously and a cloud server may belong to any number of SDN private networks at the same time. IP addressing may be defined automatically or custom IP addressing may be used. SDN private networks are configured per zone allowing cloud server on the same zone to be attached.

Available IP subnets in Private virtual LANs

Generally, you can use any global unicast address for your subnet address, even public ones. However, we recommend staying with well-known private address ranges.

Private address ranges include: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16.

Allowed subnet prefix lengths (sizes): minimum length 8 bits, maximum length 29 bits.

Excluded ranges:

  • 100.64.0.0/10 (CGNAT)
  • 127.0.0.0/8 (localhost)
  • 224.0.0.0/4 (IP multicast)
  • 169.254.0.0/16 (link local)

The above ranges are not available for use in Private virtual LANs.

List all networks

Get a list of all networks.

It is also possible to filter networks with label URL parameters, e.g. ?label=env or ?label=env%3Dprod. URL parameter can be given multiple times to add more filters (e.g. ?label=env%3Dprod&label=v2), where only networks that match all labels are returned. Label keys are matched case insensitively.

Request

GET /1.3/network/ HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "networks": {
    "network": [
      {
        "ip_networks" : {
          "ip_network": [
            {
              "address": "80.69.172.0/22",
              "dhcp": "yes",
              "dhcp_default_route": "yes",
              "dhcp_dns": [
                "94.237.127.9",
                "94.237.40.9"
              ],
              "family": "IPv4",
              "gateway": "80.69.172.1"
            }
          ]
        },
        "labels": [],
        "name": "Public 80.69.172.0/22",
        "type": "public",
        "uuid": "03000000-0000-4000-8001-000000000000",
        "zone": "fi-hel1",
        "servers": {
          "server": [
            {"uuid": "007e3200-268f-4848-8b45-bd88c44555d2", "title": "Helsinki server #1"},
            {"uuid": "00c8f13a-945a-48b8-bf5c-db2d7a3a37fe", "title": "Helsinki server #2"},
            ...
          ]
        },
        "peerings": {
           "peering": [
             {"uuid": "0f5ab9c7-959a-4bbf-9994-8322517fc359", "name": "my-peering-1", "state": "active"},
             {"uuid": "0f292fdc-73bf-4bf2-9e53-e6364de57a98", "name": "my-peering-2", "state": "active"},
             ...
            ]
        }
      },
      ...
    ]
  }
}

List networks within zone

Get a list of networks within a specific zone.

Request

GET /1.3/network/?zone={zone} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "networks": {
    "network": [
      {
        "ip_networks" : {
          "ip_network": [
            {
              "address": "80.69.172.0/22",
              "dhcp": "yes",
              "dhcp_default_route": "yes",
              "dhcp_dns": [
                "94.237.127.9",
                "94.237.40.9"
              ],
              "family": "IPv4",
              "gateway": "80.69.172.1"
            }
          ]
        },
        "labels": [],
        "name": "Public 80.69.172.0/22",
        "type": "public",
        "uuid": "03000000-0000-4000-8001-000000000000",
        "zone": "fi-hel1"
      },
      ...
    ]
  }
}

Create SDN private network

Creates a new SDN private network that cloud servers from the same zone can be attached to.

SDN private network with defined address space

POST /1.3/network/ HTTP/1.1
{
  "network": {
    "name": "Test private net",
    "zone": "uk-lon1",
    "router": "04c0df35-2658-4b0c-8ac7-962090f4e92a",
    "ip_networks" : {
      "ip_network" : [
        {
          "address" : "172.16.0.0/22",
          "dhcp" : "yes",
          "dhcp_default_route" : "no",
          "dhcp_dns" : [
            "172.16.0.10",
            "172.16.1.10"
          ],
         "dhcp_routes": [
            "192.168.0.0/24",
            "192.168.100.100/32"
         ],
          "family" : "IPv4",
          "gateway" : "172.16.0.1"
        }
      ]
    },
    "labels": [
      {
        "key": "test",
        "value": ""
      }
    ]
  }
}

Normal response

HTTP/1.1 201 OK
{
  "network": {
    "name": "Test private net",
    "type": "private",
    "uuid": "034c12bc-cf15-4b19-97b2-0ab4e51bb98d",
    "zone": "uk-lon1",
    "router": "04c0df35-2658-4b0c-8ac7-962090f4e92a",
    "ip_networks": {
      "ip_network": [
        {
          "address": "172.16.0.0/22",
          "dhcp": "yes",
          "dhcp_default_route": "no",
          "dhcp_dns" : [
            "172.16.0.10",
            "172.16.1.10"
          ],
         "dhcp_routes": [
            "192.168.0.0/24",
            "192.168.100.100/32"
         ],
          "family": "IPv4",
          "gateway": "172.16.0.1"
        }
      ]
    },
   "labels": [
     {
       "key": "test",
       "value": ""
     }
   ]
  }
}

Attributes

Attribute Accepted values Default value Required Description
name A valid name for the network yes Names the network
zone A valid zone name yes The zone in which the network is configured.
router An existing router UUID, empty string or null no Add this network to an existing router.
ip_networks Array of IP networks, see below yes Array of IP networks under ip_network
labels List of wanted labels for the network no Labels describing the network, objects with both "key" and "value" defined

The ip_networks block expects an ip_network-named array with the following possible arguments.

Attribute Accepted values Default value Required Description
address Address block with netmask yes Sets address space for the network. Please see restrictions
dhcp yes / no yes Toggles DHCP service for the network.
dhcp_default_route yes / no yes / no no Defines if the gateway should be given as default route by DHCP. Defaults to yes on public networks, and no on other ones.
dhcp_dns IP addresses separated by a comma no Defined DNS server addresses given by DHCP. Not implemented on SDN private networks.
dhcp_routes An array of valid IPv4 or IPv6 prefix strings no Defines additional DHCP classless static routes to be delivered if the DHCP is enabled. Nexthop will be IP network gateway address.
dhcp_bootfile_url TFTP URL no TFTP URL to boot file given by DHCP. For example tftp://172.16.0.253/pxelinux.0
family IPv4 yes IP address family. Currently only IPv4 networks are supported.
gateway IPv4 address no Gateway address given by the DHCP service. Defaults to first address of the network if not given.

The labels block may include 0-255 key-value pairs for classifying the network.

Attribute Accepted values Default value Required Description
key 1-32 upper and lower case letters, numbers, - & _. Cannot start with _ yes Key representing the label
value 0-255 characters yes Key representing the value

Error responses

HTTP status Error code Description
400 Bad Request NETWORK_NAME_INVALID The network name has an invalid value.
400 Bad Request NETWORK_NAME_MISSING The required attribute name is missing from the request.
400 Bad Request NETWORK_TYPE_INVALID The network type has an invalid value.
400 Bad Request NETWORK_TYPE_MISSING The required attribute type is missing from the request.
400 Bad Request DHCP_ROUTES_INVALID One of the ip networks contains invalid dhcp_routes value
400 Bad Request ZONE_INVALID The network zone has an invalid value.
400 Bad Request ZONE_MISSING The required attribute zone is missing from the request.

Get network details

Retrieves the details of a specific network.

Request

GET /1.3/network/{uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "network": {
    "name": "Test private net",
    "type": "private",
    "uuid": "034c12bc-cf15-4b19-97b2-0ab4e51bb98d",
    "zone": "uk-lon1",
    "ip_networks" : {
      "ip_network" : [
        {
          "address" : "172.16.0.0/22",
          "dhcp" : "yes",
          "dhcp_default_route" : "no",
          "dhcp_dns" : [
            "172.16.0.10",
            "172.16.1.10"
          ],
          "family" : "IPv4",
          "gateway" : "172.16.0.1"
        }
      ]
    },
    "labels": [],
    "servers": {
      "server": [
        {"uuid": "009d64ef-31d1-4684-a26b-c86c955cbf46", "title": "London server #1"},
        {"uuid": "0035079f-9d66-42d5-aa74-12090e7b4ed1", "title": "London server #2"},
        ...
      ]
    },
   "peerings": {
      "peering": [
        {"uuid": "0f5ab9c7-959a-4bbf-9994-8322517fc359", "name": "my-peering-1", "state": "active"},
        {"uuid": "0f292fdc-73bf-4bf2-9e53-e6364de57a98", "name": "my-peering-2", "state": "active"},
        ...
      ]
   }
  }
}

Error responses

HTTP status Error code Description
403 Forbidden NETWORK_FORBIDDEN No permission to access details of the specified network.
404 Not Found NETWORK_NOT_FOUND The network {uuid} does not exist.

Modify network details

Modifies the details of a specific SDN private network. The Utility and public networks cannot be modified.

Request

PUT /1.3/network/{uuid} HTTP/1.1
{
  "network": {
    "name": "My private network",
    "ip_networks": {
      "ip_network": [
        {
          "address": "172.16.0.0/22",
          "dhcp": "yes",
          "dhcp_default_route": "no",
          "dhcp_dns" : [
            "172.16.0.10",
            "172.16.1.10"
          ],
          "dhcp_routes": [
            "192.168.0.0/24",
            "192.168.100.100/32"
          ],
          "family": "IPv4",
          "gateway": "172.16.0.1"
        }
      ]
    },
    "labels": [
     {
       "key": "purpose",
       "value": "databases"
     }
    ]
  }
}

Attaching to a router

Private networks can be attached to an existing router by specifying the UUID of the router in the router field.

PUT /1.3/network/{uuid} HTTP/1.1
{
  "network": {
    "router": "04c0df35-2658-4b0c-8ac7-962090f4e92a"
  }
}

Attributes

Attribute Accepted values Default value Required Description
name A valid name for the network no Names the private network
router An existing router UUID, empty string or null no Change or clear the router attachment.
dhcp yes / no yes Toggles DHCP service for the network
family IPv4 yes IP address family. Currently only IPv4 networks are supported.
dhcp_default_route yes / no yes / no no Defines if the gateway should be given as default route by DHCP. Defaults to yes on public networks, and no on other ones.
dhcp_dns IP addresses separated by a comma no Defines DNS server addresses given by the DHCP.
dhcp_routes An array of valid IPv4 or IPv6 prefix strings no Defines additional DHCP classless static routes to be delivered if the DHCP is enabled. Nexthop will be IP network gateway address.
dhcp_bootfile_url TFTP URL no TFTP URL to boot file given by DHCP. For example tftp://172.16.0.253/pxelinux.0
gateway IPv4 address no Gateway address given by the DHCP service. Defaults to first address of the network if not given.
labels list of wanted labels for the network no Labels describing the network, objects with both "key" and "value" defined

Normal response

HTTP/1.1 200 OK
{
  "network": {
    "name": "My private network",
    "type": "private",
    "uuid": "034c12bc-cf15-4b19-97b2-0ab4e51bb98d",
    "zone": "uk-lon1",
    "ip_networks": {
      "ip_network": [
        {
          "address": "172.16.0.0/22",
          "dhcp": "yes",
          "dhcp_default_route": "no",
          "dhcp_dns" : [
            "172.16.0.10",
            "172.16.1.10"
          ],
          "dhcp_routes": [
            "192.168.0.0/24",
            "192.168.100.100/32"
          ],
          "family": "IPv4",
          "gateway": "172.16.0.1"
        }
      ]
    },
    "labels": [
      {
        "key": "purpose",
        "value": "databases"
      }
    ]
  }
}

Error responses

HTTP status Error code Description
400 Bad Request NETWORK_NAME_INVALID The network name has an invalid value
400 Bad Request NETWORK_TYPE_INVALID The network type has an invalid value
400 Bad Request ZONE_INVALID The network zone has an invalid value
400 Bad Request UNKNOWN_ATTRIBUTE The request body contains an unknown attribute
400 Bad Request DUPLICATE_LABEL_KEYS Label keys must be unique
400 Bad Request INVALID_LABEL_KEY Invalid label key in query parameters
400 Bad Request INVALID_LABEL_VALUE Invalid label value in query parameters
400 Bad Request DHCP_ROUTES_INVALID One of the ip networks contains invalid dhcp_routes value
403 Forbidden NETWORK_FORBIDDEN No permission to modify the details of the specified network

Delete network

Deletes an SDN private network. All attached cloud servers must first be detached before SDN private networks can be deleted. Utility and public networks can only be detached from servers by Releasing the corresponding IP addresses.

Request

DELETE /1.3/network/{uuid} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status Error code Description
403 Forbidden NETWORK_FORBIDDEN No permission to delete the specified network.
404 Not Found NETWORK_NOT_FOUND The network {uuid} does not exist.
409 Conflict NETWORK_NOT_EMPTY All cloud servers must be detached before the network can be deleted.

List server networks

List all networks the specific cloud server is connected to.

Request

GET /1.3/server/{uuid}/networking HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "networking": {
    "interfaces": {
      "interface": [
        {
          "index": 2,
          "ip_addresses": {
            "ip_address": [
              {
                "address": "94.237.0.207",
                "dhcp_provided": "yes",
                "family": "IPv4"
              }
            ]
          },
          "mac": "de:ff:ff:ff:66:89",
          "network": "037fcf2a-6745-45dd-867e-f9479ea8c044",
          "source_ip_filtering": "yes",
          "type": "public",
          "bootable": "no"
        },
        {
          "index": 3,
          "ip_addresses": {
            "ip_address": [
              {
                "address": "10.199.3.15",
                "dhcp_provided": "yes",
                "family": "IPv4"
              }
            ]
          },
          "mac": "de:ff:ff:ff:ed:85",
          "network": "03c93fd8-cc60-4849-91b8-6e404b228e2a",
          "source_ip_filtering": "yes",
          "type": "utility",
          "bootable": "no"
        },
        {
          "index": 4,
          "ip_addresses": {
            "ip_address": [
              {
                "address": "10.0.0.20",
                "dhcp_provided": "yes",
                "family": "IPv4"
              }
            ]
          },
          "mac": "de:ff:ff:ff:cc:20",
          "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
          "source_ip_filtering": "yes",
          "type": "private",
          "bootable": "no"
        }
      ]
    }
  }
}

Error responses

HTTP status Error code Description
404 Not Found SERVER_NOT_FOUND The server {uuid} does not exist.

Create network interface

Creates a new network interface on the specific cloud server and attaches the specified SDN private network to the new interface. The server state must be stopped. The combined limit of network interfaces and storage devices is 24.

Request

POST /1.3/server/{uuid}/networking/interface HTTP/1.1
{
  "interface": {
    "type": "private",
    "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
    "ip_addresses": {
      "ip_address": [
        {
          "family": "IPv4",
          "address": "10.0.0.20",
          "dhcp_provided": "yes"
        },
        {
          "family": "IPv4",
          "address": "10.0.0.30"
        }
      ]
    },
    "source_ip_filtering": "yes"
  }
}

Attributes

Attribute Accepted values Default value Required Description
network A valid network unique ID (varies) Virtual network ID to join. Required for private interfaces. Setting it in public and utility interfaces requires special privileges.
type public / utility / private yes Set the type of the network
index Positive integer Next available no Interface index
ip_addresses IP address array, see below yes Array of IP addresses under ip_address
source_ip_filtering yes / no yes no Whether source IP filtering is enabled on the interface. Disabling it is allowed only for SDN private interfaces.
bootable yes / no no no Whether to try booting through the interface.

Disabling the source IP filtering allows sourcing traffic from other IP addresses than allocated to virtual servers within the network, for example when a virtual server is acting as a NAT gateway or a site-to-site VPN endpoint.

ip_addresses block expects an ip_address-named array with following possible arguments.

Attribute Accepted values Default value Required Description
family IPv4 / IPv6 IPv4 yes Address family of the address. Currently IPv6 is only supported with public type interfaces.
address IPv4 / IPv6 address no A valid IP address within the IP space of the network. If not given, the next free address is selected. Specifying an address in public and utility interfaces requires special privileges.
dhcp_provided yes / no no In case of multiple IP addresses attached to the interface, the one marked with dhcp_provided flag is the one offered by the DHCP server. By default, the dhcp_provided is set to yes for the first IP address in the array.

Normal response

HTTP/1.1 200 OK
{
  "interface": {
    "index": 4,
    "ip_addresses" : {
      "ip_address" : [
        {
         "address" : "10.0.0.20",
         "dhcp_provided": "yes",
         "family" : "IPv4",
         "floating" : "no"
        },
        {
         "address" : "10.0.0.30",
         "dhcp_provided": "no",
         "family" : "IPv4",
         "floating" : "no"
        }
      ]
    },
    "mac": "de:ff:ff:ff:86:cf",
    "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
    "source_ip_filtering": "yes",
    "type": "private",
    "bootable": "no"
  }
}

Error responses

HTTP status Error code Description
404 Not Found SERVER_NOT_FOUND The server does not exist.
404 Not Found NETWORK_NOT_FOUND The network {uuid} does not exist.
409 Conflict INTERFACE_EXISTS The interface specified with index already exists.
409 Conflict SERVER_STATE_ILLEGAL The operation is not available for other than stopped servers.

Modify network interface

Modifies the network interface at the selected index on the specific cloud server. This operation is used to change the attached SDN private network or for reordering the network interface. The server state must be stopped.

Request

PUT /1.3/server/{uuid}/networking/interface/{index} HTTP/1.1
{
  "interface": {
    "ip_addresses": {
      "ip_address": [
        {
          "family": "IPv4",
          "address": "10.0.0.10"
        }
      ]
    },
    "source_ip_filtering": "no",
    "bootable": "yes"
  }
}

Attributes

Attribute Accepted values Default value Required Description
index (in path) Positive integer yes Index of the interface to modify
index (in body) Positive integer index in path no New index for the interface
ip_addresses IP address array, see below no Array of IP addresses under ip_address
source_ip_filtering yes / no no Whether source IP filtering is enabled on the interface. Disabling it is allowed only for SDN private interfaces.
bootable yes / no no Whether to try booting through the interface.

Disabling the source IP filtering allows sourcing traffic from other IP addresses than allocated to virtual servers within the network, for example when a virtual server is acting as a NAT gateway or a site-to-site VPN endpoint.

ip_addresses block expects an ip_address-named array with following possible arguments. Mentioned attributes are required only if the ip_addresses block is included in the request.

Attribute Accepted values Default value Required Description
family IPv4 yes Currently only IPv4 is supported in private networks.
address IPv4 address no A valid IP address within the IP space of the network. If not given, the next free address is selected.

Normal response

HTTP/1.1 200 OK
{
  "interface": {
    "index": 4,
    "ip_addresses" : {
      "ip_address" : [
        {
         "address" : "10.0.0.10",
         "dhcp_provided": "yes",
         "family" : "IPv4",
         "floating" : "no"
        }
      ]
    },
    "mac": "de:ff:ff:ff:86:cf",
    "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
    "source_ip_filtering": "yes",
    "type": "private",
    "bootable": "no"
  }
}

Error responses

HTTP status Error code Description
404 Not Found SERVER_NOT_FOUND The server {uuid} does not exist.
404 Not Found INTERFACE_NOT_FOUND The network interface {index} does not exist.
409 Conflict INTERFACE_EXISTS The interface specified with index in body already exists.
409 Conflict SERVER_STATE_ILLEGAL The operation is not available for other than stopped servers.

Delete network interface

Detaches an SDN private network from a cloud server by deleting the network interface at the selected index on the specific cloud server. The server state must be stopped.

Request

DELETE /1.3/server/{uuid}/networking/interface/{index} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status Error code Description
404 Not Found SERVER_NOT_FOUND The server {uuid} does not exist.
404 Not Found INTERFACE_NOT_FOUND The network interface {index} does not exist.
409 Conflict SERVER_STATE_ILLEGAL The operation is not available for other than stopped servers.

Assign IP address to network interface

Assigns a new ip address to a private network interface by given server uuid {uuid} and interface index {index}.

There is a maximum of five IP addresses per private network interface.

Request

POST /1.3/server/{uuid}/networking/interface/{index}/ip-address?force=no HTTP/1.1
{
  "ip_address": {
    "family": "IPv4",
    "address": "10.0.0.30"
  }
}

Attributes

Attribute Accepted values Required Description
family IPv4 / IPv6 yes Address family of the address.
address IPv4 / IPv6 address no A valid IP address within the IP space of the network. If not given, the next free address is selected.
force (url query) yes / no no If an IP address is already assigned in the network and source interface has more than one IP, the IP address will be detached from the source interface and assigned to the target interface.

Normal response

HTTP/1.1 200 OK
{
  "ip_address": {
    "address": "10.0.0.30",
    "dhcp_provided": "no",
    "family": "IPv4"
  }
}

Error responses

HTTP status Error code Description
404 Not Found SERVER_NOT_FOUND The server {uuid} does not exist.
404 Not Found INTERFACE_NOT_FOUND The interface {index} does not exist.
409 Conflict INTERFACE_FORBIDDEN Operation forbidden for the type of the specified interface.
409 Conflict ADDRESS_ATTACHED The specified IP address is already attached to the target interface.
409 Conflict DUAL_STACK_INTERFACE The specified interface has IP addresses from a different family than the one in the payload. Dual stack interfaces are not supported at this time.
409 Conflict IP_ADDRESS_RESOURCES_UNAVAILABLE There are currently no IP addresses available in the requested network.
409 Conflict ADDRESS_INVALID Provided IP address is not valid for the network.
409 Conflict IP_ADDRESS_LIMIT_REACHED Limit of allowed IP addresses reached for the interface.

Delete IP address from network interface

Deletes IP address by given {address} from the network interface.

Request

DELETE /1.3/server/{uuid}/networking/interface/{index}/ip-address/{address} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status Error code Description
404 Not Found SERVER_NOT_FOUND The server {uuid} does not exist.
404 Not Found INTERFACE_NOT_FOUND The interface {index} does not exist.
409 Conflict INTERFACE_FORBIDDEN Operation forbidden for the type of the specified interface.
409 Conflict IP_ADDRESS_LIMIT_REACHED Allowed limit ip addresses per interface reached.

List routers

Returns a list of all available routers associated with the current account.

It is also possible to filter routers with label URL parameters, e.g. ?label=env or ?label=env%3Dprod. URL parameter can be given multiple times to add more filters (e.g. ?label=env%3Dprod&label=v2), where only routers that match all labels are returned. Label keys are matched case insensitively.

Request

GET /1.3/router HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "routers": {
    "router": [
      {
        "attached_networks": {
          "network": []
        },
        "labels": [],
        "name": "Example router",
        "static_routes": [],
        "type": "normal",
        "uuid": "04c0df35-2658-4b0c-8ac7-962090f4e92a"
      }
    ]
  }
}

Get router details

Returns detailed information about a specific router.

Request

GET /1.3/router/{uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "router": {
    "attached_networks": {
      "network": []
    },
    "labels": [],
    "name": "Example router",
    "static_routes": [],
    "type": "normal",
    "uuid": "04c0df35-2658-4b0c-8ac7-962090f4e92a"
  }
}

Error responses

HTTP status Error code Description
404 Not Found ROUTER_NOT_FOUND The router {uuid} does not exist.

Create router

Creates a new router. Routers can be used to connect multiple Private Networks. Cloud Servers on any attached network can communicate directly with each other.

Request

POST /1.3/router HTTP/1.1
{
  "router": {
    "name": "Example router",
    "static_routes": [
      {
        "route": "0.0.0.0/0",
        "nexthop": "10.0.0.100",
        "name": "static_route_0"
      }
    ]
  }
}

Attributes

Attribute Accepted values Default value Required Description
name Non-empty string yes Name of the router
static_routes 0-50 static_route blocks no Contains static_route blocks that define static routes for this router.

The static_routes block may contain 0-50 static_route blocks. Each block can have the following attributes:

Attribute Accepted values Default value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ static-route-X no Name or description of the route.
route Valid IPv4 or IPv6 prefix yes Destination prefix of the route.
nexthop Valid IPv4 or IPv6 address yes Next hop address. NOTE: For static route to be active the next hop has to be an address of a reachable running Cloud Server in one of the Private Networks attached to the router.

Normal response

HTTP/1.1 201 Created
{
  "router": {
    "attached_networks": {
      "network": []
    },
    "labels": [],
    "name": "Example router",
    "static_routes": [],
    "type": "normal",
    "uuid": "04c0df35-2658-4b0c-8ac7-962090f4e92a"
  }
}

Error responses

HTTP status Error code Description
400 Bad Request ROUTER_NAME_MISSING The required attribute name is missing.
400 Bad Request DUPLICATE_ROUTE One of the static_routes is a duplicate.
400 Bad Request NEXTHOP_INVALID Next hop value for one of the static_routes is not valid.
400 Bad Request STATIC_ROUTE_TARGET_INVALID One of the static_routes has invalid value for target (route).
400 Bad Request INVALID_ROUTE One of the static_routes objects has invalid format.
400 Bad Request INVALID_ROUTE_FAMILY One of the static_routes has invalid IP family for next hop.
400 Bad Request DUPLICATE_LABEL_KEYS Label keys must be unique.
400 Bad Request INVALID_LABEL_KEY Invalid label key in query parameters.
400 Bad Request INVALID_LABEL_VALUE Invalid label value in query parameters.
409 Conflict STATIC_ROUTE_LIMIT_REACHED Amount of static_routes for this router is above the allowed limit.

Modify router

Modify an existing router.

Request

PATCH /1.3/router/{uuid} HTTP/1.1
{
  "router": {
    "name": "Example router",
    "labels": [
      {
        "key": "service",
        "value": "postgres cluster connectivity"
      }
    ],
    "static_routes": []
  }
}

Attributes

Attribute Accepted values Default value Required Description
name Non-empty string yes Name of the router
static_routes 0-50 static_route blocks no Contains static_route blocks that define static routes for this router.
labels list of wanted labels for the router no Labels describing the router, objects with both "key" and "value" defined

The static_routes block may contain 0-50 static_route blocks. Each block can have the following attributes:

Attribute Accepted values Default value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ static-route-X no Name or description of the route.
route Valid IPv4 or IPv6 prefix yes Destination prefix of the route.
nexthop Valid IPv4 or IPv6 address yes Next hop address. NOTE: For static route to be active the next hop has to be an address of a reachable running Cloud Server in one of the Private Networks attached to the router.

The labels block may contain 0-255 label objects. Details are available in network creation section.

Normal response

HTTP/1.1 200 OK
{
  "router": {
    "attached_networks": {
      "network": []
    },
    "labels": [
      {
        "key": "service",
        "value": "postgres cluster connectivity"
      }
    ],
    "name": "Example router",
    "static_routes": [],
    "type": "normal",
    "uuid": "04c0df35-2658-4b0c-8ac7-962090f4e92a"
  }
}

Error responses

HTTP status Error code Description
404 Not Found ROUTER_NOT_FOUND The router {uuid} does not exist.
400 Bad Request DUPLICATE_ROUTE One of the static_routes is a duplicate.
400 Bad Request NEXTHOP_INVALID Next hop value for one of the static_routes is not valid.
400 Bad Request STATIC_ROUTE_TARGET_INVALID One of the static_routes has invalid value for target (route).
400 Bad Request INVALID_ROUTE One of the static_routes objects has invalid format.
400 Bad Request INVALID_ROUTE_FAMILY One of the static_routes has invalid IP family for next hop.
400 Bad Request DUPLICATE_LABEL_KEYS Label keys must be unique.
400 Bad Request INVALID_LABEL_KEY Invalid label key in query parameters.
400 Bad Request INVALID_LABEL_VALUE Invalid label value in query parameters.
409 Conflict STATIC_ROUTE_LIMIT_REACHED Amount of static_routes for this router is above the allowed limit.

Delete router

Delete an existing router.

Request

DELETE /1.3/router/{uuid} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status Error code Description
404 Not Found ROUTER_NOT_FOUND The router {uuid} does not exist.
400 Conflict ROUTER_ATTACHED The router has attached networks.

List network peerings

Get a list of all peerings within the current account. Only peerings that refer to a network that the current account has access are returned.

It is also possible to filter network peering with label URL parameters, e.g. ?label=env or ?label=env%3Dprod. The URL parameter can be given multiple times to add more filters (e.g. ?label=env%3Dprod&label=v2), where only network peering that match all labels are returned. Label keys are matched case insensitively.

Request

GET /1.3/network-peering HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "network_peerings": {
    "network_peering": [
      {
        "configured_status": "active",
        "labels": [
          {
            "key": "env",
            "value": "prod"
          }
        ],
        "name": "Peering A->B",
        "network": {
          "ip_networks": {
            "ip_network": [
              {
                "address": "192.168.0.0/24",
                "family": "IPv4"
              },
              {
                "address": "fc02:c4f3::/64",
                "family": "IPv6"
              }
            ]
          },
          "uuid": "03126dc1-a69f-4bc2-8b24-e31c22d64712"
        },
        "peer_network": {
          "ip_networks": {
            "ip_network": [
              {
                "address": "192.168.99.0/24",
                "family": "IPv4"
              },
              {
                "address": "fc02:c4f3:99::/64",
                "family": "IPv6"
              }
            ]
          },
          "uuid": "03585987-bf7d-4544-8e9b-5a1b4d74a333"
        },
        "state": "active",
        "uuid": "0f7984bc-5d72-4aaf-b587-90e6a8f32efc"
      }
    ]
  }
}

Get network peering details

Returns the state of an existing network peering.

Note that the peer_network field only contains the network details if the peering has been defined by both accounts.

Peering states

State Description
pending-peer Peering is pending for the other account to create a corresponding peering.
active Peering is active and in use.
provisioning Peering is being applied. This is a transitionary state.
conflict-subnet Peering network subnets overlap with each other.
missing-local-router Local router has been deleted. Peering cannot be activated.
missing-peer-router The peer network router is missing or has been deleted. Peering cannot be activated.
deleted-peer-network The peer has deleted their network. The peering cannot be activated and should be deleted.
disabled This peer has been disabled by the user.
peer-disabled The peer has disabled their side of the peering.
error The peering is in unexpected error state. Please contact the support.

Request

GET /1.3/network-peering/{uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "network_peering": {
    "configured_status": "active",
    "labels": [
      {
        "key": "env",
        "value": "prod"
      }
    ],
    "name": "Peering A->B",
    "network": {
      "ip_networks": {
        "ip_network": [
          {
            "address": "192.168.0.0/24",
            "family": "IPv4"
          },
          {
            "address": "fc02:c4f3::/64",
            "family": "IPv6"
          }
        ]
      },
      "uuid": "03126dc1-a69f-4bc2-8b24-e31c22d64712"
    },
    "peer_network": {
      "ip_networks": {
        "ip_network": [
          {
            "address": "192.168.99.0/24",
            "family": "IPv4"
          },
          {
            "address": "fc02:c4f3:99::/64",
            "family": "IPv6"
          }
        ]
      },
      "uuid": "03585987-bf7d-4544-8e9b-5a1b4d74a333"
    },
    "state": "active",
    "uuid": "0f7984bc-5d72-4aaf-b587-90e6a8f32efc"
  }
}

Error responses

HTTP status Error code Description
404 Not found PEERING_NOT_FOUND The peering was not found.

Create network peering

Network peerings are used to enable traffic between two networks that can be on different main accounts. The peering must be established both ways before it's considered as active. Peering is only supported between networks of type private.

Note: you should only create peering between accounts and networks you trust. There is no limits on what traffic can flow. The server firewall has no effect for private type networks.

It is required that both networks have a Router attached to the network.

Request

POST /1.3/network-peering HTTP/1.1
{
  "network_peering": {
    "configured_status": "active",
    "name": "Peering A->B",
    "network": {
      "uuid": "03126dc1-a69f-4bc2-8b24-e31c22d64712"
    },
    "peer_network": {
      "uuid": "03585987-bf7d-4544-8e9b-5a1b4d74a333"
    },
    "labels": [
      {
        "key": "env",
        "value": "staging"
      },
      {
        "key": "foo",
        "value": "bar"
      }
    ]
  }
}

Attributes

Attribute Accepted values Default value Required Description
configured_status Either activeor disabled active no Controls whether the peering is administratively up or down.
name String with length 1 to 255 yes Descriptive name for the peering.
network.uuid Valid network UUID yes Sets the local network of the peering.
peer_network.uuid Valid network UUID yes Sets the peer network of the peering.
labels list of wanted labels for the peering no Labels describing the peering, objects with both "key" and "value" defined.

The labels block may include key-value pairs for classifying the storage.

Attribute Accepted values Default value Required Description
key 1-32 upper and lower case letters, numbers, - & _. Cannot start with _ yes Key representing the label
value 0-255 characters yes Key representing the value

Labels can include specific service labels that cannot be modified. These always start with _ and do not conflict with normal labels.

Normal response

HTTP/1.1 201 Created
{
  "network_peering": {
    "configured_status": "active",
    "labels": [
      {
        "key": "env",
        "value": "prod"
      }
    ],
    "name": "Peering A->B",
    "network": {
      "ip_networks": {
        "ip_network": [
          {
            "address": "192.168.0.0/24",
            "family": "IPv4"
          },
          {
            "address": "fc02:c4f3::/64",
            "family": "IPv6"
          }
        ]
      },
      "uuid": "03126dc1-a69f-4bc2-8b24-e31c22d64712"
    },
    "peer_network": {
      "uuid": "03585987-bf7d-4544-8e9b-5a1b4d74a333"
    },
    "state": "pending-peer",
    "uuid": "0f7984bc-5d72-4aaf-b587-90e6a8f32efc"
  }
}

Note: The above describes a response of a peering that has not been established both ways. Refer to Get network peering details for description of the states.

Error responses

HTTP status Error code Description
409 Conflict LOCAL_NETWORK_NO_ROUTER The local network has no router.
404 Not found NETWORK_NOT_FOUND The local network was not found.
404 Not found PEER_NETWORK_NOT_FOUND Peer network was not found.
409 Conflict PEERING_CONFLICT The peering between these accounts already exists.
409 Conflict LABEL_LIMIT_REACHED Maximum number of labels per resource reached.

Modify network peering

Modifies an existing network peering.

Request

PATCH /1.3/network-peering/{uuid} HTTP/1.1
{
  "network_peering": {
    "configured_status": "disabled",
    "name": "Peering A->B modified",
    "labels": [
      {
       "key": "env",
       "value": "staging"
      },
      {
       "key": "foo",
       "value": "bar"
      }
     ]
  }
}

Attributes

Attribute Accepted values Default value Required Description
configured_status Either activeor disabled current value no Controls whether the peering is administratively up or down.
name String with length 1 to 255 current value no Descriptive name for the peering.
labels list of wanted labels for the peering no Labels describing the peering, objects with both "key" and "value" defined.

Normal response

HTTP/1.1 200 OK
{
  "network_peering": {
    "configured_status": "disabled",
    "labels": [
      {
        "key": "env",
        "value": "prod"
      }
    ],
    "name": "Peering A->B modified",
    "network": {
      "ip_networks": {
        "ip_network": [
          {
            "address": "192.168.0.0/24",
            "family": "IPv4"
          },
          {
            "address": "fc02:c4f3::/64",
            "family": "IPv6"
          }
        ]
      },
      "uuid": "03126dc1-a69f-4bc2-8b24-e31c22d64712"
    },
    "peer_network": {
      "ip_networks": {
        "ip_network": [
          {
            "address": "192.168.99.0/24",
            "family": "IPv4"
          },
          {
            "address": "fc02:c4f3:99::/64",
            "family": "IPv6"
          }
        ]
      },
      "uuid": "03585987-bf7d-4544-8e9b-5a1b4d74a333"
    },
    "state": "provisioning",
    "uuid": "0f7984bc-5d72-4aaf-b587-90e6a8f32efc"
  }
}

Error responses

HTTP status Error code Description
404 Not found PEERING_NOT_FOUND The peering was not found.
409 Conflict LABEL_LIMIT_REACHED Maximum number of labels per resource reached.

Delete network peering

Deletes a network peering. It is required that the peering is in disabled state before delete is possible.

Request

DELETE /1.3/network-peering/{uuid} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status Error code Description
404 Not found PEERING_NOT_FOUND The peering was not found.
409 Conflict PEERING_NOT_DISABLED Peering is not in disabled operational state.