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.
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"},
...
]
}
},
...
]
}
}
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 | |
| 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"},
...
]
}
}
}
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. |