VDC API: How to create a network

Introduction

This document describes how to use the API interface to create networks. For a guide to using the VDC Control Centre graphical interface to create networks, see How to create a network for your VDC.

Prerequisites

To use the API interface to access a VDC account, you need to have a pair of secure keys ('API key' and 'secret key'). You can generate or replace keys in the MyServices portal; see instructions in Introduction to the API.

You are recommended to install the open source command line tool, Cloudmonkey, to work with the API. See the Introduction to the API for instructions.

Types of network in VDC

There are five types of network available in VDC. You may see alternative names for these in other information about VDC, or other Interoute products. Alternative names are noted in each case.

The types can be categorised as 'Local' or 'Direct Connect'. In VDC network information you will see these named as 'Isolated' and 'Shared', respectively.

  • Local with Internet Gateway (alternative name: 'Private with Gateway Services'): A network with internet connection and related services for firewall, NAT (port forwarding), load balancing and IPSEC VPN.

  • Local Private (alternative name: 'Isolated'): A local network with no internet connection or services. This type of network has no virtual router: please note that this has some effects you may not expect for setting up and configuring virtual machines.

  • Public Direct Connect (alternative name: 'IPAC network'): A network which contains a range of public IP addresses that are directly accessible from the Internet. This is used for example if you want to connect a virtual firewall appliance directly into the Internet.

  • Private Direct Connect network in a Direct Connect Group (alternative name: 'MPLS IPVPN network'): Private networks between VDC zones are provided free to all VDC customers; these networks use Interoute's global fibre network to offer fast and high-capacity networks which can connect your VMs in any of the VDC zones. Each Private Direct Connect network (within one zone) must belong to a Direct Connect Group, which enables the inter-connection between the zones.

  • Private Direct Connect network with gateway services egress: Private MPLS network (same functionality as the previous type) with additional egress-only connection to the Internet; this is useful, for example, in a case where you have server or container host virtual machines which require always-on outbound Internet access to software repositories.

Direct Connect networks may take up to 24 hours to activate. The listNetworks command has an 'isprovisioned' response which shows if a network is active and available for use. Please contact Interoute support if you have any queries about the availability of a new network.

The network types are known by various names in VDC, as shown in the following table. The column headings show the parameter/response names used in the VDC API.

displayednetworktype networkofferingname type subtype
Internet Gateway PrivateWithGatewayServices Isolated internetgateway
Private Isolated Isolated private
Direct Connect (public) IPAC/IPVPN Shared publicdirectconnect
Direct Connect (private) IPAC/IPVPN Shared privatedirectconnect
Direct Connect (private with GW services) SharedWithGatewayServicesEgress Shared privatedirectconnectwithgatewayservicesegress
Unknown IPAC/IPVPN Shared unknown

The type 'Unknown' usually applies to a system network (such as those used by vTools) and it should not appear for customer-controlled networks.

Creating a 'Local with Internet Gateway' network

Local with Internet Gateway is the standard network type for connecting virtual machines to the Internet, and to each other within the same zone. The network has a 'virtual router' (VR) which provides a firewall, load balancing, and NAT port-forwarding. The VR is also used to communicate information to each VM, notably DHCP services for the VM to automatically set its own IP network configuration.

In a new VDC account you will find a 'default network' of this type already created in each zone. When created, the network has a completely closed firewall. You have full control over the inbound and outbound traffic of the network: you can add egress rules for outbound traffic, and port forwarding or load balancing rules for inbound traffic.

Another service provided by this network type is an IPSEC VPN (virtual private network). This allows remote client computers to use the Internet to make an encrypted connection by 'tunneling' in to become part of your VDC network. You will need suitable client software on your own computers; for example, you can use the built-in clients provided for Windows or Mac OS.

The API command createLocalNetwork will create a network based on the following inputs, all of which are required:

  • zonename: the name of the zone where the network will be created

  • cidr: the CIDR of the IP address range for the network (usually of size '/24')

  • gateway: the IP address of the network gateway

  • displaytext: description text for the network

Note: the network 'name' is not user-defined and it will be set using the pattern: 'Network Local VDC_ACCOUNT_NAME NUM' (where NUM is a number that increments with each new network of the given type).

Important

It is your own responsibility to check that the CIDR you choose is unique for this Local network in this region. VDC will not raise an error if you use the same CIDR range for more than one network.

 

Here is an example API call using Cloudmonkey, with the (abbreviated) output:

(local) > createLocalNetwork displaytext='test-LWIG-1' zonename='Frankfurt (ESX)' ↩
   cidr=192.168.227.0/24 gateway=192.168.227.254
