Update the Getting Started tutorial with instructions for using private networking.

Note that there is still a problem here with OpenStack: OS requires a router to be attached to an external network (i.e., a gateway) vs. a user-created network. We do not have a way to filter for an external network since this is only an OS concept. So the example provided will require an extra step of listing all the available networks, picking out the public/external one and attaching the router to it. This also happens to be a problem for writing tests, hence those are still missing.

docs/getting_started.rst

@@ -30,7 +30,7 @@ AWS:
     config = {'aws_access_key': 'AKIAJW2XCYO4AF55XFEQ',
               'aws_secret_key': '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'}
     provider = CloudProviderFactory().create_provider(ProviderList.AWS, config)
-    image_id = 'ami-d85e75b0'  # Ubuntu 14.04
+    image_id = 'ami-2d39803a'  # Ubuntu 14.04 (HVM)
 
 OpenStack (with Keystone authentication v2):
 
@@ -91,6 +91,23 @@ on disk as a read-only file.
     import os
     os.chmod('cloudbridge_intro.pem', 0400)
 
+Configure a private network
+---------------------------
+We want to provision our instance into a private network to give us flexibility
+in the future. Also, providers these days are increasingly requiring use of
+private networks. Setting up a private network requires several steps:
+(1) create a network; (2) create a subnet within the network; (3) create a
+router; (4) attach the router to an external network; and (5) add a route to
+the router that links with with a subnet.
+
+.. code-block:: python
+
+    net = provider.network.create('cloudbridge_intro')
+    sn = net.create_subnet('10.0.0.1/28', 'cloudbridge-intro')
+    router = provider.network.create_router('cloudbridge-intro')
+    router.attach_network(net.id)
+    router.add_route(sn.id)
+
 Create a security group
 -----------------------
 Next, we need to create a security group and add a rule to allow ssh access.
@@ -98,13 +115,14 @@ Next, we need to create a security group and add a rule to allow ssh access.
 .. code-block:: python
 
     sg = provider.security.security_groups.create(
-        'cloudbridge_intro', 'A security group used by CloudBridge')
+        'cloudbridge_intro', 'A security group used by CloudBridge', net.id)
     sg.add_rule('tcp', 22, 22, '0.0.0.0/0')
 
 Launch an instance
 ------------------
 We can now launch an instance using the created key pair and security group.
-We will launch an instance type that has at least 2 CPUs and 4GB RAM.
+We will launch an instance type that has at least 2 CPUs and 4GB RAM. We will
+also add the network interface as a launch argument.
 
 .. code-block:: python
 
@@ -112,14 +130,26 @@ We will launch an instance type that has at least 2 CPUs and 4GB RAM.
     inst_type = sorted([t for t in provider.compute.instance_types.list()
                         if t.vcpus >= 2 and t.ram >= 4],
                        key=lambda x: x.vcpus*x.ram)[0]
+    lc = provider.compute.instances.create_launch_config()
+    lc.add_network_interface(net.id)
     inst = provider.compute.instances.create(
         name='CloudBridge-intro', image=img, instance_type=inst_type,
-        key_pair=kp, security_groups=[sg])
+        key_pair=kp, security_groups=[sg], launch_config=lc)
     # Wait until ready
-    inst.wait_till_ready()
+    inst.wait_till_ready()  # This is a blocking call
     # Show instance state
     inst.state
     # 'running'
+
+Assign a public IP address
+--------------------------
+To access the instance, let's assign a public IP address to the instance. For
+this step, we'll first need to allocate a floating IP address for our account
+and then associate it with the instance.
+
+    fip = provider.network.create_floating_ip()
+    inst.add_floating_ip(fip.public_ip)
+    inst.refresh()
     inst.public_ips
     # [u'54.166.125.219']
 
@@ -133,8 +163,18 @@ To wrap things up, let's clean up all the resources we have created
 .. code-block:: python
 
     inst.terminate()
+    from cloudbridge.cloud.interfaces import InstanceState
+    inst.wait_for([InstanceState.TERMINATED, InstanceState.UNKNOWN],
+                   terminal_states=[InstanceState.ERROR])  # Blocking call
+    fip.delete()
     sg.delete()
     kp.delete()
+    os.remove('cloudbridge_intro.pem')
+    router.remove_route(sn.id)
+    router.detach_network()
+    router.delete()
+    sn.delete()
+    net.delete()
 
 And that's it - a full circle in a few lines of code. You can now try
 the same with a different provider. All you will need to change is the