Browse Source

Updating naming conventions and documenting a Python API

- renamed the class that calls ansible_runner to NetworkingAnsible
- added documentation

Change-Id: Ia1819d54469acdcb66bf2e40f6cb750574a4ea30
Dan Radez 7 months ago
parent
commit
095c86e015

+ 20
- 10
README.rst View File

@@ -4,12 +4,12 @@ Networking-Ansible ML2 Driver
4 4
 
5 5
 Overview
6 6
 --------
7
-Networking-Ansible is a Neutron ML2 driver that abstracts the management and
8
-interaction with switching hardware to Ansible Networking. This driver is not
7
+Networking-Ansible is a python library that abstracts management and
8
+interaction with switching hardware to Ansible Networking. This library is not
9 9
 tested with all the modules included with Ansible Networking. In theory it
10 10
 should work with any switch that has compatible modules included with Ansible
11
-Networking if the provider tasks are added to the Ansible openstack-ml2 role
12
-included with this driver. See the contributor documentation for more information
11
+Networking if the provider tasks are added to this library's Ansible role.
12
+See the contributor documentation for more information
13 13
 about adding support for an Ansible Networking driver to the openstack-ml2
14 14
 Ansible role.
15 15
 
@@ -20,21 +20,31 @@ Ansible role.
20 20
 
21 21
 Components
22 22
 ----------
23
-The Networking-Ansible ML2 Driver consists of the following components:
23
+The Networking-Ansible library consists of the following components:
24 24
 
25
-``networking_ansible`` ML2 Driver
26
-  Invoked by neutron to configure L2 networking for tenant networks.
25
+``ML2 Mechanism Driver``
26
+  Invoked by neutron to configure L2 networking for OpenStack tenant networks.
27
+
28
+``Python API``
29
+  Imported directly by python.
27 30
 
28 31
 Use Cases
29 32
 ---------
30
-``Ironic Baremetal Guest Deployment``
33
+``OpenStack Ironic Baremetal Guest Deployment``
31 34
 
32 35
 Ironic uses Networking-Ansible to configure the switch ports for the baremetal guests.
33 36
 Ironic needs to swap the port a baremetal guest is connected to between the
34 37
 Ironic provisioning network and the tenant VLAN that the guest is assigned.
35 38
 
39
+``Python API``
40
+
41
+Any python application could need the ability to communicate with a switch
42
+to perform a task that networking-ansible is able to complete. The interaction
43
+with ansible is designed in a library style that will allow direct import and
44
+invocation in python independant of a running OpenStack deployment.
45
+
36 46
 Features
37 47
 --------
38 48
 
39
-* On create network a vlan can be defined
40
-* On port update will assign a vlan to an access port
49
+* Create and delete VLANs
50
+* Configure a port in access mode and assign a it to a VLAN

+ 0
- 1
doc/source/contributor/index.rst View File

@@ -7,4 +7,3 @@
7 7
 
8 8
    contributing
9 9
    provider
10
-

+ 2
- 2
doc/source/install/configure.rst View File

@@ -1,7 +1,7 @@
1 1
 .. _configure:
2 2
 
3
-Configure
4
-~~~~~~~~~
3
+ML2 Configuriation
4
+~~~~~~~~~~~~~~~~~~
5 5
 
6 6
 This section decribes how to configure Neutron configuration files to enable
7 7
 the networking-ansible ML2 driver and configure switch devices that will be

+ 3
- 6
doc/source/install/index.rst View File

@@ -4,7 +4,9 @@ Install and configure
4 4
 This section describes how to install and configure the networking-ansible
5 5
 ML2 Driver, code-named networking-ansible, on the controller node.
6 6
 This section assumes that you already have a working OpenStack
7
-environment with Neutron server included.
7
+environment with Neutron server included. For guides to assist in installing
8
+and deploying OpenStack visit
9
+`OpenStack Docs <https://docs.openstack.org/>`_.
8 10
 
9 11
 Perform installation configuration steps on each controller node that has a Neutron server running.
10 12
 
@@ -20,8 +22,3 @@ Perform installation configuration steps on each controller node that has a Neut
20 22
 .. note::