count = 1
localnetwork:
+--------------------------------------+------+------------------+-----------------+-----------------+
|                zoneid                | sid  |       cidr       |     gateway     |    zonename     |
+--------------------------------------+------+------------------+-----------------+-----------------+
| 7144b207-e97e-4e4a-b15d-64a30711e0e7 | None | 192.168.227.0/24 | 192.168.227.254 | Frankfurt (ESX) |
+--------------------------------------+------+------------------+-----------------+-----------------+

The 'gateway' address can be chosen anywhere in the CIDR range, but '.254' or '.1' are conventional choices.

Creating a 'Local Private' network

A Local Private network functions as a Local network without the virtual router which provides Internet connection and network-related services. Hence it can be used as a 'private' network, for example the network architecture for a web-based application will typically place database server VMs on a private network.

The lack of a virtual router does have the following consequences for VM deployment and configuration which you will need to deal with:

  • There is no DHCP service on the network, therefore a deployed VM cannot query the network to configure its network interface. You will need to login via the VM console and manually configure the VM's network, hostname, etc.

  • VDC cannot set or reset a VM root password. The password set at deployment will be the default root password for the operating system. However VDC will incorrectly report that it has installed a randomised password.

  • VDC cannot bootstrap a VM by the passing of 'userdata' to initialisation scripts on the VM.

The API call createLocalNetwork will create a Local Private network based on the following inputs. You omit 'gateway' to make the created network of Local Private type. All of these inputs are required:

  • zonename: the name of the zone where the network will be created

  • cidr: the CIDR of the IP address range for the network (usually of size '/24')

  • displaytext: description text for the network

The network 'name' is not user-defined and it will be set using the pattern: 'Network Local VDC_ACCOUNT_NAME NUM' (where NUM is a number that increments with each new network of the given type).

Important

It is your own responsibility to check that the CIDR you choose is unique for this Local network in this region. VDC will not raise an error if you use the same CIDR range for more than one network.

 

Here is an example API call using Cloudmonkey, with the output:

(local) > createLocalNetwork displaytext='test-PRIVATE-1' zonename='Frankfurt (ESX)' ↩
   cidr=192.168.228.0/24
count = 1
localnetwork:
+---------+------+------------------+--------------------------------------+-----------------+
| gateway | sid  |       cidr       |                zoneid                |     zonename    |
+---------+------+------------------+--------------------------------------+-----------------+
|   None  | None | 192.168.228.0/24 | 7144b207-e97e-4e4a-b15d-64a30711e0e7 | Frankfurt (ESX) |
+---------+------+------------------+--------------------------------------+-----------------+

Creating a 'Public Direct Connect' network

This type of network consists of a range of public IP addresses that are directly connected to the Internet. When you attach a VM to this type of network it must be configured with appropriate firewall software and be 'hardened' for Internet use.

This network type is intended for use with VMs running dedicated firewall or load balancer applications. A range of open source and enterprise applications are available in the Interoute Cloudstore.

The API call createPublicDirectConnect requires the following inputs:

  • zonename: the name of the zone where the network will be created

  • suffix: the CIDR suffix to specify the network size (29)

  • displaytext: description text for the network

The network 'name' is not user-defined and it will be set using the pattern: 'Network Public Direct Connect VDC_ACCOUNT_NAME NUM' (where NUM is a number that increments with each new network of the given type).

The available network size for creation through the API is currently restricted to '/29' only; that is, eight network addresses of which six are reserved for system use, so you get 2 usable IP addresses. If you require a larger network please submit a request ticket to Interoute support.

Here is an example API call using Cloudmonkey, with the output:

(local) > createPublicDirectConnect displaytext='test-publicDC-1' ↩
   zonename='Frankfurt (ESX)' suffix=29
count = 1
publicdirectconnect:
+-----------------+---------------+---------------------+-----------------+------------------+-----------------+
| routerendpoint1 |    gateway    |         sid         | routerendpoint2 |       cidr       |     zonename    |
+-------------- --+---------------+---------------------+-----------------+------------------+-----------------+
|  213.251.9.212  | 213.251.9.214 | INTJG/IPAC/va-B7k8W |  213.251.9.213  | 213.251.9.208/29 | Frankfurt (ESX) |
+-----------------+---------------+---------------------+-----------------+------------------+-----------------+

In this example, the allocated network is '213.251.9.208/29', that is the eight addresses from 213.251.9.208 to 213.251.9.215. However only two of these are available to the user. Here is what you will typically get:

