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.

Request

GET /1.3/network/

Normal response

HTTP/1.0 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"
            }
          ]
        },
        "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

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

Normal response

HTTP/1.0 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"
            }
          ]
        },
        "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/
{
  "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"
          ],
          "family" : "IPv4",
          "gateway" : "172.16.0.1"
        }
      ]
    }
  }
}

Normal response

HTTP/1.0 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"
          ],
          "family": "IPv4",
          "gateway": "172.16.0.1"
        }
      ]
    }
  }
}

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_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.

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 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}

Normal response

HTTP/1.0 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"
        }
      ]
    },
    "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

PUT /1.3/network/{uuid}
{
  "network": {
    "name": "My private network",
      "ip_networks": {
        "ip_network": [
          {
            "dhcp": "no",
            "family" : "IPv4"
          }
        ]
      }
    }
}

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}
{
  "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_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.

Normal response

HTTP/1.0 200 OK
{
  "network": {
    "name": "My private network",
    "type": "private",
    "uuid": "034c12bc-cf15-4b19-97b2-0ab4e51bb98d",
    "zone": "uk-lon1",
    "ip_networks": {
      "ip_network": [
        {
          "address": "10.0.0.0/24",
          "dhcp": "no",
          "dhcp_default_route": "no",
          "family": "IPv4",
          "gateway": "10.0.0.1"
        }
      ]
    }

  }
}

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.
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}

Normal response

HTTP/1.0 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

Normal response

HTTP/1.0 200 OK
{
  "networking": {
    "interfaces": {
      "interface": [
        {
          "index": 2,
          "ip_addresses": {
            "ip_address": [
              {
                "address": "94.237.0.207",
                "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",
                "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",
                "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.

Request

POST /1.3/server/{uuid}/networking/interface
{
  "interface": {
    "type": "private",
    "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
    "ip_addresses": {
      "ip_address": [
        {
          "family": "IPv4",
          "address": "10.0.0.20"
        }
      ]
    },
    "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.

Normal response

HTTP/1.0 200 OK
{
  "interface": {
    "index": 4,
    "ip_addresses" : {
      "ip_address" : [
        {
         "address" : "10.0.0.20",
         "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}
{
  "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.0 200 OK
{
  "interface": {
    "index": 4,
    "ip_addresses" : {
      "ip_address" : [
        {
         "address" : "10.0.0.10",
         "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}

Normal response

HTTP/1.0 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.

List routers

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

Request

GET /1.3/router

Normal response

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

Get router details

Returns detailed information about a specific router.

Request

GET /1.3/router/{uuid}

Normal response

HTTP/1.0 200 OK
{
  "router": {
    "attached_networks": {
      "network": []
    },
    "name": "Example router",
    "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
{
  "router": {
    "name": "Example router"
  }
}

Attributes

Attribute Accepted values Default value Required Description
name Non-empty string yes Name of the router

Normal response

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

Modify router

Modify an existing router.

Request

PATCH /1.3/router/{uuid}
{
  "router": {
    "name": "Example router"
  }
}

Attributes

Attribute Accepted values Default value Required Description
name Non-empty string yes Name of the router

Normal response

HTTP/1.0 200 OK
{
  "router": {
    "attached_networks": {
      "network": []
    },
    "name": "Example router",
    "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.

Delete router

Delete an existing router.

Request

DELETE /1.3/router/{uuid}

Normal response

HTTP/1.0 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.