Add network user guide

Add a network user guide to replace the current placeholder.  Also,
add to and update the network examples to go along with the guide.
And finally, add a test for the network examples.

Change-Id: Ib98a7632c3ccc9764a93831f0dbe597ce0bce606
Closes-Bug: #1466186

doc/source/users/guides/network.rst

@@ -5,4 +5,99 @@ Before working with the Network service, you'll need to create a connection
 to your OpenStack cloud by following the :doc:`connect` user guide. This will
 provide you with the ``conn`` variable used in the examples below.
 
-.. TODO(thowe): Implement this guide
+.. contents:: Table of Contents
+   :local:
+
+The primary resource of the Network service is the network.
+
+List Networks
+-------------
+
+A **network** is an isolated `Layer 2 <https://en.wikipedia.org/wiki/Data_link_layer>`_
+networking segment. There are two types of networks, project and provider networks.
+Project networks are fully isolated and are not shared with other projects. Provider
+networks map to existing physical networks in the data center and provide external
+network access for servers. Only an OpenStack administrator can create provider
+networks. Networks can be connected via routers.
+
+.. literalinclude:: ../examples/network/list.py
+   :pyobject: list_networks
+
+Full example: `network resource list`_
+
+List Subnets
+------------
+
+A **subnet** is a block of IP addresses and associated configuration state.
+Subnets are used to allocate IP addresses when new ports are created on a
+network.
+
+.. literalinclude:: ../examples/network/list.py
+   :pyobject: list_subnets
+
+Full example: `network resource list`_
+
+List Ports
+----------
+
+A **port** is a connection point for attaching a single device, such as the
+`NIC <https://en.wikipedia.org/wiki/Network_interface_controller>`_
+of a server, to a network. The port also describes the associated network
+configuration, such as the `MAC <https://en.wikipedia.org/wiki/Media_access_control>`_
+and IP addresses to be used on that port.
+
+.. literalinclude:: ../examples/network/list.py
+   :pyobject: list_ports
+
+Full example: `network resource list`_
+
+List Security Groups
+--------------------
+
+A **security group** acts as a virtual firewall for servers. It is a container
+for security group rules which specify the type of network traffic and direction
+that is allowed to pass through a port.
+
+.. literalinclude:: ../examples/network/list.py
+   :pyobject: list_security_groups
+
+Full example: `network resource list`_
+
+List Routers
+------------
+
+A **router** is a logical component that forwards data packets between networks.
+It also provides `Layer 3 <https://en.wikipedia.org/wiki/Network_layer>`_ and
+`NAT <https://en.wikipedia.org/wiki/Network_address_translation>`_ forwarding to
+provide external network access for servers on project networks.
+
+.. literalinclude:: ../examples/network/list.py
+   :pyobject: list_routers
+
+Full example: `network resource list`_
+
+Create Network
+--------------
+
+Create a project network and subnet. This network can be used when creating
+a server and allows the server to communicate with others servers on the
+same project network.
+
+.. literalinclude:: ../examples/network/create.py
+   :pyobject: create_network
+
+Full example: `network resource create`_
+
+Delete Network
+--------------
+
+Delete a project network and its subnets.
+
+.. literalinclude:: ../examples/network/delete.py
+   :pyobject: delete_network
+
+Full example: `network resource delete`_
+
+.. _network resource create: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/network/create.py
+.. _network resource delete: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/network/delete.py
+.. _network resource list: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/network/list.py

examples/network/create.py

@@ -11,69 +11,25 @@
 # under the License.
 
 """
-Network examples
+Create resources with the Network service.
 
-Create all the pieces parts to have a working network.
+For a full guide see TODO(etoews):link to docs on developer.openstack.org
-
-To run:
-    python examples/network/create.py
 """
 
-import sys
 
-from examples import common
+def create_network(conn):
-from examples import connection
+    print("Create Network:")
 
+    example_network = conn.network.create_network(
+        name='openstacksdk-example-project-network')
 
-def create(conn, name, opts, ports_to_open=[80, 22]):
+    print(example_network)
-    dns_nameservers = opts.data.pop('dns_nameservers', '206.164.176.34')
-    cidr = opts.data.pop('cidr', '10.3.3.0/24')
 
-    network = conn.network.find_network(name)
+    example_subnet = conn.network.create_subnet(
-    if network is None:
+        name='openstacksdk-example-project-subnet',
-        network = conn.network.create_network(name=name)
+        network_id=example_network.id,
-    print(str(network))
+        ip_version='4',
+        cidr='10.0.2.0/24',
+        gateway_ip='10.0.2.1')
 