21 23
 
22 24
    Installation and configuration may vary by distribution.
23
-
24
-This chapter assumes a working setup of OpenStack that includes Neutron server.
25
-For guides to assist in installing and deploying OpenStack visit
26
-`OpenStack Docs <https://docs.openstack.org/>`_.
27
-

+ 3
- 3
doc/source/install/install.rst View File

@@ -4,9 +4,9 @@ Install
4 4
 ~~~~~~~
5 5
 
6 6
 This section describes how to install and configure the Networking-Ansible
7
-Driver, code-named networking_ansible, on the controller node. This section
8
-assumes that you already have a working OpenStack environment with Neutron
9
-configured to provide VLAN tenant networking.
7
+library, code-named networking_ansible. If you plan to use the library as an
8
+ML2 driver in OpenStack, this section assumes that you already have a working
9
+OpenStack environment with Neutron configured to provide VLAN tenant networking.
10 10
 
11 11
 .. note::
12 12
 

+ 5
- 1
doc/source/install/next-steps.rst View File

@@ -3,6 +3,10 @@
3 3
 Next steps
4 4
 ~~~~~~~~~~
5 5
 
6
-Your OpenStack environment now includes the networking-ansible ML2 Driver.
6
+If you have installed and configured Networking-Ansible as an ML2 driver, your
7
+OpenStack environment now includes the networking-ansible ML2 Driver.
7 8
 
8 9
 To add additional services, see https://docs.openstack.org/.
10
+
11
+If you plan to use Networking-Ansible as a Python API the module can now be
12
+imported and instatiated. See :ref:`api`.

+ 8
- 4
doc/source/install/prerequisites.rst View File

@@ -1,9 +1,9 @@
1 1
 Prerequisites
2 2
 -------------
3 3
 
4
-To successfully install and configure the Networking-Ansible ML2 Driver, you
5
-will need a few prerequisites. Collecting this information and ensuring these
6
-resources are available will ensure a successful installation.
4
+To successfully install and configure the Networking-Ansible library, you
5
+will possibly need a few prerequisites. Collecting this information and ensuring
6
+these resources are available will ensure a successful installation.
7 7
 
8 8
 #. Switch credentials that allow configuration changes to the ports that the
9 9
    deployed baremetal guests are connected to.
@@ -16,9 +16,13 @@ resources are available will ensure a successful installation.
16 16
    a VLAN to that port. It will optionally need access to create VLANs if
17 17
    you choose not to predefine the VLANs that will be used.
18 18
 
19
-#. OpenStack must be installed with Neutron configured to provide VLAN tenant
19
+#. If you plan to configure networking-ansible as an ML2 driver in OpenStack,
20
+   OpenStack must be installed with Neutron configured to provide VLAN tenant
20 21
    networking.
21 22
 
22 23
    This prerequisite is currently outside the scope of this document. Please
23 24
    refer to Neutron's documentation or other guides to provide VLAN tenant
24 25
    networking.
26
+
27
+   For guides to assist in installing and deploying OpenStack visit
28
+   `OpenStack Docs <https://docs.openstack.org/>`_.

+ 2
- 2
doc/source/install/verify.rst View File

@@ -1,7 +1,7 @@
1 1
 .. _verify:
2 2
 
3
-Verify operation
4
-~~~~~~~~~~~~~~~~
3
+Verify ML2 operation
4
+~~~~~~~~~~~~~~~~~~~~
5 5
 
6 6
 Verify operation of the networking-ansible ML2 Driver service.
7 7
 

+ 46
- 0
doc/source/user/api.rst View File