213.251.9.208: network address
213.251.9.209: USER AVAILABLE
213.251.9.210: VDC virtual router
213.251.9.211: USER AVAILABLE
213.251.9.212: Interoute backbone router 1
213.251.9.213: Interoute backbone router 2
213.251.9.214: gateway address
213.251.9.215: broadcast address

A '/28' network would be allocated a range of 16 IP addresses. Six of those would be reserved, as above, thus providing 10 usable addresses.

Important

Public Direct Connect networks may take up to 24 hours to activate. The listNetworks command has an 'isprovisioned' response which shows if a network is active and available for use. Please contact Interoute support if you have any queries about the availability of a new network.

 

Creating a 'Direct Connect Group' and 'Private Direct Connect' networks

With Private Direct Connect networks you can create a set of private networks, that are inter-connected between VDC zones, and this will work for any number of VDC zones across the three global VDC regions.

Inter-zone connection is established by membership of a Direct Connect Group (DCG). Networks in the same group are inter-connected. You can remove a network from a group or re-attach the network to a different group; but these changes are not possible by user control, you need to raise a request ticket to Interoute support. There is no charge for the setting up of Direct Connect Groups, or for any data transfer on Interoute private networks. It is also possible to create inter-connections in the same DCG with Interoute VPN networks or third-party VPN networks.

Important

You may have a need to create multiple DCGs if you require isolation of network traffic for particular purposes (such as compliance regulations). However one DCG is sufficient for most users as it will support multiple sets of VMs communicating for different tasks, and your network traffic is isolated using strong MPLS IPVPN protocols. All network traffic between VDC zones flows entirely via Interoute's private optic fibre network.

 

To check if you have any existing DCG, use the listDirectConnectGroups command:

(local) > listDirectConnectGroups
count = 1
directconnectgroups:
+------+-------+---------+----------+
| sids |   id  |   name  | networks |
+------+-------+---------+----------+
|  []  | 33914 | Default |    []    |
+------+-------+---------+----------+

In this example, a DCG named 'Default' has already been created (sometimes, this will have been done by the VDC support team when your account was created). It does not currently contain any networks (the 'networks' response is an empty list).

To create a Direct Connect Group (DCG), use the API command createDirectConnectGroup, which requires one input:

  • name: the name to be associated with the DCG, this must be unique for a VDC account

Here is an example API call using Cloudmonkey, with the output:

(local) > createDirectConnectGroup name=test-DCG-1
count = 1
directconnectgroup:
+--------------------+-------+
|        name        |   id  |
+--------------------+-------+
|     test-DCG-1     | 35980 |
+--------------------+-------+

When a DCG exists for your VDC account, you can create a Private Direct Connect network in any zone using the API command createPrivateDirectConnect, which requires these inputs:

  • zonename: the name of the zone where the network will be created

  • cidr: the CIDR of the IP address range for the network (usually of size '/24')

  • gateway: the IP address of the network gateway

  • displaytext: description text for the network

And one of these inputs:

  • dcgid: the numerical ID of the DCG to be used

  • dcgname: the name of the DCG to be used

Note: the network 'name' is not user-defined and it will be set using the pattern: 'Network Private Direct Connect VDC_ACCOUNT_NAME NUM' (where NUM is a number that increments with each new network of the given type).

Here is an example API call using Cloudmonkey, with the output:

