Browse Source

Updating docs for Rocky Release

- formatting to Provider
- more clarifications for installation and configuration
- more clarifications on prerequisites
- add pip installation
- clean up references to Ansible Networking ML2 driver.

Change-Id: If28e9d92b0b744148555c634bb5bf0828ff0bc5b
changes/68/597568/3
Dan Radez 9 months ago
parent
commit
55a9a29471

+ 8
- 4
README.rst View File

@@ -4,10 +4,14 @@ Networking-Ansible ML2 Driver
4 4
 
5 5
 Overview
6 6
 --------
7
-Networking-Ansible is a Neutron ML2 driver that abstracts the interaction with
8
-switch hardware to Ansible Networking. This driver may not be tested with all
9
-the modules included with Ansible Networking. In theory it should work with any
10
-switch that has compatible modules included with Ansible Networking.
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
9
+tested with all the modules included with Ansible Networking. In theory it
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
13
+about adding support for an Ansible Networking driver to the openstack-ml2
14
+Ansible role.
11 15
 
12 16
 * Free software: Apache license
13 17
 * Documentation: https://networking-ansible.readthedocs.io/en/latest/

+ 8
- 8
doc/source/contributor/provider.rst View File

@@ -22,26 +22,26 @@ networking-ansible.
22 22
 
23 23
 * defaults.yaml
24 24
 
25
-   Defines default values for segmentation name and ID. For example some
26
-   switch vendors use the name "default" and VLAN ID 1 as a default VLAN
27
-   to assign switchports to. Open vSwitch expects no VLAN ID and VLAN name
28
-   in the case that port is not assigned to a specific VLAN.
25
+  Defines default values for segmentation name and ID. For example some
26
+  switch vendors use the name "default" and VLAN ID 1 as a default VLAN
27
+  to assign switchports to. Open vSwitch expects no VLAN ID and VLAN name
28
+  in the case that port is not assigned to a specific VLAN.
29 29
 
30 30
 * create_network.yaml
31 31
 
32
-   Defines the Ansible tasks to create a VLAN on a switch.
32
+  Defines the Ansible tasks to create a VLAN on a switch.
33 33
 
34 34
 * delete_network.yaml
35 35
 
36
-   Defines the Ansible tasks to delete a VLAN on a switch.
36
+  Defines the Ansible tasks to delete a VLAN on a switch.
37 37
 
38 38
 * update_port.yaml
39 39
 
40
-   Defines the Ansible tasks to assign a VLAN to a switchport in access mode.
40
+  Defines the Ansible tasks to assign a VLAN to a switchport in access mode.
41 41
 
42 42
 * delete_port.yaml
43 43
 
44
-   Defines the Ansible tasks to remove configuration from a switchport.
44
+  Defines the Ansible tasks to remove configuration from a switchport.
45 45
 
46 46
 [1] https://docs.ansible.com/ansible/2.5/modules/list_of_network_modules.html
47 47
 

+ 2
- 1
doc/source/index.rst View File

@@ -7,7 +7,8 @@
7 7
 Welcome to Networking-Ansible Documentation
8 8
 ===========================================
9 9
 
10
-Contents:
10
+Contents
11
+~~~~~~~~
11 12
 
12 13
 .. toctree::
13 14
    :maxdepth: 2

+ 16
- 17
doc/source/install/configure.rst View File

@@ -7,20 +7,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
8 8
 managed by networking-ansible.
9 9
 
10
-#. Register the networking-ansible ML2 Driver with Neutron.
11
-
12
-    TODO(radez) is this done automatially when the egg code is installed?
13
-    Edit the entry_points.txt file. Add AnsibleMechanismDriver to the
14
-    neutron.ml2.mechanism_drivers section.
15
-
16
-    .. code-block:: ini
17
-
18
-        [neutron.ml2.mechanism_drivers]
19
-        ...
20
-        ansible = ansible_networking.ml2.mech_driver:AnsibleMechanismDriver
21
-        ...
22
-
23
-
24 10
 #. Configure type_drivers and mechanism_drivers and network_vlan_ranges.
25 11
 
26 12
     Add ``vlan`` to ``type_drivers``, ``ansible`` to ``mechanism_drivers``, and
@@ -52,16 +38,29 @@ managed by networking-ansible.
52 38
     .. code-block:: ini
53 39
 
54 40
       [ansible:myhostname]
55
-      ansible_network_os=vyos
41
+      ansible_network_os=junos
56 42
       ansible_host=10.10.2.250
57 43
       ansible_user=ansible
58 44
       ansible_pass=password
59 45
 
60 46
     * myhostname is an arbitrary internal identifier used only in ironic's link_local_information.
61 47
     * ansible_network_os is a valid Ansible Networking value to indicate switch type.
62
-      TODO(radez) enumerate what options are supported
48
+      Tested with networking-ansible: openvswitch, junos
49
+      Untested but valid with networking-ansible: eos, nxos
50
+      See contributor/provider for more information.
63 51
     * ansible_host is the IP address or hostname used to connect to the switch.