@@ -0,0 +1,46 @@
1
+.. _api:
2
+
3
+==========
4
+Python API
5
+==========
6
+
7
+Networking-Ansible can be called directly via python API. This method does not
8
+require a running OpenStack, with neutron.
9
+
10
+In this section, this use case will be exercised in a set of example commands to
11
+show how end users could import the networking-ansible API and call it to
12
+execute switch level network configuration.
13
+
14
+#. In a python environment import the networking-ansible class.
15
+
16
+  .. code-block:: console
17
+
18
+    from networking_ansible.api import NetworkingAnsible
19
+
20
+#. Instantiate the NetworkingAnsible class. This requires a dictionary that
21
+   represents an Ansible Inventory data structure. This data structure could be
22
+   read from a file or built dynamically by the code that is instantiating the
23
+   class. This example will statically assign the data structure to a variable
24
+   to show the expected data structure.
25
+
26
+  .. code-block:: console
27
+
28
+    inventory = {'all':
29
+      {'hosts':
30
+        {'examplehost':
31
+          {'ansible_network_os': 'openswitch',
32
+           'ansible_host': '5.6.7.8',
33
+           'ansible_user': 'ansible',
34
+           'ansible_ssh_pass': 'password',
35
+          }
36
+        }
37
+      }
38
+    }
39
+    net_ans = NetworkingAnsible(inventory)
40
+
41
+#. Call functions to configure the inventory.
42
+
43
+  .. code-block:: console
44
+
45
+    vlan = 37
46
+    net_ans.create_network(vlan)

+ 5
- 33
doc/source/user/index.rst View File

@@ -2,38 +2,10 @@
2 2
 Users guide
3 3
 ===========
4 4
 
5
-Networking-Ansible is currently tested with one use case, Ironic Baremetal Guests.
6
-In this section this use case will be exercised in a set of example commands to
7
-show how end users would use ironic to provision baremetal nodes. Provisioning
8
-baremetal nodes using ironic with networking-ansible would use networking-ansible
9
-to manage the guest's switch level network configuration. Networking-Ansible is used by
10
-ironic to first assign a baremetal guest's switchport to the Ironic provisoning
11
-network to provision the baremetal guest. After provisoning, the baremetal
12
-guest's switchport is assigned to the VLAN assigned by Neutron to guest's tenant network.
5
+Networking-Ansible is able to be used in two possible senarios.
13 6
 
14
-The example shown here mirrors a user's expereience deploying a guest with
15
-Ironic. The end user's experience using networking-ansible is via Neutron and
16
-Nova. Nova will select a baremetal node as its target when a properly configured
17
-baremetal flavor is provided to the OpenStack server create command.
7
+.. toctree::
8
+   :maxdepth: 2
18 9
 
19
-#. An administrator will provide Ironic node(s) that are available for
20
-   provisioning and a baremetal flavor.
21
-
22
-  .. code-block:: console
23
-
24
-    openstack baremetal node list
25
-    openstack flavor list
26
-
27
-#. Create a tenant VLAN network and subnet that uses the physical network the guest is attached to.
28
-
29
-  .. code-block:: console
30
-
31
-    openstack network create --provider-network-type vlan --provider-physical-network datacentre my-tenant-net
32
-    openstack subnet create --network tenant-net --subnet-range 192.168.3.0/24 --allocation-pool start=192.168.3.10,end=192.168.3.20 tenant-subnet
33
-
34
-#. Execute server create using the tenant network just created. This assumes
35
-   disk images and keypairs are already created and available.
36
-
37
-  .. code-block:: console
38
-
39
-    openstack server create --image a-baremetal-image --flavor baremetal --nic net-id={my-tenant-net uuid} --key-name my-keypair bm-instance
10
+   ironic
11
+   api

+ 42
- 0
doc/source/user/ironic.rst View File