-    subnet = conn.network.find_subnet(name)
+    print(example_subnet)
-    if subnet is None:
-        args = {
-            "name": name,
-            "network_id": network.id,
-            "ip_version": "4",
-            "dns_nameservers": [dns_nameservers],
-            "cidr": cidr,
-        }
-        subnet = conn.network.create_subnet(**args)
-    print(str(subnet))
-
-    extnet = conn.network.find_network("Ext-Net")
-    router = conn.network.find_router(name)
-    if router is None:
-        args = {
-            "name": name,
-            "external_gateway_info": {"network_id": extnet.id}
-        }
-        router = conn.network.create_router(**args)
-        conn.network.router_add_interface(router, subnet.id)
-    print(str(router))
-
-    sg = conn.network.find_security_group(name)
-    if sg is None:
-        sg = conn.network.create_security_group(name=name)
-        for port in ports_to_open:
-            conn.network.security_group_open_port(sg.id, port)
-        conn.network.security_group_allow_ping(sg.id)
-    print(str(sg))
-
-    return network
-
-
-def run_network(opts):
-    name = opts.data.pop('name', 'netty')
-    conn = connection.make_connection(opts)
-    return(create(conn, name, opts))
-
-
-if __name__ == "__main__":
-    opts = common.setup()
-    sys.exit(common.main(opts, run_network))

examples/network/delete.py

@@ -11,56 +11,18 @@
 # under the License.
 
 """
-Network examples
+Delete resources with the Network service.
 
-Destroy all the pieces parts of a working network.
+For a full guide see TODO(etoews):link to docs on developer.openstack.org
-
-To run:
-    python examples/network/delete.py
 """
 
-import sys
 
-from examples import common
+def delete_network(conn):
-from examples import connection
+    print("Delete Network:")
 
+    example_network = conn.network.find_network(
+        'openstacksdk-example-project-network')
 
-def delete(conn, name):
+    for example_subnet in example_network.subnets:
-
+        conn.network.delete_subnet(example_subnet, ignore_missing=False)
-    router = conn.network.find_router(name)
+    conn.network.delete_network(example_network, ignore_missing=False)
-    if router is not None:
-        print(str(router))
-
-    subnet = conn.network.find_subnet(name)
-    if subnet is not None:
-        print(str(subnet))
-        if router:
-            try:
-                conn.network.router_remove_interface(router, subnet.id)
-            except Exception:
-                pass
-        for port in conn.network.get_subnet_ports(subnet.id):
-            print(str(port))
-            conn.network.delete_port(port)
-
-    if router is not None:
-        conn.network.delete_router(router)
-
-    if subnet:
-        conn.network.delete_subnet(subnet)
-
-    network = conn.network.find_network(name)
-    if network is not None:
-        print(str(network))
-        conn.network.delete_network(network)
-
-
-def run_network(opts):
-    name = opts.data.pop('name', 'netty')
-    conn = connection.make_connection(opts)
-    return(delete(conn, name))
-
-
-if __name__ == "__main__":
-    opts = common.setup()
-    sys.exit(common.main(opts, run_network))

examples/network/list.py

@@ -22,3 +22,31 @@ def list_networks(conn):
 
     for network in conn.network.networks():
         print(network)
+
+
+def list_subnets(conn):
+    print("List Subnets:")
+
+    for subnet in conn.network.subnets():
+        print(subnet)
+
+
+def list_ports(conn):
+    print("List Ports:")
+
+    for port in conn.network.ports():
+        print(port)
+
+
+def list_security_groups(conn):
+    print("List Security Groups:")
+
+    for port in conn.network.security_groups():
+        print(port)
+
+
+def list_routers(conn):
+    print("List Routers:")
+
+    for router in conn.network.routers():
+        print(router)

openstack/tests/examples/test_network.py

@@ -0,0 +1,43 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+import unittest
+
+from examples import connect
+from examples.network import create as network_create
+from examples.network import delete as network_delete
+from examples.network import find as network_find
+from examples.network import list as network_list
+
+
+class TestNetwork(unittest.TestCase):
+    """Test the network examples
+
+    The purpose of these tests is to ensure the examples run without erring
+    out.
+    """
+
+    @classmethod
+    def setUpClass(cls):
+        cls.conn = connect.create_connection_from_config()
+
+    def test_network(self):
+        network_list.list_networks(self.conn)
+        network_list.list_subnets(self.conn)
+        network_list.list_ports(self.conn)
+        network_list.list_security_groups(self.conn)
+        network_list.list_routers(self.conn)
+
+        network_find.find_network(self.conn)
+
+        network_create.create_network(self.conn)
+        network_delete.delete_network(self.conn)