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
Normal response
{
"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
Normal response
{
"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
{
"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
{
"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. | |
| 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. | |
| labels | list of wanted labels for the network | no | Labels describing the network, objects with both "key" and "value" defined |
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
Normal response
{
"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
{
"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.
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
{
"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
Normal response
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
Normal response
{
"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
{
"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
{
"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
{
"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
{
"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
Normal response
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
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
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
Normal response
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
Normal response
{
"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
Normal response
{
"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
{
"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
{
"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
{
"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
{
"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
Normal response
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
Normal response
{
"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
Normal response
{
"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
{
"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
{
"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
{
"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
{
"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
Normal response
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. |