Update docs for the new Instance.create method's network parameter

docs/getting_started.rst

@@ -40,9 +40,9 @@ OpenStack (with Keystone authentication v2):
 
     config = {'os_username': 'username',
               'os_password': 'password',
-              'os_tenant_name': 'tenant name',
               'os_auth_url': 'authentication URL',
-              'os_region_name': 'region name'}
+              'os_region_name': 'region name',
+              'os_project_name': 'project name'}
     provider = CloudProviderFactory().create_provider(ProviderList.OPENSTACK,
                                                       config)
     image_id = 'c1f4b7bc-a563-4feb-b439-a2e071d861aa'  # Ubuntu 14.04 @ NeCTAR
@@ -56,9 +56,9 @@ OpenStack (with Keystone authentication v3):
     config = {'os_username': 'username',
               'os_password': 'password',
               'os_auth_url': 'authentication URL',
-              'os_user_domain_name': 'domain name',
+              'os_project_name': 'project name',
               'os_project_domain_name': 'project domain name',
-              'os_project_name': 'project name'}
+              'os_user_domain_name': 'domain name'}
     provider = CloudProviderFactory().create_provider(ProviderList.OPENSTACK,
                                                       config)
     image_id = '97755049-ee4f-4515-b92f-ca00991ee99a'  # Ubuntu 14.04 @ Jetstream
@@ -91,23 +91,6 @@ 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.
@@ -130,11 +113,9 @@ also add the network interface as a launch argument.
     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], launch_config=lc)
+        key_pair=kp, security_groups=[sg])
     # Wait until ready
     inst.wait_till_ready()  # This is a blocking call
     # Show instance state
@@ -147,6 +128,8 @@ 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.
 
+.. code-block:: python
+
     fip = provider.network.create_floating_ip()
     inst.add_floating_ip(fip.public_ip)
     inst.refresh()

docs/topics/launch.rst

@@ -1,110 +1,63 @@
 Launching instances
 ===================
-Depending on the cloud provider, instances can be launched using
-software-managed networking (e.g., VPC on AWS, Neutron on OpenStack) or the
-classic networking approach. Before being able to run below command, you will
-need a ``provider`` object (see `this page <setup.html>`_).
+Before being able to run below commands, you will need a ``provider`` object
+(see `this page <setup.html>`_).
 
 Common launch data
 ------------------
-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.
+Before launching an instance, you need to decide what image to launch
+as well as what type of instance. We will create those objects here. The
+specified image ID is a base Ubuntu image on AWS so feel free to change it as
+desired. For instance type, we're going to let CloudBridge figure out what's
+the appropriate name on a given provider for an instance with at least 2 CPUs
+and 4 GB RAM.
 
 .. code-block:: python
 
-    img = provider.compute.images.get('ami-d85e75b0')  # Ubuntu 14.04 on AWS
-    inst_type = provider.compute.instance_types.find(name='m1.small')[0]
+    img = provider.compute.images.get('ami-5ac2cd4d')  # Ubuntu 14.04 on AWS
+    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]
 
 When launching an instance, you can also specify several optional arguments
 such as the security group, a key pair, or instance user data. To allow you to
 connect to the launched instances, we will also supply those parameters (note
 that we're making an assumption here these resources exist; if you don't have
-those resources, take a look at the `Getting Started <../getting_started.html>`_
-guide).
+those resources under your account, take a look at the
+`Getting Started <../getting_started.html>`_ guide).
 
 .. code-block:: python
 
     kp = provider.security.key_pairs.find(name='cloudbridge_intro')[0]
     sg = provider.security.security_groups.list()[0]
 
-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.
-
-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 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``):
-
-.. code-block:: python
-
-    net = provider.network.create(name="CloudBridge-net")
-    net.cidr_block  # '10.0.0.0/16'
-    sn = net.create_subnet('10.0.0.1/27', "CloudBridge-subnet")
-
-Note that it may be necessary to also create a route for this new network. If
-that's the case, take a look at the
-`Getting Started <../getting_started.html>`_ document for an example.
-
-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('desired network ID')
-    sn = net.subnets()[0]  # Get a handle on a 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:
+Once we have all the desired pieces, we'll use them to launch an instance:
 
 .. code-block:: python
 
