VDC API: How to manage your networks

Introduction
Prerequisites
Viewing network configurations
Types of networks in VDC
Modifying networks
Managing Direct Connect Groups
Deleting networks
Allocated and Implemented Local networks
Using IPSEC VPN tunneling

 

Introduction

This document describes how to use the API interface to manage networks.

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

Viewing network configurations

The API command listNetworks returns information about the networks in your VDC:

(local) > listNetworks

This will usually print out a lot of information, so use the 'filter' option of Cloudmonkey to reduce the quantity of information:

(local) > listNetworks filter=id,name,cidr,gateway,subtype,isprovisioned
count = 9
network:
+---------------+------------------+---------------+-------------------------------------------+--------------------+
|    gateway    |       cidr       | isprovisioned |                  name                     |      subtype       |
+---------------+------------------+---------------+-------------------------------------------+--------------------+
|192.168.31.254 | 192.168.31.0/24  |               | Local Internet Gateway Interoute Demo 1   |  internetgateway   |
| 10.0.115.254  |  10.0.115.0/24   |     True      | Private Direct Connect Interoute Demo     |privatedirectconnect|
| 10.0.111.254  |  10.0.111.0/24   |     True      | Private Direct Connect Interoute Demo 1   |privatedirectconnect|
|213.251.9.214  | 213.251.9.208/29 |     False     |  Public Direct Connect Interoute Demo 1   |publicdirectconnect |
|195.21.12.254  | 195.21.12.248/29 |     True      | Public Direct Connect Interoute Demo 1    |publicdirectconnect |
| 10.0.106.254  |  10.0.106.0/24   |     True      | Private Direct Connect Interoute Demo 4   |privatedirectconnect|
| 10.0.102.254  |  10.0.102.0/24   |     False     | Private Direct Connect Interoute Demo 2   |privatedirectconnect|
| 10.0.101.254  |  10.0.101.0/24   |     True      |Private Direct Connect Interoute Demo 5    |privatedirectconnect|
+---------------+------------------+---------------+-------------------------------------------+--------------------+

Cloudmonkey's 'filter' option selects from the full set of responses for an API command, using the response names listed in the API command reference.

The 'isprovisioned' response for Direct Connect-type networks which will be 'True' when a network has been created in VDC and the required network resources have been provisioned for it. There can be a delay of up to 24 hours for the provisioning to take place. For Local-type networks, 'isprovisioned' is not included in the API response. Please contact Interoute support if you have any queries about the availability of a new network or new Direct Connect Groups.

For Direct Connect Groups (DCGs), use the API command listDirectConnectGroups to return information:

(local) > listDirectConnectGroups
count = 1
directconnectgroups:
+------+------------------------------------------------+-------+--------------------+
| sids |                    networks                    |   id  |       name         |   
+------+------------------------------------------------+-------+--------------------+
|  []  | u'05d047a9-b2a5-4b99-8ca5-61a1879e22b9',       | 35980 |    test-DCG--1     |
|      |         u'1d6e12be-fbf4-46fb-8a0b-1dcac84d5d7e'|       |                    |
+------+------------------------------------------------+-------+--------------------+

The network UUIDs of the member networks (if there are any) for each DCG are listed. The 'sids' response shows a list of 'Interoute service IDs' for member networks that have a SID.

Types of networks in VDC

The VDC network types are known by various names, which are summarised in the following table. The column headings show the parameter/response names used in the VDC API (see listNetworks).





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.

Modifying networks

The modifyNetwork command can be used to modify network properties.

For Public Direct Connect networks, it is only possible to change the displaytext. This is also the case for the other network types when they are not empty (that is, at least one VM is present, whether running or stopped). For example:

(local) > modifyNetwork id=65c0651b-a715-440d-b2a7-ab88ff7d4ce6 displaytext='Public Direct Connect-Frankfurt-websites'
{
  "count": 1,
  "network": [
    {
      "displaytext": "Public Direct Connect-Frankfurt-websites",
      "id": "65c0651b-a715-440d-b2a7-ab88ff7d4ce6"
    }
  ]
}

For Local and Private Direct Connect networks which are empty it is possible to change the CIDR (IP range) and gateway IP address. This process actually involves creating a new network to replace the current one, and so the network UUID is changed to a new value.

For example (for a Local Private network):

(local) > modifyNetwork id=04af96e2-5f9f-40af-a431-5da8638bb043 cidr=192.168.222.0/24
count = 1
network:
+------------------+--------------------------------------+--------------------------------------+
|       cidr       |              originalid              |                  id                  |
+------------------+--------------------------------------+--------------------------------------+
| 192.168.222.0/24 | 04af96e2-5f9f-40af-a431-5da8638bb043 | a316279c-a548-419d-9183-881c7c11128b |
+------------------+--------------------------------------+--------------------------------------+

Important

If you modify the 'gateway' IP address of a Local Private network, it will be converted to a Local with Internet Gateway network.

 

Managing Direct Connect Groups

It is possible to change the name of a Direct Connect Group using the updateDirectConnectGroup command:

(local) > updateDirectConnectGroup name="test-DCG-Phillip-1" newname="DCG-Database-Apps"
{
  "count": 1,
  "directconnectgroup": [
    {
      "id": "35980",
      "name": "DCG-Database-Apps"
    }
  ]
}

For any other modification, such as:

  • deleting a DCG;

  • removing a Private Direct Connect network from a DCG;

  • moving a Private Direct Connect network from a DCG to another DCG;

  • making an Interoute VPN network a member of a DCG for Interoute VDC;

  • making a third party VPN network (for example, a private corporate network) a member of a DCG for Interoute VDC;

you should contact Interoute support.

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's 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.

Allocated and Implemented Local networks

Local networks can be in 'allocated' or 'implemented' states. You can think of these as 'hibernating' or 'active' states, respectively. VDC has an automatic function to optimise the use of network resources for all users by switching off any Local network which is empty of virtual machines.

When a new Local network is created, it will be in allocated state. When you add a VM to the network, it will become implemented, with a virtual router running, and a public IP address will be assigned for a Local with Internet Gateway network. This means that, at the moment you create a Local with Internet Gateway network, you will not be able to discover its public IP address, since it has not yet been assigned.

An implemented network will be automatically switched to allocated state if it is empty of virtual machines. However if it has one or more assigned public IP addresses these will remain assigned to that network.

A new VDC account is created with one 'default' Local with Internet Gateway network in every VDC zone. This makes it easier to deploy virtual machines, because a virtual machine cannot be deployed in a zone without a network being present. However keep in mind that there is a standard limit of 3 public IP addresses per VDC region, which means that you can operate a maximum of 3 implemented Local with Internet Gateway networks in each region. If you try to deploy a VM into a fourth zone, for example, this will fail with the error message that your public IP address limit is exceeded. To request a larger allowance of public IP addresses, you need to contact Interoute support.

Using IPSEC VPN tunneling

IPSEC is a type of VPN which allows remote client computers to connect via the Internet into a VDC network.

It is important to distinguish IPSEC VPN from the VPN-based network functions provided by Private Direct Connect networks and Direct Connect Groups, which create VPN connections between private networks.

IPSEC VPN is part of the functionality of a Local with Internet Gateway network.

When your computer is connected through an IPSEC VPN your computer is effectively a member of that VDC network, so you can, for example, use 'ssh' to login to any Linux VM on the network, or use Remote Desktop Connection (RDC) client software to connect to a Windows VM.