@@ -0,0 +1,42 @@
1
+======================
2
+Ironic Baremetal Guest
3
+======================
4
+
5
+Networking-Ansible can be used as the ML2 driver that communicates with the
6
+switch that baremetal guests are cabled to. These guests need to have their
7
+port configuration updated depending on their deployment status.
8
+
9
+In this section, this use case will be exercised in a set of example commands to
10
+show how end users would use ironic to provision baremetal nodes. Provisioning
11
+baremetal nodes using ironic with networking-ansible would use networking-ansible
12
+to manage the guest's switch level network configuration. Networking-Ansible is used by
13
+ironic to first assign a baremetal guest's switchport to the Ironic provisoning
14
+network to provision the baremetal guest. After provisoning, the baremetal
15
+guest's switchport is assigned to the VLAN assigned by Neutron to guest's tenant network.
16
+
17
+The example shown here mirrors a user's expereience deploying a guest with
18
+Ironic. The end user's experience using networking-ansible is via Neutron and
19
+Nova. Nova will select a baremetal node as its target when a properly configured
20
+baremetal flavor is provided to the OpenStack server create command.
21
+
22
+#. An administrator will provide Ironic node(s) that are available for
23
+   provisioning and a baremetal flavor.
24
+
25
+  .. code-block:: console
26
+
27
+    openstack baremetal node list
28
+    openstack flavor list
29
+
30
+#. Create a tenant VLAN network and subnet that uses the physical network the guest is attached to.
31
+
32
+  .. code-block:: console
33
+
34
+    openstack network create --provider-network-type vlan --provider-physical-network datacentre my-tenant-net
35
+    openstack subnet create --network tenant-net --subnet-range 192.168.3.0/24 --allocation-pool start=192.168.3.10,end=192.168.3.20 tenant-subnet
36
+
37
+#. Execute server create using the tenant network just created. This assumes
38
+   disk images and keypairs are already created and available.
39
+
40
+  .. code-block:: console
41
+
42
+    openstack server create --image a-baremetal-image --flavor baremetal --nic net-id={my-tenant-net uuid} --key-name my-keypair bm-instance

+ 0
- 1
networking_ansible/__init__.py View File

@@ -14,6 +14,5 @@
14 14
 
15 15
 import pbr.version
16 16
 
17
-
18 17
 __version__ = pbr.version.VersionInfo(
19 18
     'networking-ansible').version_string()

networking_ansible/ansible_networking.py → networking_ansible/api.py View File

@@ -21,7 +21,7 @@ from networking_ansible import exceptions
21 21
 LOG = logging.getLogger(__name__)
22 22
 
23 23
 
24
-class AnsibleNetworking(object):
24
+class NetworkingAnsible(object):
25 25
     """Object to invoke ansible_runner to call Ansible Networking
26 26
 
27 27
     Hold inventory and provide an interface for calling

+ 5
- 5
networking_ansible/ml2/mech_driver.py View File

@@ -17,10 +17,10 @@ from neutron.db import provisioning_blocks
17 17
 from neutron.plugins.ml2.common import exceptions as ml2_exc
18 18
 from neutron_lib.api.definitions import portbindings
19 19
 from neutron_lib.callbacks import resources
20
-from neutron_lib.plugins.ml2 import api
20
+from neutron_lib.plugins.ml2 import api as ml2api
21 21
 from oslo_log import log as logging
22 22
 
23
-from networking_ansible import ansible_networking
23
+from networking_ansible import api
24 24
 from networking_ansible import config
25 25
 
26 26
 LOG = logging.getLogger(__name__)
@@ -28,7 +28,7 @@ LOG = logging.getLogger(__name__)
28 28
 ANSIBLE_NETWORKING_ENTITY = 'ANSIBLENETWORKING'
29 29
 
30 30
 
31
-class AnsibleMechanismDriver(api.MechanismDriver):
31
+class AnsibleMechanismDriver(ml2api.MechanismDriver):
32 32
     """ML2 Mechanism Driver for Ansible Networking
33 33
 
34 34
     https://www.ansible.com/integrations/networks
@@ -38,7 +38,7 @@ class AnsibleMechanismDriver(api.MechanismDriver):
38 38
         LOG.debug("Initializing Ansible ML2 driver")
39 39
 
40 40
         inventory = config.build_ansible_inventory()
41
-        self.ansnet = ansible_networking.AnsibleNetworking(inventory)
41
+        self.ansnet = api.NetworkingAnsible(inventory)
42 42
 
43 43
     def create_network_postcommit(self, context):
44 44
         """Create a network.
@@ -228,7 +228,7 @@ class AnsibleMechanismDriver(api.MechanismDriver):
228 228
         # Assign port to network
229 229
         self.ansnet.vlan_access_port('assign', context.current,
230 230
                                      context.network.current)
231
-        context.set_binding(segments[0][api.ID],
231
+        context.set_binding(segments[0][ml2api.ID],
232 232
                             portbindings.VIF_TYPE_OTHER, {})
233 233
 
234 234
     @staticmethod

+ 2
- 2
networking_ansible/tests/unit/base.py View File

@@ -19,7 +19,7 @@ from oslo_config import cfg
19 19
 from oslotest import base
20 20
 import pbr
21 21
 
22
-from networking_ansible import ansible_networking
22
+from networking_ansible import api
23 23
 from networking_ansible import config
24 24
 from networking_ansible.ml2 import mech_driver
25 25
 
@@ -108,4 +108,4 @@ class NetworkingAnsibleTestCase(BaseTestCase):
108 108
             self.mock_port_context.network.current
109 109
         ]
110 110
 
111
-        self.mech.ansnet = ansible_networking.AnsibleNetworking(self.inventory)
111
+        self.mech.ansnet = api.NetworkingAnsible(self.inventory)

+ 7
- 7
networking_ansible/tests/unit/ml2/test_mech_driver.py View File

@@ -25,7 +25,7 @@ from neutron_lib.api.definitions import portbindings
25 25
 from neutron_lib.api.definitions import provider_net
26 26
 import webob.exc
27 27
 
28
-from networking_ansible import ansible_networking as anet
28
+from networking_ansible import api
29 29
 from networking_ansible import exceptions
30 30
 from networking_ansible.tests.unit import base
31 31
 
@@ -49,7 +49,7 @@ class NetAnsibleML2Base(test_plugin.Ml2PluginV2TestCase):
49 49
         super(NetAnsibleML2Base, self).setUp()
50 50
 
51 51
 
52
-@mock.patch.object(anet.AnsibleNetworking, 'vlan_access_port')
52
+@mock.patch.object(api.NetworkingAnsible, 'vlan_access_port')
53 53
 @mock.patch('networking_ansible.ml2.mech_driver.provisioning_blocks',
54 54
             autospec=True)
55 55
 class TestBindPort(base.NetworkingAnsibleTestCase):
@@ -106,7 +106,7 @@ class TestIsPortBound(base.NetworkingAnsibleTestCase):
106 106
             self.mech._is_port_bound(self.mock_port_context.current))
107 107
 
108 108
 
109
-@mock.patch.object(anet.AnsibleNetworking, 'create_network')
109
+@mock.patch.object(api.NetworkingAnsible, 'create_network')
110 110
 class TestCreateNetworkPostCommit(base.NetworkingAnsibleTestCase):
111 111
     def test_create_network_postcommit(self, mock_create_network):
112 112
         self.mech.create_network_postcommit(self.mock_net_context)
@@ -137,7 +137,7 @@ class TestCreateNetworkPostCommit(base.NetworkingAnsibleTestCase):
137 137
         mock_create_netwrk.assert_not_called()
138 138
 
139 139
 
140
-@mock.patch.object(anet.AnsibleNetworking, 'delete_network')
140
+@mock.patch.object(api.NetworkingAnsible, 'delete_network')
141 141
 class TestDeleteNetworkPostCommit(base.NetworkingAnsibleTestCase):
142 142
     def test_delete_network_postcommit(self, mock_delete_network):
143 143
         self.mech.delete_network_postcommit(self.mock_net_context)
@@ -168,7 +168,7 @@ class TestDeleteNetworkPostCommit(base.NetworkingAnsibleTestCase):
168 168
 
169 169
 @mock.patch('networking_ansible.ml2.mech_driver.'
170 170
             'AnsibleMechanismDriver._is_port_bound')
171
-@mock.patch.object(anet.AnsibleNetworking, 'vlan_access_port')
171
+@mock.patch.object(api.NetworkingAnsible, 'vlan_access_port')
172 172
 class TestDeletePortPostCommit(base.NetworkingAnsibleTestCase):
173 173
     def test_delete_port_postcommit_current(self,
174 174
                                             mock_vlan_access,
@@ -196,7 +196,7 @@ class TestInit(base.NetworkingAnsibleTestCase):
196 196
 
197 197
 @mock.patch('networking_ansible.ml2.mech_driver.'
198 198
             'AnsibleMechanismDriver._is_port_bound')
199
-@mock.patch.object(anet.AnsibleNetworking, 'vlan_access_port')
199
+@mock.patch.object(api.NetworkingAnsible, 'vlan_access_port')
200 200
 @mock.patch('networking_ansible.ml2.mech_driver.provisioning_blocks',
201 201
             autospec=True)
202 202
 class TestUpdatePortPostCommit(base.NetworkingAnsibleTestCase):
@@ -224,7 +224,7 @@ class TestUpdatePortPostCommit(base.NetworkingAnsibleTestCase):
224 224
         mock_vlan_access.assert_not_called()
225 225
 
226 226
 
227
-@mock.patch.object(anet.AnsibleNetworking, '_run_task')
227
+@mock.patch.object(api.NetworkingAnsible, '_run_task')
228 228
 class TestML2PluginIntegration(NetAnsibleML2Base):
229 229
     _mechanism_drivers = ['ansible']
230 230
     HOSTS = ['testinghost', 'otherhost']

networking_ansible/tests/unit/test_ansible_networking.py → networking_ansible/tests/unit/test_api.py View File

@@ -21,16 +21,16 @@ from networking_ansible.tests.unit import base
21 21
 
22 22
 class TestCreateDeleteNetwork(base.NetworkingAnsibleTestCase):
23 23
 
24
-    @mock.patch('networking_ansible.ansible_networking'
25
-                '.AnsibleNetworking._run_task')
24
+    @mock.patch('networking_ansible.api'
25
+                '.NetworkingAnsible._run_task')
26 26
     def test_create_network(self, mock_run_task):
27 27
         self.mech.ansnet.create_network(self.testhost, self.testsegid)
28 28
         mock_run_task.assert_called_once_with('create_network',
29 29
                                               self.testhost,
30 30
                                               self.testsegid)
31 31
 
32
-    @mock.patch('networking_ansible.ansible_networking'
33
-                '.AnsibleNetworking._run_task')
32
+    @mock.patch('networking_ansible.api'
33
+                '.NetworkingAnsible._run_task')
34 34
     def test_delete_network(self, mock_run_task):
35 35
         self.mech.ansnet.delete_network(self.testhost, self.testsegid)
36 36
         mock_run_task.assert_called_once_with('delete_network',
@@ -38,7 +38,7 @@ class TestCreateDeleteNetwork(base.NetworkingAnsibleTestCase):
38 38
                                               self.testsegid)
39 39
 
40 40
 
41
-@mock.patch('networking_ansible.ansible_networking.ansible_runner')
41
+@mock.patch('networking_ansible.api.ansible_runner')
42 42
 class TestRunTask(base.NetworkingAnsibleTestCase):
43 43
     def test_run_task_no_switchport(self, mock_ans_runner):
44 44
         mock_result = mock_ans_runner.run.return_value
@@ -86,8 +86,8 @@ class TestRunTask(base.NetworkingAnsibleTestCase):
86 86
                           'fake_switchport')
87 87
 
88 88
 
89
-@mock.patch('networking_ansible.ansible_networking'
90
-            '.AnsibleNetworking._run_task')
89
+@mock.patch('networking_ansible.api'
90
+            '.NetworkingAnsible._run_task')
91 91
 class TestVlanAccessPort(base.NetworkingAnsibleTestCase):
92 92
 
93 93
     def test_assign_vlan_access_port(self, mock_run_task):

+ 5
- 0
requirements.txt View File

@@ -6,3 +6,8 @@ ansible-runner>=1.0.5 # Apache-2.0
6 6
 neutron>=13.0.0.0b1 # Apache-2.0
7 7
 neutron-lib>=1.18.0 # Apache-2.0
8 8
 pbr>=2.0 # Apache-2.0
9
+
10
+# these are explictly defined for python API support
11
+# oslo-log is ont in openstack-requirements
12
+# TODO(radez) figure out how to handle logging
13
+# oslo-log

Loading…
Cancel
Save