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

Attributes

Attribute Accepted values Default value Required Description
name A valid name for the network no Names the private network
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.
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 OK

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

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 yes Virtual network ID to join
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.

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 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.20",
         "family" : "IPv4",
         "floating" : "no"
        }
      ]
    },
    "mac": "de:ff:ff:ff:86:cf",
    "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
    "source_ip_filtering": "yes",
    "type": "private"
  }
}

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": {
    "type": "private",
    "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
    "ip_addresses": {
      "ip_address": [
        {
          "family": "IPv4",
          "address": "10.0.0.10"
        }
      ]
    }
  }
}

Attributes

Attribute Accepted values Default value Required Description
index (in path) Positive integer yes Index of the interface to modify
network A valid network unique ID no Virtual network ID to join
type private no Set the type of the virtual network
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.

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

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 OK

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.