summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDan Radez <dradez@redhat.com>2018-08-29 11:08:51 -0400
committerDan Radez <dradez@redhat.com>2018-08-30 08:19:08 -0400
commit55a9a29471ab4012651a01d7851e8dfd0009fb2d (patch)
tree507e1145b7f5e3b3a2984afa2f418ba61f7a1b8a
parent6b98ccbbcc24479b586b99834508468744d5f18b (diff)
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
Notes
Notes (review): Code-Review+2: Jakub Libosvar <libosvar@redhat.com> Workflow+1: Dan Radez <dradez@redhat.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Thu, 30 Aug 2018 12:55:55 +0000 Reviewed-on: https://review.openstack.org/597568 Project: openstack/networking-ansible Branch: refs/heads/master
-rw-r--r--README.rst12
-rw-r--r--doc/source/contributor/provider.rst16
-rw-r--r--doc/source/index.rst3
-rw-r--r--doc/source/install/configure.rst33
-rw-r--r--doc/source/install/index.rst19
-rw-r--r--doc/source/install/install-pip.rst14
-rw-r--r--doc/source/install/install.rst13
-rw-r--r--doc/source/install/prerequisites.rst23
-rw-r--r--doc/source/install/verify.rst6
9 files changed, 86 insertions, 53 deletions
diff --git a/README.rst b/README.rst
index fc4e699..321de70 100644
--- a/README.rst
+++ b/README.rst
@@ -4,10 +4,14 @@ Networking-Ansible ML2 Driver
4 4
5Overview 5Overview
6-------- 6--------
7Networking-Ansible is a Neutron ML2 driver that abstracts the interaction with 7Networking-Ansible is a Neutron ML2 driver that abstracts the management and
8switch hardware to Ansible Networking. This driver may not be tested with all 8interaction with switching hardware to Ansible Networking. This driver is not
9the modules included with Ansible Networking. In theory it should work with any 9tested with all the modules included with Ansible Networking. In theory it
10switch that has compatible modules included with Ansible Networking. 10should work with any switch that has compatible modules included with Ansible
11Networking if the provider tasks are added to the Ansible openstack-ml2 role
12included with this driver. See the contributor documentation for more information
13about adding support for an Ansible Networking driver to the openstack-ml2
14Ansible role.
11 15
12* Free software: Apache license 16* Free software: Apache license
13* Documentation: https://networking-ansible.readthedocs.io/en/latest/ 17* Documentation: https://networking-ansible.readthedocs.io/en/latest/
diff --git a/doc/source/contributor/provider.rst b/doc/source/contributor/provider.rst
index fbaa2f3..08bdddf 100644
--- a/doc/source/contributor/provider.rst
+++ b/doc/source/contributor/provider.rst
@@ -22,26 +22,26 @@ networking-ansible.
22 22
23* defaults.yaml 23* defaults.yaml
24 24
25 Defines default values for segmentation name and ID. For example some 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 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 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. 28 in the case that port is not assigned to a specific VLAN.
29 29
30* create_network.yaml 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* delete_network.yaml 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* update_port.yaml 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* delete_port.yaml 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[1] https://docs.ansible.com/ansible/2.5/modules/list_of_network_modules.html 46[1] https://docs.ansible.com/ansible/2.5/modules/list_of_network_modules.html
47 47
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 038cb69..9eeedd4 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -7,7 +7,8 @@
7Welcome to Networking-Ansible Documentation 7Welcome to Networking-Ansible Documentation
8=========================================== 8===========================================
9 9
10Contents: 10Contents
11~~~~~~~~
11 12
12.. toctree:: 13.. toctree::
13 :maxdepth: 2 14 :maxdepth: 2
diff --git a/doc/source/install/configure.rst b/doc/source/install/configure.rst
index c4f9872..e97f99d 100644
--- a/doc/source/install/configure.rst
+++ b/doc/source/install/configure.rst
@@ -7,20 +7,6 @@ This section decribes how to configure Neutron configuration files to enable
7the networking-ansible ML2 driver and configure switch devices that will be 7the networking-ansible ML2 driver and configure switch devices that will be
8managed by networking-ansible. 8managed 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#. Configure type_drivers and mechanism_drivers and network_vlan_ranges. 10#. Configure type_drivers and mechanism_drivers and network_vlan_ranges.
25 11
26 Add ``vlan`` to ``type_drivers``, ``ansible`` to ``mechanism_drivers``, and 12 Add ``vlan`` to ``type_drivers``, ``ansible`` to ``mechanism_drivers``, and
@@ -52,16 +38,29 @@ managed by networking-ansible.
52 .. code-block:: ini 38 .. code-block:: ini
53 39
54 [ansible:myhostname] 40 [ansible:myhostname]
55 ansible_network_os=vyos 41 ansible_network_os=junos
56 ansible_host=10.10.2.250 42 ansible_host=10.10.2.250
57 ansible_user=ansible 43 ansible_user=ansible
58 ansible_pass=password 44 ansible_pass=password
59 45
60 * myhostname is an arbitrary internal identifier used only in ironic's link_local_information. 46 * myhostname is an arbitrary internal identifier used only in ironic's link_local_information.
61 * ansible_network_os is a valid Ansible Networking value to indicate switch type. 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 * ansible_host is the IP address or hostname used to connect to the switch. 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 * manage_vlans is optional and defaults to True. Set this to False for a 64 * manage_vlans is optional and defaults to True. Set this to False for a
66 switch if networking-ansible should not create and delete VLANs on the device. 65 switch if networking-ansible should not create and delete VLANs on the device.
67 66
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
index 616b6f1..8900766 100644
--- a/doc/source/install/index.rst
+++ b/doc/source/install/index.rst
@@ -1,14 +1,16 @@
1Install and configure 1Install and configure
2~~~~~~~~~~~~~~~~~~~~~ 2~~~~~~~~~~~~~~~~~~~~~
3 3
4This section describes how to install and configure the 4This section describes how to install and configure the networking-ansible
5Ansible Networking ML2 Driver, code-named networking_ansible, on the controller node. 5ML2 Driver, code-named networking-ansible, on the controller node.
6
7This section assumes that you already have a working OpenStack 6This section assumes that you already have a working OpenStack
8environment with at least the following components installed: 7environment with Neutron server included.
9.. (add the appropriate services here and further notes) 8
9Perform installation configuration steps on each controller node that has a Neutron server running.
10
11.. note::
10 12
11Note that installation and configuration vary by distribution. 13 Installation and configuration may vary by distribution.
12 14
13.. toctree:: 15.. toctree::
14 :maxdepth: 2 16 :maxdepth: 2
@@ -19,7 +21,6 @@ Note that installation and configuration vary by distribution.
19 verify.rst 21 verify.rst
20 next-steps.rst 22 next-steps.rst
21 23
22This chapter assumes a working setup of OpenStack following the 24This chapter assumes a working setup of OpenStack that includes Neutron server following the
23`OpenStack Installation Tutorial 25`OpenStack Installation Tutorial <https://docs.openstack.org/project-install-guide/rocky/>`_.
24<https://docs.openstack.org/project-install-guide/rocky/>`_.
25 26
diff --git a/doc/source/install/install-pip.rst b/doc/source/install/install-pip.rst
new file mode 100644
index 0000000..d7ad524
--- /dev/null
+++ b/doc/source/install/install-pip.rst
@@ -0,0 +1,14 @@
1Manual Installation
2~~~~~~~~~~~~~~~~~~~
3This section describes how to install the Networking-Ansible ML2 Driver
4in the case that a package is not available. Networking-Ansible can be
5installed from PyPI using pip.
6
7Install and configure components
8--------------------------------
9
10#. Install the packages:
11
12 .. code-block:: console
13
14 # pip install networking-ansible
diff --git a/doc/source/install/install.rst b/doc/source/install/install.rst
index d235008..e35f792 100644
--- a/doc/source/install/install.rst
+++ b/doc/source/install/install.rst
@@ -3,14 +3,14 @@
3Install 3Install
4~~~~~~~ 4~~~~~~~
5 5
6This section describes how to install and configure the 6This section describes how to install and configure the Networking-Ansible
7Ansible Networking ML2 Driver, code-named networking_ansible, on the controller node. 7Driver, code-named networking_ansible, on the controller node. This section
8assumes that you already have a working OpenStack environment with Neutron
9configured to provide VLAN tenant networking.
8 10
9This section assumes that you already have a working OpenStack 11.. note::
10environment with at least the following components installed:
11.. (add the appropriate services here and further notes)
12 12
13Note that installation and configuration vary by distribution. 13 Note that installation and configuration may vary by distribution.
14 14
15.. toctree:: 15.. toctree::
16 :maxdepth: 2 16 :maxdepth: 2
@@ -18,3 +18,4 @@ Note that installation and configuration vary by distribution.
18 install-obs.rst 18 install-obs.rst
19 install-rdo.rst 19 install-rdo.rst
20 install-ubuntu.rst 20 install-ubuntu.rst
21 install-pip.rst
diff --git a/doc/source/install/prerequisites.rst b/doc/source/install/prerequisites.rst
index 2191bb0..125166f 100644
--- a/doc/source/install/prerequisites.rst
+++ b/doc/source/install/prerequisites.rst
@@ -1,7 +1,24 @@
1Prerequisites 1Prerequisites
2------------- 2-------------
3 3
4Before you install and configure the Ansible Networking ML2 Driver, 4To successfully install and configure the Networking-Ansible ML2 Driver, you
5you must configure your OpenStack installation for vlan tenant networking. 5will need a few prerequisites. Collecting this information and ensuring these
6resources 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.
diff --git a/doc/source/install/verify.rst b/doc/source/install/verify.rst
index 96581a7..a37c089 100644
--- a/doc/source/install/verify.rst
+++ b/doc/source/install/verify.rst
@@ -3,11 +3,7 @@
3Verify operation 3Verify operation
4~~~~~~~~~~~~~~~~ 4~~~~~~~~~~~~~~~~
5 5
6Verify operation of the Ansible Networking ML2 Driver service. 6Verify operation of the networking-ansible ML2 Driver service.
7
8.. note::
9
10 Perform these commands on the controller node.
11 7
12#. Grep the neutron logs for ansible and confirm the driver has been registered and configured. 8#. Grep the neutron logs for ansible and confirm the driver has been registered and configured.
13 root access CLI commands: 9 root access CLI commands: