Updated networking documentation

cloudbridge/cloud/providers/openstack/services.py

@@ -835,9 +835,8 @@ class OpenStackSubnetService(BaseSubnetService):
             # No default; create one
             net = self.provider.networking.networks.create(
                 OpenStackNetwork.CB_DEFAULT_NETWORK_NAME)
-            sn = self.provider.networking.subnets.create(
-                name=OpenStackSubnet.CB_DEFAULT_SUBNET_NAME,
-                network=net, cidr_block='10.0.0.0/24')
+            sn = net.create_subnet(name=OpenStackSubnet.CB_DEFAULT_SUBNET_NAME,
+                                   cidr_block='10.0.0.0/24')
             router = self.provider.networking.routers.create(
                 OpenStackRouter.CB_DEFAULT_ROUTER_NAME)
             router.attach_subnet(sn)

docs/topics/networking.rst

@@ -3,6 +3,7 @@ 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.
+All CloudBridge deployed VMs must be deployed into a particular subnet.
 
 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
@@ -11,38 +12,96 @@ 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
-----------------------------
+Once a VM is deployed, cloudbridge's networking capabilities must address
+several common scenarios.
+
+1. Allowing internet access from a launched VM
+
+   In the simplest scenario, a user may simply want to launch an instance and
+   allow the instance to access the internet.
+
+2. Allowing internet access to a launched VM
+
+   Alternatively, the user may want to allow the instance to be contactable
+   from the internet. In a more complex scenario, a user may want to deploy
+   VMS into several subnets, and deploy a gateway, jump host or bastion host
+   to access other VMs which are not directly connected to the internet. In
+   the latter scenario, the gateway/jump host/bastion host will need to be
+   contactable over the internet.
+
+3. Secure access between subnets for n-tier applications
+
+   In this third scenario, a multi-tier app may be deployed into several
+   subnets depending on their tier. For example, consider the following
+   scenario:
+
+   - Tier 1/Subnet 1 - Web Server Needs to be externally accessible over the
+     internet. However, in this particular scenario, the web server itself does
+     not need access to the internet.
+
+   - Tier 2/Subnet 2 - Application Server The Application server must only be
+     able to communicate with the database server in Subnet 3, and receive
+     communication from the Web Server in Subnet 1. However, we assume a
+     special case here where the application server needs to access the
+     internet.
+
+   - Tier 3/Subnet 3 - Database Server The database server must only be able to
+     receive incoming traffic from Tier 2, but must not be able to make
+     outgoing traffic outside of its subnet.
+
+    At present, CloudBridge does not provide support for this scenario,
+    primarily because OpenStack's FwaaS (Firewall-as-a-Service) is not widely
+    available.
+
+1. Allowing internet access from a launched VM
+----------------------------------------------
 Creating a private network is a simple, one-line command but appropriately
-connecting it so it has Internet access is a multi-step process:
+connecting it so that it has uniform Internet access across all providers
+is a multi-step process:
 (1) create a network; (2) create a subnet within this network; (3) create a
-router; (4) attach the router to an external network; and (5) add a route to
-the router that links 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.
+router; (4) attach the router to the subnet and (5) attach the router to the
+internet gateway.
+
+When creating a network, we need to set an address pool. Any subsequent
+subnets you create must have a CIDR block that falls within the parent
+network's CIDR block. Below, we'll create a subnet starting from the beginning
+of the block and allow up to 16 IP addresses within a subnet (``/28``).
+
+.. code-block:: python
+
+    net = self.provider.networking.networks.create(
+        name='my-network', cidr_block='10.0.0.0/16')
+    sn = net.create_subnet(name='my-subnet', cidr_block='10.0.0.0/28', zone=zone)
+    router = self.provider.networking.routers.create(network=net, name='my-router')
+    router.attach_subnet(sn)
+    gateway = self.provider.networking.gateways.get_or_create_inet_gateway(name)
+    router.attach_gateway(gateway)
 
-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``).
+
+2. Allowing internet access to a launched VM
+----------------------------------------------
+The additional step that's require here is to assign a floating ip to the VM.
 
 .. code-block:: python
 
-    net = provider.networking.networks.create('cloudbridge_intro')
-    sn = net.create_subnet('10.0.0.0/28', 'cloudbridge-intro')
-    router = provider.networking.networks.create_router('cloudbridge-intro')
-    if not net.external:
-        for n in self.provider.networking.networks.list():
-            if n.external:
-                net = n
-                break
-    router.attach_network(net.id)
-    router.add_route(sn.id)
+    net = provider.networking.networks.create(
+        name='my-network', cidr_block='10.0.0.0/16')
+    sn = net.create_subnet(name='my-subnet', cidr_block='10.0.0.0/28', zone=zone)
+
+    vm = provider.compute.instances.create('my-inst', subnet=sn, ...)
+
+    router = provider.networking.routers.create(network=net, name='my-router')
+    router.attach_subnet(sn)
+    gateway = provider.networking.gateways.get_or_create_inet_gateway(name)
+    router.attach_gateway(gateway)
+
+    fip = provider.networking.networks.create_floating_ip()
+    vm.add_floating_ip(fip)
+
 
 Retrieve an existing private network
 ------------------------------------
-If you already have existing networks, we can query for those:
+If you already have existing networks, we can query for it:
 
 .. code-block:: python