(local) > createPrivateDirectConnect zonename='Paris (ESX)' ↩
   cidr=10.0.101.0/24 gateway=10.0.101.254 ↩
   displaytext='test-privateDC-dcg35980-PARIS' dcgid=35980
{
  "count": 1,
  "privatedirectconnect": [
   {   
    "routerendpoint1": "10.0.101.1",
    "sid": "INT53/IPVPN/AnkKE3iO",
    "id": "11c70463-064f-4b27-97f7-1325f91ff1ec",
    "routerendpoint2": "10.0.101.2",
    "cidr": "10.0.101.0/24",
    "gateway": "10.0.101.254",
    "zonename": "Paris (ESX)"
   }
  ]

Note: it is conventional to use private IP addresses starting with '10.' for private networks, but you are not required to follow this.

The 'gateway' address can be chosen anywhere in the CIDR range, but '.254' or '.1' are conventional choices.

Important

Private Direct Connect networks and Direct Connect Groups may take up to 24 hours to activate. The listNetworks command has an 'isprovisioned' response which shows if a network is active and available for use. Please contact Interoute support if you have any queries about the availability of a new network or DCG.

 

Creating a 'Private Direct Connect' network with gateway services egress (outbound Internet)

To create this type of network requires an existing Direct Connect Group. You create a network in the same way as a standard Private Direct Connect network, but add the parameter 'gatewayServices' with value 'true':

(local) > createPrivateDirectConnect zonename='Paris (ESX)' ↩
   cidr=10.0.102.0/24 gateway=10.0.102.254 gatewayServices=true ↩
   displaytext='test-privateDC-with-egress' dcgid=35980

For this type of network, the 'gateway' address must be '.254' in the CIDR specified.

The network will have all of the functionality of 'Private Direct Connect', with the addition of outbound-only Internet connection. The Internet egress is not controllable with firewall egress rules, unlike the case of 'Local with Internet Gateway' networks.

The typical use case for this type of network is where you have virtual machines that require network interconnection across multiple VDC zones, and which also require continuous Internet egress for connection to software repositories, for example the Docker Hub for downloading container images.

Attaching a VM to a network

A VM is attached, or detached, from networks by the creation, or destruction, of a 'virtual NIC' (virtual network card).

You can do network attachment when a VM is deployed and started, using the deployVirtualMachine command, and you can modify network configuration at any later time, using the commands
addNicToVirtualMachine and
removeNicFromVirtualMachine.

If you definitely know the required network configuration for a VM it is usually preferable to set this up at deployment, as VDC can perform configuration tasks on a new VM. If you change the virtual NIC configuration later, there is no way for VDC to access into the VM operating system and you will need to login manually or use an OS-level configuration tool.

Attach a single network at deployment

When a VM is deployed, it must be attached to at least one network.

If there is only one network in a zone, deployVirtualMachine will use it and you do not need to specify the network.

If there is more than one network in a zone, you need to specify which network is to be used, using the 'networkids' parameter with the UUID of the network:

(local) > deploy virtualmachine …other parameters… networkids=UUID

With the above commands, VDC will select an (arbitrary) unused IP address for your VM. To specify an IP address, use the 'ipaddress' parameter, for example:

(local) > deploy virtualmachine …other parameters… ipaddress=192.168.101.25 ↩
   networkids=UUID

Change a single network for a running VM

To change the network to which a VM is attached, you should first attach it to the replacement network (with addNicToVirtualMachine), and then detach from the original network (with removeNicFromVirtualMachine).

You should always re-boot a Linux VM after a networks change. A Windows VM will usually detect changes and update itself.

VDC is not able to access your VM to modify its IP routing configuration. Therefore, depending on the network change, you may need to login to the VM and manually configure the IP routing.

Attaching a VM to multiple networks

A VM is attached, or detached, from networks by the creation, or destruction, of 'virtual NICs' (virtual network cards).

You can do network attachment when a VM is deployed and started, using different parameters of the deployVirtualMachine command.

If you definitely know the required network configuration for a VM it is usually preferable to set this up at deployment, as VDC can perform configuration tasks on a new VM. If you change the virtual NIC configuration later, there is no way for VDC to access into the VM operating system and you will need to login manually or use an OS-level configuration tool.

Attaching to multiple networks at deployment

When you want to attach two or more networks to a VM at deployment, use the 'networkids' parameter with the UUIDs of the networks inserted, separated by commas:

(local) > deploy virtualmachine …other parameters… networkids=UUID1,UUID2

The first network specified (above, the network with UUID1) will be used as the 'default' network for the IP routing configuration of the VM.

With the above command, VDC will select (arbitrary) unused IP addresses for your VM. To specify IP addresses on multiple networks, you have to use a different parameter, 'iptonetworklist', like this:

(local) > deploy virtualmachine …other parameters… iptonetworklist[0].ip=192.168.101.200  ↩
  iptonetworklist[0].networkid=UUID1 iptonetworklist[1].ip=10.0.104.10  ↩
  iptonetworklist[1].networkid=UUID2

Note that in this case you have to specify all the IP addresses for all of the networks, you can't tell VDC to automatically select some of the addresses.

Changing multiple networks for a running VM

You can detach a VM from a network using the removeNicFromVirtualMachine command. Note that a VM has to be attached to at least one network at all times. Attach the VM to new networks using the addNicToVirtualMachine command.

You should always re-boot a Linux VM after a networks change. A Windows VM may detect changes and update itself.

VDC is not able to access your VM to modify its IP routing configuration. Therefore, depending on the network changes, you may need to login to the VM and manually configure the IP routing.

Deleting networks

Local networks can be deleted using the API command deleteNetwork by specifying the network UUID.

This function is also available using the Control Centre by selecting the network details panel and clicking the Delete network button.

Direct Connect networks cannot be deleted by the user. You should submit a request ticket to Interoute support.