Update launch docs to include more details about networking setup.

docs/getting_started.rst

@@ -32,7 +32,7 @@ AWS:
     provider = CloudProviderFactory().create_provider(ProviderList.AWS, config)
     image_id = 'ami-d85e75b0'  # Ubuntu 14.04
 
-OpenStack:
+OpenStack (with Keystone authentication v2):
 
 .. code-block:: python
 
@@ -47,6 +47,22 @@ OpenStack:
                                                       config)
     image_id = 'c1f4b7bc-a563-4feb-b439-a2e071d861aa'  # Ubuntu 14.04 @ NeCTAR
 
+OpenStack (with Keystone authentication v3):
+
+.. code-block:: python
+
+    from cloudbridge.cloud.factory import CloudProviderFactory, ProviderList
+
+    config = {'os_username': 'username',
+              'os_password': 'password',
+              'os_auth_url': 'authentication URL',
+              'os_user_domain_name': 'domain name',
+              'os_project_domain_name': 'project domain name',
+              'os_project_name': 'project name'}
+    provider = CloudProviderFactory().create_provider(ProviderList.OPENSTACK,
+                                                      config)
+    image_id = '97755049-ee4f-4515-b92f-ca00991ee99a'  # Ubuntu 14.04 @ Jetstream
+
 List some resources
 -------------------
 Once you have a reference to a provider, explore the cloud platform:
@@ -87,8 +103,8 @@ Next, we need to create a security group and add a rule to allow ssh access.
 
 Launch an instance
 ------------------
-Before we can launch an instance, we need to decide what image to use so let's
-get a base Ubuntu image ``ami-d85e75b0`` and 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.
 
 .. code-block:: python
 

docs/topics/launch.rst

@@ -7,14 +7,14 @@ need a ``provider`` object (see `this page <setup.html>`_).
 
 Common launch data
 ------------------
-Before launching an instane, you need to decide on what image to launch
+Before launching an instance, you need to decide on what image to launch
 as well as what type of instance. We will create those objects here are use
 them in both options below. The specified image ID is a base Ubuntu image on
 AWS so feel free to change it as desired.
 
 .. code-block:: python
 
-    img = provider.compute.images.get('ami-d85e75b0')
+    img = provider.compute.images.get('ami-d85e75b0')  # Ubuntu 14.04 on AWS
     inst_type = provider.compute.instance_types.find(name='m1.small')[0]
 
 When launching an instance, you can also specify several optional arguments
@@ -29,24 +29,18 @@ guide).
     kp = provider.security.key_pairs.find(name='cloudbridge_intro')[0]
     sg = provider.security.security_groups.list()[0]
 
-Launch with classic networking
-------------------------------
-Launching an instance with the traditional networking model is straighforward,
-only needing to specify the basic parameters:
+Private networking setup
+------------------------
+Private networking gives you control over the networking setup for your
+instance(s) and is considered the preferred method for launching instances.
 
-.. code-block:: python
-
-    inst = provider.compute.instances.create(
-        name='CloudBridge-basic', image=img, instance_type=inst_type,
-        key_pair=kp, security_groups=[sg])
-
-Launch with private networking
-------------------------------
+Create a new private network
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 To start, we will create a private network and a corresponding subnet into
 which an instance will be launched. When creating the subnet, we need to
-set the address pool. For the AWS cloud, the subnet address pool needs to
-belong to the private network address space; for OpenStack, any address pool
-is acceptable. On AWS, we can obtain the private network address space via
+set the address pool. For OpenStack, any address pool is acceptable while for
+the AWS cloud, the subnet address pool needs to belong to the private network
+address space; we can obtain the private network address space via
 network object's ``cidr_block`` field (e.g., ``10.0.0.0/16``). Let's crate a
 subnet starting from the beginning of the block and allow up to 32 IP addresses
 into the subnet (``/27``):
@@ -57,7 +51,19 @@ into the subnet (``/27``):
     net.cidr_block  # '10.0.0.0/16'
     sn = net.create_subnet('10.0.0.1/27', "CloudBridge-subnet")
 
-Once we hace created a private network, we'll define a launch configuration
+Retrieve an existing private network
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you already have existing networks, we can simply reuse an existing one:
+
+.. code-block:: python
+
+    provider.network.list()  # Find a desired network ID
+    net = provider.network.get('network ID')
+    sn = net.subnets()[0]  # Get a handle on desired subnet
+
+Launch an instance
+------------------
+Once we have a handle on a private network, we'll define a launch configuration
 object to aggregate all the launch configuration options. The launch config
 can contain other launch options, such as the block storage mappings (see
 below). Finally, we can launch the instance:
@@ -70,9 +76,34 @@ below). Finally, we can launch the instance:
         name='CloudBridge-VPC', image=img,  instance_type=inst_type,
         launch_config=lc, key_pair=kp, security_groups=[sg])
 
+.. warning::
+
+    There is still a problem with network abstractions in CloudBridge between
+    AWS and OpenStack providers. AWS takes a subnet ID for it's launch config
+    while OpenStack takes a network ID. For the time being, the user needs to
+    make this distinction in their code and supply the correct value.
+    For example, for OpenStack, above code needs to look like the following:
+    ``lc.add_network_interface(net.id)``.
+
+Launch with default networking
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Launching an instance with the default networking model is straightforward,
+only needing to specify the basic parameters. This will only work for the case
+a default network exists for your account, which is provider-dependent and may
+not necessarily exist.
+
+For the case of AWS, an instance will be launched into the VPC where the
+specified security group belongs to. If no security group is specified, the
+instance will get launched into the *default* VPC, assuming such VPC exists.
+
+.. code-block:: python
+
+    inst = provider.compute.instances.create(
+        name='CloudBridge-basic', image=img, instance_type=inst_type,
+        key_pair=kp, security_groups=[sg])
 
 Block device mapping
---------------------
+~~~~~~~~~~~~~~~~~~~~
 Optionally, you may want to provide a block device mapping at launch,
 specifying volume or ephemeral storage mappings for the instance. While volumes
 can also be attached and mapped after instance boot using the volume service,
@@ -90,8 +121,10 @@ refer to :class:`.LaunchConfig`.
         name='CloudBridge-BDM', image=img,  instance_type=inst_type,
         launch_config=lc, key_pair=kp, security_groups=[sg])
 
-where img is the :class:`.Image` object to use for the root volume.
+where ``img`` is the :class:`.Image` object to use for the root volume.
 
+After launch
+------------
 After an instance has launched, you can access its properties:
 
 .. code-block:: python
@@ -102,3 +135,13 @@ After an instance has launched, you can access its properties:
     # 'running'
     inst.public_ips
     # [u'54.166.125.219']
+
+Depending on the provider's networking setup, it may be necessary to explicitly
+assign a floating IP address to your instance. This can be done as follows:
+
+.. code-block:: python
+
+    # List all the IP addresses and find the desired one
+    provider.network.floating_ips()
+    # Assign the IP to the instance
+    inst.add_floating_ip('149.165.168.143')