Welcome to Networking-Ansible Documentation¶

Prerequisites¶

To successfully install and configure the Networking-Ansible library, you will possibly need a few prerequisites. Collecting this information and ensuring these resources are available will ensure a successful installation.

1. Switch credentials that allow configuration changes to the ports that the deployed baremetal guests are connected to.

   For security purposes it is important that you do not provide administrator access to the switch for networking-ansible. A user should be created and granted access for the permissions needed for networking-ansible.

   Networking-Ansible will need to configure a port in access mode and assign a VLAN to that port. It will optionally need access to create VLANs if you choose not to predefine the VLANs that will be used.

2. If you plan to configure networking-ansible as an ML2 driver in OpenStack, OpenStack must be installed with Neutron configured to provide VLAN tenant networking.

   This prerequisite is currently outside the scope of this document. Please refer to Neutron’s documentation or other guides to provide VLAN tenant networking.

   For guides to assist in installing and deploying OpenStack visit OpenStack Docs.

Install¶

This section describes how to install and configure the Networking-Ansible library, code-named networking_ansible. If you plan to use the library as an ML2 driver in OpenStack, this section assumes that you already have a working OpenStack environment with Neutron configured to provide VLAN tenant networking.

ML2 Configuriation¶

This section decribes how to configure Neutron configuration files to enable the networking-ansible ML2 driver and configure switch devices that will be managed by networking-ansible.

1. Configure type_drivers and mechanism_drivers and network_vlan_ranges.

   Add vlan to type_drivers, ansible to mechanism_drivers, and define the network_vlan_range that will be used by the openstack networks that use this driver.

   [ml2]
   type_drivers = vlan
   mechanism_drivers = ansible
   
   [ml2_type_vlan]
   network_vlan_ranges = physnet1:1000:1099
   

   • Do not remove other values from these comma delimited lists if there are are already values present. Append a comma and your value to the list.
   • physnet1 is an identifier configured in the bridge_mapping TODO(radez) doc ref to bridge_mapping
   • the VLAN range (1000:1099 in this example) is provided by the switch administor. This range is the VLAN IDs assigned by Neutron when a network is created.

2. Add a section for each switch device that will be managed by networking-ansible.

   Create a section for each host with a section name prefixed by ansible: in /etc/neutron/plugins/ml2/ml2_conf.ini.

   [ansible:myhostname]
   ansible_network_os=junos
   ansible_host=10.10.2.250
   ansible_user=ansible
   ansible_pass=password
   

   • myhostname is an arbitrary internal identifier used only in ironic’s link_local_information.
   • ansible_network_os is a valid Ansible Networking value to indicate switch type. Tested with networking-ansible: openvswitch, junos Untested but valid with networking-ansible: eos, nxos See contributor/provider for more information.
   • ansible_host is the IP address or hostname used to connect to the switch.
   • ansible_user username of the credentials used to connect to the switch.
   • ansible_pass password of the credentials used to connect to the switch.

   OpenStack Specific parameters:

   mac=01:23:45:67:89:AB
   manage_vlans=True
   

   • mac is the MAC address of the switch as provided by lldp. This is optional to provide and specific to OpenStack ML2 use cases. It is used for zero touch provisioning using Ironic introspection. Introspection gathers the switch’s MAC and node’s port provided by lldp and populates the baremetal node’s local_link_information. If this parameter is provided in the ML2 ini configuration it will be used to match against the lldp provided MAC to populate internally generated ansible playbooks with the appropriate host name for the switch.
   • manage_vlans is optional and defaults to True. Set this to False for a switch if networking-ansible should not create and delete VLANs on the device.

   Additional parameters and examples:

   ansible_ssh_private_key_file=/path/to/ansible-ssh
   ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q user@hostname"'
   

   • ansible_ssh_private_key_file can be used as an alternative to ansible_pass to use ssh key authentication instead of password authentication.
   • ansible_ssh_common_args is passed to the ssh command Ansible uses. In the example above the ProxyCommand is used to connect to a switch through a proxy.

   Parameters pass through automatically:

   • All parameters not mentioned here are passed from neutron to ansible through inventory. Any inventory parameter that is supported by the version of Ansible should be able to be defined in the switch’s configuration stanza and will passed to Ansible.

3. Restart the Neutron API service

   $ service neturon-server restart
   

Verify ML2 operation¶

Verify operation of the networking-ansible ML2 Driver service.

