From 64180464e41ba5bca69c79e1c387df0dfbb44fb7 Mon Sep 17 00:00:00 2001 From: Sona Sarmadi Date: Thu, 3 Oct 2019 13:53:40 +0200 Subject: GettingStarted: update Device Conf & Prov Update ch "4.3 - Device Configuration and Provisioning" - Remove Windows platform - Re-structure some chapters - Move In-band Management under New chapter "Configure Bridges" - Remove all screeshots except "Host Interfaces Caps" and make sure that image is up-to-date. Change-Id: I54df140169506c180962d9099db4a56bf1e2ccb7 Signed-off-by: Sona Sarmadi --- .../doc/getting_started_ucpe_manager.xml | 634 ++++++++++++--------- .../doc/images/host_interface_caps.png | Bin 15222 -> 32885 bytes .../doc/in_band_management.xml | 175 ------ 3 files changed, 349 insertions(+), 460 deletions(-) delete mode 100644 doc/book-enea-nfv-access-getting-started/doc/in_band_management.xml diff --git a/doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml b/doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml index 935c9df..5d980fc 100644 --- a/doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml +++ b/doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml @@ -2,20 +2,20 @@ Getting Started with Enea uCPE Manager -
+
Prerequisites - Listed below are the main generic prerequisites required so that - uCPE Manager can be deployed on your host platform: + Listed below are the main generic prerequisites required so that the + uCPE Manager can be deployed on the host platform: - A device that is supported by NFV Access. + A device that supports NFV Access. - A machine running either Windows or CentOS with network access - to the physical device. + A machine running CentOS with network access to the physical + device.
@@ -23,35 +23,23 @@
Install the Enea uCPE Manager - Unpack the uCPE Manager and install it by following the instructions + Unpack the uCPE Manager and install it following the instructions provided within the release archive: [unpacked_folder]/dist/README. - There are a few things to consider during the installation phase, as + There are things to consider during the installation phase, as there are a few steps where user input is required. In most cases, the default values should be used. - For demo purposes, use the internal PostgreSQL database (which - defaults to Y), and not the machine as part of a cluster (which defaults - to N). Installing on a Windows machine, will require the user to follow - the Windows password policies when defining the password for the ucpemanager service. A good example for an - acceptable password would - be:_1ucpe#2manager!3_. - - Check that the Windows or CentOS machine where the uCPE Manager is - installed has the firewall disabled. To disable the firewall, if using - Windows 10, go to the Control Panel, then inside Network & - Internet and Firewall & Network - Protection, disable the firewall for "Domain network" and - "Private network". + Check that the CentOS machine where the uCPE Manager is installed + has the firewall disabled. Verify that the installation has succeeded: Point your browser to the server machine running the uCPE - Manager: https://localhost. + Manager. @@ -73,10 +61,14 @@ infrastructure.
- Manual Addition + Direct Connection + + When using this mechanism, the uCPE Manager will periodically poll + the uCPE device, using a specified IP address as the destination, attempting + to establish a management connection. Add the uCPE device running the NFV Access Run Time Platform to - the management system: Devices -> Manage -> + the management system by selecting Devices -> Manage -> Add. Supply information about the uCPE device, and set the parameters that will be used to connect to it. @@ -85,7 +77,7 @@ Type. The type of device to be added, i.e Enea - universal uCPE. + universal CPE. @@ -98,25 +90,19 @@ - IP Address. IP address of the device. If a device is - installed under a local/private network and not directly visible - to the uCPE Manager machine, the Gateway IP of the private network - must be used. + IP Address. IP address of the device. - SSH Port. The NETCONF Port used for communications. This is - a relevant parameter if the standard NETCONF SSH (i.e. not - Call-Home) is being used. Default is set to 830. + SSH Port. The NETCONF Port used for communications. - SSH User Name. The user name for SSH connectivity. Default - user is root. + SSH User Name. The user name for SSH connectivity. @@ -136,8 +122,8 @@ - Device ID. The unique instance ID of the device. This is - what links a device to its day-0 configuration (stored in the + Device ID. The unique instance ID of the device. This links + a device to its day-0 configuration (stored in the offline configuration system). It is a required field if you want to perform Zero-Touch Provisioning. @@ -145,22 +131,29 @@
- Using Call-Home - - The uCPE Manager must be configured to bring the uCPE device - under management. This is done by selecting the Device Calls - Home checkbox when adding a device. When Device Calls Home - is checked, the device will initiate a connection by opening a socket - to the uCPE Manager for NETCONF traffic (over SSH), while the uCPE - Manager waits for device connection. + Device Call Home Connection + + Follow the same steps as described in previous section, making sure + that the Device Calls Home checkbox is selected. + + When using this mechanism, the device will initiate a connection + to the uCPE Manager for NETCONF traffic (over SSH), while the uCPE + Manager waits for a device connection. Make sure the uCPE Manager IP + address has been configured on the device. For more information please see section + Installing Enea NFV Access for more details.
- Prepare uCPE device for VNF onboarding + Configure NFV Infrastructure + + Once a management connection with the uCPE device has been established + by using any of the supported methods, the virtualization networking + infrastructure can be configured either manually or by using Zero Touch + Provisioning. The uCPE Manager can list network interfaces found on a device by - selecting: Device -> + selecting the uCPE device first and then selecting Configuration -> OpenVSwitch -> Host Interface Caps: @@ -175,234 +168,301 @@ - Network interfaces can be set in three modes: DPDK, SR-IOV and - PCI-Passthrough. + Available network interfaces can be added to the management + system, for use by the networking virtualization infrastructure. -
- DPDK Interface Type +
+ Manual Configuration - Configuring a physical interface in DPDK mode will require a - DPDK-based application (e.g. OVS-DPDK) in order to access and use the - interface. An interface set as DPDK can be attached to an OVS-DPDK - bridge. Select the uCPE device, then from the top toolbar select: - Configuration -> OpenVSwitch - -> Host Interfaces -> - Add: + For Manual Configuration of uCPE networking, select the uCPE device + first and then Configuration -> OpenVSwitch. + In the Host Interfaces Caps, one can find a list of available network + interfaces and their capabilities. -
- DPDK Host Interface +
+ Configuring Interfaces - - - - - -
+ DPDK Interface Type - For DPDK mode, the user must set following fields: + Configuring a physical interface in DPDK mode will require a + DPDK-based application (e.g. OVS-DPDK) in order to access and use + the interface. An interface set as the DPDK can be attached to an + OVS-DPDK bridge. + + Select the uCPE device, then from the top toolbar + select Configuration -> OpenVSwitch + -> Host Interfaces -> + Add. - - - Source: PCI address of the physical interface - + For DPDK mode, the user must set values for the following fields: - - Type: dpdk - + + + Source: the PCI address of the physical interface. + - - Networking-type: dpdk - + + Type: dpdk + - - Dpdk-type: kernel module that allow user space access of - physical interface - - + + Networking-type: dpdk + - Create an OpenVSwitch bridge (ovsbr0) on the - device that uses a DPDK interface, by selecting the uCPE device, then - from the top toolbar selecting: Configuration-> - OpenVSwitch -> Bridges -> - Add: + + Dpdk-type: the kernel module that allows user space access to the + physical interface. + + -
- OVS bridge + Create an OpenVSwitch bridge (ovsbr0) on + the device that uses a DPDK interface, by selecting the uCPE device, + then from the top toolbar selecting Configuration + -> OpenVSwitch -> Bridges -> + Add. - - - - - -
-
+ SR-IOV Interface Type -
- SR-IOV Interface Type + SR-IOV mode will create a number of virtual functions on the host + which can be used to route traffic to VMs. Select the uCPE device, + then from the top toolbar select Configuration + -> OpenVSwitch -> Host Interfaces + -> Add. - SR-IOV mode will create a number of virtual functions on host - that can be used to route traffic to VMs. Select the uCPE device, then - from the top toolbar select: Configuration - -> OpenVSwitch -> Host Interfaces - -> Add: + For SR-IOV mode, the user must set values for the following fields: - For SR-IOV mode, the user must set following fields: + + + Source: the PCI address of the physical interface. + - - - Source: PCI address of the physical interface - + + Type: sr-iov + - - Type: sr-iov - + + Networking-type: srIov + - - Networking-type: srIov - + + sriov-mode: adapter-pool + - - sriov-mode: adapter-pool - + + sriov-num-vfs: the number of virtual functions to + create. + + - - sriov-num-vfs: the number of virtual functions to - create - - + PCI Passthrough Interface + Type -
- SR-IOV Interface Type + For the PCI Passthrough a user does not have to configure a + physical interface, instead simply select the PCI address and + connect it to a virtual port when the VNF instantiation step is reached. +
- - - - - - -
+
+ Configuring Bridges -
- PCI Passthrough Interface Type + In-band Management - For PCI Passthrough the user does not have to configure a - physical interface, instead simply select the PCI address and connect - it to a virtual port at the VNF instantiation step. -
-
+ In-band Management refers to a model where both the data plane + and control plane flow over the same network path. -
- Zero Touch Provisioning - - Zero-Touch Provisioning (ZTP) is an alternative to Manual - configuration. ZTP refers to the process by which, when a device starts - up for the first time, its initial configuration is pushed down by an - external management system, so that it is setup for proper operation - without additional manual intervention by an operator. - - A variety of operations can occur as part of ZTP such as initial - device setup, configuration of managed objects, etc. The goal is to set - up a device to the maximum possible extent without forcing an operator - to be physically present (initially) to manage the device. - - In order to create a static configuration supporting ZTP, the uCPE - Manager user needs to identify the Device ID of the - machine running NFV Access. - - During the automatic installation process when the - Automatic install step is reached, enter the option - menu Customize kernel parameters and set the - uCPE Manager IP address. Please check , for how to set the uCPE Manager IP - address at boot time. The Device ID will be listed in the installer - under the Customize kernel parameters menu. - - With the address parameter set, run - list_deviceID.sh after NFV Access is installed and - booted, to get the device ID of the uCPE device. - - - It is possible to let NFV Access know the uCPE Manager IP - address at run-time by setting vcpemgr=<IP> - as a kernel boot parameter in the grub configuration file. Reboot is - required after this update. - - This step needs to be done each time the uCPE Manager host - changes its IP address. - - - An offline configuration can be prepared in advance for the uCPE - Manager to setup the infrastructure on the device. - -
- Offline Configuration - - The Offline Configuration subsystem is used to pre-populate a - configuration for a device that will be brought under management at a - future point in time. When creating an offline configuration store, an - optional Device ID can be specified - this ID - uniquely identifies the device to be initialized. - - Use the GUI (shown below) launched by the Applications - -> Offline Config -> Add menu: + In some situations, In-band Management is the only option + available to both control and configure the uCPE device, while also + allowing for data-path traffic to pass over the same physical + interface. -
- Onboard New VNF + The main requirement in order to use this solution is to have all + traffic pass through a defined WAN physical port. - - - - - -
+ Three types of traffic are mentioned hereafter: - Specify the exact value of the Device ID in - the required field. This will tag the device needed for the initial - configuration provided by the offline configuration store. Choose - Merge as the Default Upload Method if you do not - want any boot configuration set on the device, to be wiped out. - Selecting Replace will set the entire device - configuration to match values in the offline configuration. - - After creating the Offline Config Store, access the device - through Applications -> offline config -> Config - App and provision it with the required initial - configuration. This operation mirrors what happens during regular - offline configuration. - - Now that the store has been provisioned successfully, it is - ready to send this configuration to the device when it first comes - online. -
+ + + Device management. Part of the device configuration done by the + uCPE Manager. + + + + VNF(s) configuration. Enabling or disabling features of a + VNF. E.g. enabling/disabling the firewall or VPN setup. + -
- Initial Communications + + Data-path. All other traffic that is not used in the + control plane and needs to reach a LAN network. + + - There are two possible paths to this process, depending upon - whether or not NETCONF Call-Home functionality is used: + + For use-cases where latency is very important, it is + recommended to use out-of-band management with a dedicated + physical interface for the data-path. + + + The solution provided by Enea for In-band management is based + upon Open vSwitch bridges which control all traffic passing through + the WAN physical port. The NFV Access platform will assume the activated + connection with the uCPE Manager should be used for In-band management. + The physical port used by the active connection will be attached to the + In-band management WAN bridge. Communication with the uCPE Manager + should not be affected, it is reestablished automatically after In-band management + activation. + + All network traffic, with the exception of any received from + the uCPE Manager, will be sent to the VNF or dropped if there + is no VNF instantiated on the uCPE device. The VNF connected to the + WAN bridge must be configured for In-band management since traffic + from the VNF manager and data-path will be sent to only one port + (WAN) of the VNF. + + + Only one VNF must be connected to the In-band management WAN + bridge. + + + + Setup Prerequisites + + + + + + + + + WAN port + + The physical port supported by DPDK. + + + + Dynamic IP on WAN port + + The DHCP server configured to distribute the same IP address + for the same MAC. + + + + uCPE Manager + + The uCPE Manager IP address must be public (accessible + for the uCPE device) and static. + + + +
+ + How to activate In-band Management from + the uCPE Manager + + + + Select the uCPE device. + - - - If Call-Home is not enabled/supported, the uCPE Manager - creates a SSH session to the device over the port configured - through the Add Device process (default 830). - It then initiates NETCONF communications over this session. - + + Select Configuration. + - - If the device uses Call-Home, it creates a socket connection - to port 4334 on the management system which runs the uCPE Manager. - The uCPE Manager then creates a SSH session over this socket and - initiates NETCONF communications as a client. - - + + Click OpenvSwitch. + + + + Select the Bridges option, then click Add. + + + + + In-band management WAN DPDK bridge configuration + + + + name. Provide a name for the WAN bridge e.g. + "ibm-wan-br". + ovs-bridge-type. dpdkWan + mgmt-address. IPv4 (add the IP address of the uCPE Manager machine). + mgmt-port. 4334 + + + The connection between the uCPE device and uCPE Manager will + be recreated and all traffic will pass through the new bridge + (ibm-wan-br). The WAN port of the very first instantiated VNF must + be connected to the ibm-wan-br bridge and it + should receive the same IP address as the WAN interfaces of the uCPE device. + +
+ Enea In-band Management solution + + + + + + +
+ + The VNF can be reached on the same IP address as the uCPE + device, e.g. https://<WAN_IP> if a HTTP + server is present on that VNF. + + + The In-band management bridge must be recreated each time + the uCPE Manager IP is changed. + +
+
- Once communications with the device have been established, the - Device Manager will try and connect to it. +
+ Zero Touch Provisioning + + Zero-Touch Provisioning (ZTP) refers to the process of when a device + starts up for the first time and its initial configuration is pushed down + by an external management system, so that it is setup for proper + operation without additional manual intervention by an + operator. ZTP is an alternative to Manual configuration. + + A variety of operations can occur as part of ZTP such as initial + device setup, configuration of managed objects, etc. The goal is to + set up a device to the maximum possible extent without forcing an + operator to be physically present (initially) to manage the + device. + + An offline configuration can be prepared in advance for the uCPE + Manager to setup the infrastructure on the device. + +
+ Offline Configuration + + The Offline Configuration subsystem is used to pre-populate a + configuration for a device that will be brought under management at + a future point in time. + + When creating an offline configuration store a + Device ID can be specified. This ID + uniquely identifies the device to be initialized. + + From the top toolbar menu select Applications -> + Offline Config -> Add. + Specify the exact value of the Device ID in the + required field. This will tag the device needed for + the initial configuration provided by the + offline configuration store. Choose Merge as the + "Default Upload Method" if you do not want any boot configuration set + on the device, to be wiped out. Selecting Replace + will set the entire device configuration to match values in the + offline configuration. + + After creating the Offline Config Store, access the device + through Applications -> offline config + -> Config App and provision it with the required initial + configuration. This operation mirrors what happens during regular + offline configuration. +
@@ -410,10 +470,9 @@
VNF Management - The Enea uCPE Manager is responsible for - onboarding, configuring (e.g. CloudInit) and ensuring life cycle - management of VNFs that are instantiated and run on the various uCPE - devices. + The Enea uCPE Manager is responsible for onboarding, configuring + (e.g. CloudInit) and ensuring life cycle management of VNFs that are + instantiated and run on the various uCPE devices.
Onboarding a VNF @@ -423,8 +482,8 @@ uCPE devices). This is accomplished using the Enea uCPE Manager Onboarding graphical user interface. - Typically, the Getting Started Guide of a VNF contains all necessary - information needed to onboard a VNF. + Typically, the Getting Started Guide of a VNF contains all + necessary information needed to onboard a VNF.
Retrieving Artifacts @@ -438,7 +497,8 @@ - Procure any VNF-specific files from the VNF vendor, e.g. license file. + Procure any VNF-specific files from the VNF vendor, e.g. + license file. There are no standard ways of managing VNF licenses, @@ -477,11 +537,13 @@ This decides what resources the VNF is configured for, along with networking and day zero configurations. - Generally, the Getting Started Guide for the VNF - provides guidelines for resource allocation, but since - performance is dependent on hardware capacity, the right - resource allocation for deployment is determined - through benchmarking. + + Generally, the Getting Started Guide for the VNF + provides guidelines for resource allocation, but since + performance is dependent on hardware capacity, the right + resource allocation for deployment is determined through + benchmarking. + @@ -533,22 +595,22 @@ When prompted by the UI, make sure the VM - Image radio button at the top of the onboarding - screen is selected, it will trigger a popup menu. + Image radio button at the top of the onboarding screen + is selected, it will trigger a popup menu. - This menu contains data fields where both necessary and optional - information about the VNF can be supplied. After doing so, press - the onboard button, the uCPE Manager will create the VNF package and onboard it. + This menu contains data fields where both necessary and optional + information about the VNF can be supplied. After doing so, press the + onboard button, the uCPE Manager will create the VNF package and + onboard it.
Onboard a VNF - @@ -559,9 +621,9 @@ VM Image File. This is the - Virtual Machine image file for the VNF. Typically, it is a - QCOW image. Press Choose File and select the - image you wish to upload. + Virtual Machine image file for the VNF. Typically, it is a QCOW + image. Press Choose File and select the image + you wish to upload. @@ -577,8 +639,8 @@ Description. This field - contains any description provided and is only displayed - in the GUI tables in the uCPE Manager. + contains any description provided and is only displayed in the GUI + tables in the uCPE Manager. @@ -616,13 +678,14 @@ This table will contain the interfaces required by this VNF to be configured, when creating an instance. Consult the VNF vendor to determine which and how many are required. Each interface requires a - name, and optionally a description, used only by the uCPE Manager. + name, and optionally a description, used only by the uCPE + Manager. Cloud Init Tab Click the Clout Init tab to provide the - Clout-Init configuration. There are three fields that need to be - populated: + Clout-Init configuration. There are three fields that need to be + populated: @@ -630,9 +693,9 @@ Datasource To onboard a VNF you must specify the Cloud-Init - Datasource that the VNF uses. This - information is procured from the VNF Vendor. Choose one of the following - methods to specify the datasource: + Datasource that the VNF uses. This information is + procured from the VNF Vendor. Choose one of the following methods + to specify the datasource: @@ -690,10 +753,10 @@ In this table, you can enter values for properties that will be used during instantiation of the VNF. The values will augment the - default values in the Domain.XML file used - by libvirt/virsh (running in NFV Access) when - creating an instance of the VNF. Consult with the VNF Vendor - or ENEA support for values needed by specific VNFs. + default values in the Domain.XML file used by + libvirt/virsh (running in NFV Access) when creating + an instance of the VNF. Consult with the VNF Vendor or ENEA support + for values needed by specific VNFs. Property Values @@ -706,9 +769,9 @@ Instantiating a VNF When a VNF is onboarded and available in the VNF catalog, it can - be instantiated on connected uCPE devices. The configurations - provided when the VNF is onboarded, serve as a template for instantiation. - Follow the instructions below to instantiate a VNF: + be instantiated on connected uCPE devices. The configurations provided + when the VNF is onboarded, serve as a template for instantiation. Follow + the instructions below to instantiate a VNF: @@ -757,8 +820,8 @@ - Add VNF-specific configuration data by uploading a Cloud-Init file - (when the Cloud-Init is used). + Add VNF-specific configuration data by uploading a Cloud-Init + file (when the Cloud-Init is used). @@ -766,8 +829,8 @@ - Hit the Create button to deploy the - VNF and run it on the specified uCPE device. + Hit the Create button to deploy the VNF and + run it on the specified uCPE device. @@ -785,8 +848,9 @@ - SSH to the uCPE device from the Enea uCPE Manager (Device->SSH) - with default user and password: root. + SSH to the uCPE device from the Enea uCPE Manager + (Device->SSH) with default user and password: + root. diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/host_interface_caps.png b/doc/book-enea-nfv-access-getting-started/doc/images/host_interface_caps.png index 5adb5c2..42188a5 100755 Binary files a/doc/book-enea-nfv-access-getting-started/doc/images/host_interface_caps.png and b/doc/book-enea-nfv-access-getting-started/doc/images/host_interface_caps.png differ diff --git a/doc/book-enea-nfv-access-getting-started/doc/in_band_management.xml b/doc/book-enea-nfv-access-getting-started/doc/in_band_management.xml deleted file mode 100644 index 6f5cdb1..0000000 --- a/doc/book-enea-nfv-access-getting-started/doc/in_band_management.xml +++ /dev/null @@ -1,175 +0,0 @@ - - - - In-band Management - - In-band Management refers to a model where both the data plane and - control plane flow over the same network path. - - In some situations, In-band Management is the only option available to - both control and configure the uCPE device, while also allowing for data-path - traffic to pass over the same physical interface. - - The main requirement for this use case solution is to have all traffic - pass through a defined WAN physical port. - - Three types of traffic are mentioned: - - - - Device management - e.g.: device configuration - done by the uCPE Manager. - - - - VNF(s) configuration - enabling or disabling features of a VNF. - E.g. enabling/disabling the firewall or VPN setup. - - - - Data-path - all the other traffic that is not used in the control - plane and needs to reach a LAN network. - - - - - For use-cases where latency is very important, it is recommended to - use out-of-band management with a dedicated physical interface for the - data-path. - - - The solution provided by Enea for In-band management is based upon - Open vSwitch bridges which control all traffic passing through the WAN - physical port. Note that the NFV Access platform will assume that the - activated connection with the uCPE Manager should be used for In-band - management. The physical port used by the active connection will be attached - to the In-band management WAN bridge. Communication with the uCPE Manager - should not be affected, it is reestablished automatically after In-band - management activation. - - All network traffic, with the exception of any received from the uCPE - Manager, will be sent towards the VNF or dropped if there is no VNF - instantiated on the uCPE device. The VNF connected to the WAN bridge - must be configured for In-band management since traffic from the VNF manager - and data-path will be sent to only to one port (WAN) of the VNF. - - - Only one VNF must be connected to the In-band management WAN bridge. - - - - Setup Prerequisites - - - - - - - - - WAN port - - Physical port supported by DPDK - - - - Dynamic IP on WAN port - - DHCP server configured to distribute same IP address for same - MAC - - - - uCPE Manager - - uCPE Manager IP address must be public (accessible for the uCPE device) - and static - - - -
- - How to activate In-band Management from the uCPE - Manager - - - - Select the uCPE device. - - - - Select Configuration. - - - - Click OpenvSwitch. - - - - Select the Bridges option, then click Add. - - - - - In-band management WAN DPDK bridge configuration - - - - - - - - - name - - Provide a name for the WAN bridge e.g. "ibm-wan-br" - - - - ovs-bridge-type - - dpdkWan - - - - mgmt-address - - IPv4 (add IP address of uCPE Manager machine) - - - - mgmt-port - - 4334 - - - -
- - The connection between the uCPE device and uCPE Manager will be recreated - and all traffic will pass through the new bridge (ibm-wan-br). The user - should be able to continue device configuration. The WAN port of the very - first instantiated VNF must be connected to ibm-wan-br and it should receive - the same IP address as the WAN interfaces of the uCPE device. - -
- Enea In-band Management solution - - - - - - -
- - The VNF can be reached on the same IP address as the uCPE device, e.g. - https://<WAN_IP> if a HTTP server is present - on that VNF. - - - The In-band management bridge must be recreated each time the uCPE - Manager IP is changed. - - -- cgit v1.2.3-54-g00ecf