64
-    * ansible_user and pass are credentials used to connect to the switch.
52
+    * ansible_user username of the credentials used to connect to the switch.
53
+    * ansible_pass password of the credentials used to connect to the switch.
54
+
55
+    Additional available parameters:
56
+
57
+    .. code-block:: ini
58
+
59
+      ansible_ssh_private_key_file=/path/to/ansible-ssh
60
+      manage_vlans=True
61
+
62
+    * ansible_ssh_private_key_file can be used as an alternative to ansible_pass
63
+      to use ssh key authentication instead of password authentication.
65 64
     * manage_vlans is optional and defaults to True. Set this to False for a
66 65
       switch if networking-ansible should not create and delete VLANs on the device.
67 66
 

+ 10
- 9
doc/source/install/index.rst View File

@@ -1,14 +1,16 @@
1 1
 Install and configure
2 2
 ~~~~~~~~~~~~~~~~~~~~~
3 3
 
4
-This section describes how to install and configure the
5
-Ansible Networking ML2 Driver, code-named networking_ansible, on the controller node.
6
-
4
+This section describes how to install and configure the networking-ansible
5
+ML2 Driver, code-named networking-ansible, on the controller node.
7 6
 This section assumes that you already have a working OpenStack
8
-environment with at least the following components installed:
9
-.. (add the appropriate services here and further notes)
7
+environment with Neutron server included.
8
+
9
+Perform installation configuration steps on each controller node that has a Neutron server running.
10
+
11
+.. note::
10 12
 
11
-Note that installation and configuration vary by distribution.
13
+   Installation and configuration may vary by distribution.
12 14
 
13 15
 .. toctree::
14 16
    :maxdepth: 2
@@ -19,7 +21,6 @@ Note that installation and configuration vary by distribution.
19 21
    verify.rst
20 22
    next-steps.rst
21 23
 
22
-This chapter assumes a working setup of OpenStack following the
23
-`OpenStack Installation Tutorial
24
-<https://docs.openstack.org/project-install-guide/rocky/>`_.
24
+This chapter assumes a working setup of OpenStack that includes Neutron server following the
25
+`OpenStack Installation Tutorial <https://docs.openstack.org/project-install-guide/rocky/>`_.
25 26
 

+ 14
- 0
doc/source/install/install-pip.rst View File

@@ -0,0 +1,14 @@
1
+Manual Installation
2
+~~~~~~~~~~~~~~~~~~~
3
+This section describes how to install the Networking-Ansible ML2 Driver
4
+in the case that a package is not available. Networking-Ansible can be
5
+installed from PyPI using pip.
6
+
7
+Install and configure components
8
+--------------------------------
9
+
10
+#. Install the packages:
11
+
12
+   .. code-block:: console
13
+
14
+      # pip install networking-ansible

+ 7
- 6
doc/source/install/install.rst View File

@@ -3,14 +3,14 @@
3 3
 Install
4 4
 ~~~~~~~
5 5
 
6
-This section describes how to install and configure the
7
-Ansible Networking ML2 Driver, code-named networking_ansible, on the controller node.
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.
8 10
 
9
-This section assumes that you already have a working OpenStack
10
-environment with at least the following components installed:
11
-.. (add the appropriate services here and further notes)
11
+.. note::
12 12
 
13
-Note that installation and configuration vary by distribution.
13
+   Note that installation and configuration may vary by distribution.
14 14
 
15 15
 .. toctree::
16 16
    :maxdepth: 2
@@ -18,3 +18,4 @@ Note that installation and configuration vary by distribution.
18 18
    install-obs.rst
19 19
    install-rdo.rst
20 20
    install-ubuntu.rst
21
+   install-pip.rst

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

@@ -1,7 +1,24 @@
1 1
 Prerequisites
2 2
 -------------
3 3
 
4
-Before you install and configure the Ansible Networking ML2 Driver,
5
-you must configure your OpenStack installation for vlan tenant networking.
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.
6 7
 
7
-#. TODO: Link to or create documentation to show how to do this.
8
+#. Switch credentials that allow configuration changes to the ports that the
9
+   deployed baremetal guests are connected to.
10
+
11
+   For security purposes it is important that you do not provide administrator
12
+   access to the switch for networking-ansible. A user should be created
13
+   and granted access for the permissions needed for networking-ansible.
14
+
15
+   Networking-Ansible will need to configure a port in access mode and assign
16
+   a VLAN to that port. It will optionally need access to create VLANs if
17
+   you choose not to predefine the VLANs that will be used.
18
+
19
+#. OpenStack must be installed with Neutron configured to provide VLAN tenant
20
+   networking.
21
+
22
+   This prerequisite is currently outside the scope of this document. Please
23
+   refer to Neutron's documentation or other guides to provide VLAN tenant
24
+   networking.

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

@@ -3,11 +3,7 @@
3 3
 Verify operation
4 4
 ~~~~~~~~~~~~~~~~
5 5
 
6
-Verify operation of the Ansible Networking ML2 Driver service.
7
-
8
-.. note::
9
-
10
-   Perform these commands on the controller node.
6
+Verify operation of the networking-ansible ML2 Driver service.
11 7
 
12 8
 #. Grep the neutron logs for ansible and confirm the driver has been registered and configured.
13 9
    root access CLI commands:

Loading…
Cancel
Save