-    lc = provider.compute.instances.create_launch_config()
-    lc.add_network_interface(net.id)
     inst = provider.compute.instances.create(
-        name='CloudBridge-VPC', image=img,  instance_type=inst_type,
-        launch_config=lc, key_pair=kp, security_groups=[sg])
-
-.. warning::
-
-    CloudBridge version 0.1.0 does not uniformly deal with network abstractions
-    for AWS and OpenStack providers. AWS takes a subnet ID for it's launch
-    config while OpenStack takes a network ID. As a result, the user needs to
-    make this distinction in their code and supply the correct value. For
-    example, for AWS, above code needs to look like the following:
-    ``lc.add_network_interface(sn.id)``. This has been corrected in newer code.
-
-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.
+        name='CloudBridge-VPC', image=img, instance_type=inst_type,
+        key_pair=kp, security_groups=[sg])
 
-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.
+Private networking
+~~~~~~~~~~~~~~~~~~
+Private networking gives you control over the networking setup for your
+instance(s) and is considered the preferred method for launching instances. To
+launch an instance with an explicit private network, just supply it as an
+additional argument to the ``create`` method:
 
 .. code-block:: python
 
+    provider.network.list()  # Find a desired network ID
+    net = provider.network.get('desired network ID')
     inst = provider.compute.instances.create(
-        name='CloudBridge-basic', image=img, instance_type=inst_type,
-        key_pair=kp, security_groups=[sg])
+        name='CloudBridge-VPC', image=img, instance_type=inst_type,
+        network=net, key_pair=kp, security_groups=[sg])
+
+For more information on how to create and setup a private network, take a look
+at `Networking <./networking.html>`_.
 
 Block device mapping
 ~~~~~~~~~~~~~~~~~~~~

docs/topics/networking.rst

@@ -0,0 +1,50 @@
+Private networking
+==================
+Private networking gives you control over the networking setup for your
+instance(s) and is considered the preferred method for launching instances.
+Also, providers these days are increasingly requiring use of private networks.
+
+If you do not explicitly specify a private network to use when launching an
+instance, CloudBridge will attempt to use a default one. A 'default' network is
+one tagged as such by the native API. If such tag or functionality does not
+exist, CloudBridge will look for one with a predefined name (by default, called
+'CloudBridgeNet', which can be overridden with environment variable
+``CB_DEFAULT_NETWORK_NAME``).
+
+Create a new private network
+----------------------------
+Creating a private network is a simple, one-line command but appropriately
+connecting it so it has Internet access is a multi-step process:
+(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. For some providers, any network can
+be external (ie, connected to the Internet) while for others it's a specific,
+pre-defined one that exists in the an account by default. In order to properly
+connect the router, we need to ensure we're using an external network.
+
+When creating the subnet, we need to set an address pool. We can obtain the
+private network address space via network object's ``cidr_block`` field (e.g.,
+``10.0.0.0/16``). Below, we'll create a subnet starting from the beginning of
+the block and allow up to 16 IP addresses into the subnet (``/28``).
+
+.. code-block:: python
+
+    net = provider.network.create('cloudbridge_intro')
+    sn = net.create_subnet('10.0.0.0/28', 'cloudbridge-intro')
+    router = provider.network.create_router('cloudbridge-intro')
+    if not net.external:
+        for n in self.provider.network.list():
+            if n.external:
+                external_net = n
+                break
+    router.attach_network(external_net.id)
+    router.add_route(sn.id)
+
+Retrieve an existing private network
+------------------------------------
+If you already have existing networks, we can query for those:
+
+.. code-block:: python
+
+    provider.network.list()  # Find a desired network ID
+    net = provider.network.get('desired network ID')