diff --git a/doc/source/users/guides/network.rst b/doc/source/users/guides/network.rst index 0ec9e2c2a..6cc56c37e 100644 --- a/doc/source/users/guides/network.rst +++ b/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 `_ +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 `_ +of a server, to a network. The port also describes the associated network +configuration, such as the `MAC `_ +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 `_ and +`NAT `_ 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 \ No newline at end of file diff --git a/examples/network/create.py b/examples/network/create.py index e948ccc8a..f89387b8d 100644 --- a/examples/network/create.py +++ b/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. - -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) diff --git a/examples/network/delete.py b/examples/network/delete.py index e6ecdaa23..eedd0b61c 100644 --- a/examples/network/delete.py +++ b/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. - -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) diff --git a/examples/network/list.py b/examples/network/list.py index d32e6df9e..9ab952984 100644 --- a/examples/network/list.py +++ b/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) diff --git a/openstack/tests/examples/test_network.py b/openstack/tests/examples/test_network.py new file mode 100644 index 000000000..0e09f39b7 --- /dev/null +++ b/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)