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
This commit is contained in:
Richard Theis 2015-11-25 11:55:42 -06:00
parent 0d9fcb7b78
commit f15dabeac8
5 changed files with 190 additions and 106 deletions

View File

@ -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

View File

@ -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.
To run:
python examples/network/create.py
For a full guide see TODO(etoews):link to docs on developer.openstack.org
"""
import sys
from examples import common
from examples import connection
def create_network(conn):
print("Create Network:")
example_network = conn.network.create_network(
name='openstacksdk-example-project-network')
def create(conn, name, opts, ports_to_open=[80, 22]):
dns_nameservers = opts.data.pop('dns_nameservers', '206.164.176.34')
cidr = opts.data.pop('cidr', '10.3.3.0/24')
print(example_network)
network = conn.network.find_network(name)
if network is None:
network = conn.network.create_network(name=name)
print(str(network))
example_subnet = conn.network.create_subnet(
name='openstacksdk-example-project-subnet',
network_id=example_network.id,
ip_version='4',
cidr='10.0.2.0/24',
gateway_ip='10.0.2.1')
subnet = conn.network.find_subnet(name)
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))
print(example_subnet)

View File

@ -11,56 +11,18 @@
# under the License.
"""
Network examples
Delete resources with the Network service.
Destroy all the pieces parts of a working network.
To run:
python examples/network/delete.py
For a full guide see TODO(etoews):link to docs on developer.openstack.org
"""
import sys
from examples import common
from examples import connection
def delete_network(conn):
print("Delete Network:")
example_network = conn.network.find_network(
'openstacksdk-example-project-network')
def delete(conn, name):
router = conn.network.find_router(name)
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))
for example_subnet in example_network.subnets:
conn.network.delete_subnet(example_subnet, ignore_missing=False)
conn.network.delete_network(example_network, ignore_missing=False)

View File

@ -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)

View File

@ -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)