1. Grep the neutron logs for ansible and confirm the driver has been registered and configured. root access CLI commands:

   $ grep ansible /var/log/neutron/server.log
   INFO neutron.plugins.ml2.managers [-] Configured mechanism driver names: ['ansible']
   INFO neutron.plugins.ml2.managers [-] Loaded mechanism driver names: ['ansible']
   INFO neutron.plugins.ml2.managers [-] Registered mechanism drivers: ['ansible']
   

Next steps¶

If you have installed and configured Networking-Ansible as an ML2 driver, your OpenStack environment now includes the networking-ansible ML2 Driver.

To add additional services, see https://docs.openstack.org/.

If you plan to use Networking-Ansible as a Python API the module can now be imported and instatiated. See Python API.

Ironic Baremetal Guest¶

Networking-Ansible can be used as the ML2 driver that communicates with the switch that baremetal guests are cabled to. These guests need to have their port configuration updated depending on their deployment status.

In this section, this use case will be exercised in a set of example commands to show how end users would use ironic to provision baremetal nodes. Provisioning baremetal nodes using ironic with networking-ansible would use networking-ansible to manage the guest’s switch level network configuration. Networking-Ansible is used by ironic to first assign a baremetal guest’s switchport to the Ironic provisoning network to provision the baremetal guest. After provisoning, the baremetal guest’s switchport is assigned to the VLAN assigned by Neutron to guest’s tenant network.

The example shown here mirrors a user’s expereience deploying a guest with Ironic. The end user’s experience using networking-ansible is via Neutron and Nova. Nova will select a baremetal node as its target when a properly configured baremetal flavor is provided to the OpenStack server create command.

1. An administrator will provide Ironic node(s) that are available for provisioning and a baremetal flavor.

openstack baremetal node list
openstack flavor list

1. Create a tenant VLAN network and subnet that uses the physical network the guest is attached to.

openstack network create --provider-network-type vlan --provider-physical-network datacentre my-tenant-net
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

1. Execute server create using the tenant network just created. This assumes disk images and keypairs are already created and available.

openstack server create --image a-baremetal-image --flavor baremetal --nic net-id={my-tenant-net uuid} --key-name my-keypair bm-instance

Python API¶

Networking-Ansible can be called directly via python API. This method does not require a running OpenStack, with neutron.

In this section, this use case will be exercised in a set of example commands to show how end users could import the networking-ansible API and call it to execute switch level network configuration.

1. In a python environment import the networking-ansible class.

   from networking_ansible.api import NetworkingAnsible
   

2. Instantiate the NetworkingAnsible class. This requires a dictionary that represents an Ansible Inventory data structure. This data structure could be read from a file or built dynamically by the code that is instantiating the class. This example will statically assign the data structure to a variable to show the expected data structure.

   inventory = {'all':
     {'hosts':
       {'examplehost':
         {'ansible_network_os': 'openswitch',
          'ansible_host': '5.6.7.8',
          'ansible_user': 'ansible',
          'ansible_ssh_pass': 'password',
         }
       }
     }
   }
   net_ans = NetworkingAnsible(inventory)
   

3. Call functions to configure the inventory.

   host = 'examplehost'
   port = 'port123'
   vlan_id = 37
   
   # create the VLAN
   net_ans.create_vlan(host, vlan_id)
   # configure a port in access mode on the VLAN
   net_ans.update_access_port(host, port, vlan_id)
   # shutdown the port
   net_ans.delete_port(host, port)
   # delete the VLAN
   net_ans.delete_vlan(host, vlan_id)
   

Contributing¶

If you would like to contribute to the development of OpenStack, you must follow the steps in this page:

http://docs.openstack.org/infra/manual/developers.html

If you already have a good understanding of how the system works and your OpenStack accounts are set up, you can skip to the development workflow section of this documentation to learn how changes to OpenStack should be submitted for review via the Gerrit tool:

http://docs.openstack.org/infra/manual/developers.html#development-workflow

Pull requests submitted through GitHub will be ignored.

Bugs should be filed on Storyboard, not GitHub:

https://storyboard.openstack.org/#!/project/openstack/networking-ansible

Provider Support¶

Networking-Ansible contains provider switch specific functionality in an Ansible role that enables specific hardware devices per provider switch added to this role. The openstack-ml2 Ansible role is stored in networking-ansible’s etc/ansible/roles directory. A provider switch will be refered to as just a provider for the remainder of this document.