path: root/doc/book-enea-nfv-access-getting-started/doc/device_configuration_and_provisioning.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter id="configuration_provision">
  <title>Device Configuration and Provisioning</title>

  <section id="man_config">
    <title>Manual Configuration</title>

    <para>This section describes how to connect to an instance of NFV Access
    installed on a specific uCPE device, and how to setup the virtual
    infrastructure manually.</para>

    <para><emphasis role="bold">How to add a uCPE device to the management
    system </emphasis></para>

     <para>Add the uCPE device running the NFV Access Run Time Platform to the
      management system: <literal>Devices -&gt; Manage -&gt; Add</literal>. Supply
      information about the uCPE device, and set the parameters that will be used 
      to connect to it.</para>

      <para>The relevant parameters are:</para>

    <itemizedlist>
      <listitem>
        <para>Type. The type of device to be added, i.e <literal>Enea
        universal uCPE</literal>.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <listitem>
        <para>Name. The name by which the device is referred to in the uCPE
        Manager.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <listitem>
        <para>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.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <listitem>
        <para>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.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <listitem>
        <para>SSH User Name. The user name for SSH connectivity. Default user
        is <literal>root</literal>.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <listitem>
        <para>SSH Password. Leave this blank.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <listitem>
        <para>Device Calls Home. This checkbox indicates the direction of
        device communications. In the Manual Configuration, leave this box
        blank. For more info about how to add a device please refer to <link
        linkend="adding_a_device">Zero Touch Provisioning, Adding a
        Device</link>.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <listitem>
        <para>Device ID. The unique instance ID of the device. This is what
        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.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section id="host_int_net_config">
    <title>Host Interfaces and Network Configuration</title>

    <para>The uCPE Manager can list network interfaces found on a device by
    selecting: <literal>Device</literal> -&gt;
    <literal>Configuration</literal> -&gt; <literal>OpenVSwitch
    </literal>-&gt; <literal>Host Interface Caps</literal>:</para>

    <figure>
      <title>Host Interface Caps</title>

      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/host_interface_caps.png"
                     scale="55" />
        </imageobject>
      </mediaobject>
    </figure>

    <para>Network interfaces can be set in three modes: DPDK, SR-IOV and
    PCI-Passthrough.</para>

    <section id="dpdk_interface">
      <title>DPDK Interface Type</title>

      <para>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:
      <literal>Configuration</literal> -&gt;<literal> OpenVSwitch
      </literal>-&gt; <literal>Host Interfaces</literal> -&gt;<literal>
      Add</literal>:</para>

      <figure>
        <title>DPDK Host Interface</title>

        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/dpdk_interface_type.png"
                       scale="90" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>For DPDK mode, the user must set following fields:</para>

      <itemizedlist>
        <listitem>
          <para>Source: PCI address of the physical interface</para>
        </listitem>

        <listitem>
          <para>Type: dpdk</para>
        </listitem>

        <listitem>
          <para>Networking-type: dpdk</para>
        </listitem>

        <listitem>
          <para>Dpdk-type: kernel module that allow user space access of
          physical interface</para>
        </listitem>
      </itemizedlist>

      <para>Create an OpenVSwitch bridge (<literal>ovsbr0</literal>) on the
      device that uses a DPDK interface, by selecting the uCPE device, then
      from the top toolbar selecting: <literal>Configuration</literal>-&gt;
      <literal>OpenVSwitch</literal> -&gt; <literal>Bridges</literal> -&gt;
      <literal>Add</literal>:</para>

      <figure>
        <title>OVS bridge</title>

        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/ovs_bridge.png"
                       scale="95" />
          </imageobject>
        </mediaobject>
      </figure>
    </section>

    <section id="sriov_interface_type">
      <title>SR-IOV Interface Type</title>

      <para>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: <literal>Configuration</literal> -&gt;<literal>
      OpenVSwitch </literal>-&gt; <literal>Host Interfaces
      </literal>-&gt;<literal> Add</literal>:</para>

      <para>For SR-IOV mode, the user must set following fields:</para>

      <itemizedlist>
        <listitem>
          <para>Source: PCI address of the physical interface</para>
        </listitem>

        <listitem>
          <para>Type: sr-iov</para>
        </listitem>

        <listitem>
          <para>Networking-type: srIov</para>
        </listitem>

        <listitem>
          <para>sriov-mode: adapter-pool</para>
        </listitem>

        <listitem>
          <para>sriov-num-vfs: the number of virtual functions to
          create</para>
        </listitem>
      </itemizedlist>

      <figure>
        <title>SR-IOV Interface Type</title>

        <mediaobject>
          <imageobject>
            <imagedata align="center"
                       fileref="images/sriov_interface_type.png" scale="90" />
          </imageobject>
        </mediaobject>
      </figure>
    </section>

    <section id="pci_interface_type">
      <title>PCI Passthrough Interface Type</title>

      <para>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.</para>
    </section>
  </section>

  <section id="zero_touch_prov">
    <title>Zero Touch Provisioning</title>

    <para>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.</para>

    <para>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.</para>

    <para>In order to create a static configuration supporting ZTP, the uCPE
    Manager user needs to identify the <literal>Device ID</literal> of the
    machine running NFV Access.</para>

    <para>During the automatic installation process when the
    <literal>Automatic install</literal> step is reached, enter the option
    menu <literal>Customize kernel parameters</literal> and set the
    <literal>uCPE Manager IP address</literal>. Please check <xref
    linkend="install_ena_stick" />, for how to set the uCPE Manager IP address
    at boot time. The Device ID will be listed in the installer under the
    <literal>Customize kernel parameters</literal> menu.</para>

    <para>With the address parameter set, run
    <literal>list_deviceID.sh</literal> after NFV Access is installed and
    booted, to get the device ID of the uCPE device.</para>

    <note>
      <para>It is possible to let NFV Access know the uCPE Manager IP address
      at run-time by setting <literal>vcpemgr=&lt;IP&gt;</literal> as a kernel
      boot parameter in the grub configuration file. Reboot is required after
      this update.</para>

      <para>This step needs to be done each time the uCPE Manager host changes
      its IP address.</para>
    </note>

    <para>An offline configuration can be prepared in advance for the uCPE
    Manager to setup the infrastructure on the device.</para>

    <section id="adding_a_device">
      <title>Adding a Device</title>

      <para>The uCPE Manager must be configured to bring the uCPE device under
      management. This is done by selecting <literal>Device Calls
      Home</literal> checkbox when adding a device. When Device Calls Home
      checkbox 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.</para>

      <para>For more info about how to add a device please refer to <link
      linkend="man_config">Manual Configuration</link>.</para>
    </section>

    <section id="offline_configuration">
      <title>Offline Configuration</title>

      <para>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<literal> Device ID</literal> can be specified - this ID
      uniquely identifies the device to be initialized.</para>

      <para>Use the GUI (shown below) launched by the <literal>Applications
      -&gt; Offline Config -&gt; Add</literal> menu:</para>

      <figure>
        <title>Onboard New VNF</title>

        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/offline_config.png"
                       scale="80" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>Specify the exact value of the <literal>Device ID</literal> in the
      required field. This will tag the device needed for the initial
      configuration provided by the offline configuration store. Choose
      <literal>Merge</literal> as the Default Upload Method if you do not want
      any boot configuration set on the device, to be wiped out. Selecting
      <literal>Replace</literal> will set the entire device configuration to
      match values in the offline configuration.</para>

      <para>After creating the Offline Config Store, access the device through
      <literal> Applications -&gt; offline config -&gt; Config App</literal>
      and provision it with the required initial configuration. This operation
      mirrors what happens during regular offline configuration.</para>

      <para>Now that the store has been provisioned successfully, it is ready
      to send this configuration to the device when it first comes
      online.</para>
    </section>

    <section id="initial_communications">
      <title>Initial Communications</title>

      <para>There are two possible paths to this process, depending upon
      whether or not NETCONF Call-Home functionality is used:</para>

      <orderedlist>
        <listitem>
          <para>If Call-Home is not enabled/supported, the uCPE Manager
          creates a SSH session to the device over the port configured through
          the <literal>Add Device </literal> process (default 830). It then
          initiates NETCONF communications over this session.</para>
        </listitem>

        <listitem>
          <para>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.</para>
        </listitem>
      </orderedlist>

      <para>Once communications with the device have been established, the
      Device Manager will try and connect to it.</para>
    </section>
  </section>

  <section id="vnf_management">
    <title>VNF Management</title>

    <para>As the acting vnf manager, the uCPE Manager is responsible for
    handling the life-cycles of VNFs that are instantiated and run on the
    various uCPE devices. The vnf manager module is written so as to be able
    to manage multiple VNF types. Along with it is provided a generic
    infrastructure to allow the end-user to introduce new VNF types
    dynamically into the system. This allows for third-party VNFs to be added
    over time to an existing network infrastructure without having to perform
    an expensive upgrade of the vnf manager itself.</para>

    <para>The process of VNF Onboarding consists of providing the system with
    sufficient information and resources related to the VNF such that it can
    instantiate a flavour of the VNF on the uCPE device, configure and scale
    it as appropriate, heal and upgrade it when necessary and tear it down at
    the right moment.</para>

    <para>The vnf manager subsystem in the uCPE Manager inserts a menu item in
    the toolbar, called <literal>VNF</literal> as shown in the screen-shot
    below.</para>

    <figure>
      <title>VNF Management</title>

      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/vnf_management.png"
                     scale="80" />
        </imageobject>
      </mediaobject>
    </figure>

    <para>Selecting this menu item gives you the following options:</para>

    <itemizedlist>
      <listitem>
        <para><literal>Descriptors</literal>: Choosing this option lets you
        manage the VNF Descriptors catalog. The vnf manager maintains a
        catalog of all VNFs that can be instantiated and managed by the
        system. Before you can use a new VNF, you need to onboard it into the
        catalog.</para>
      </listitem>

      <listitem>
        <para><literal>Instances</literal>: Choosing this option lets you
        instantiate (or destroy) VNFs on a given uCPE device.</para>
      </listitem>

      <listitem>
        <para><literal>Events</literal>: Choosing this option displays all the
        events that are related to VNF lifecycle management. Whenever a VNF
        state changes (i.e. it is
        created/destroyed/stopped/started/paused/resumed), a state change
        event is generated in the uCPE Manager. The screen shown when this
        option is chosen displays all events in the system, filtered to show
        only VNF state change notifications.</para>
      </listitem>
    </itemizedlist>

    <section id="onboarding_a_vnf">
      <title>Onboarding a VNF</title>

      <para>The VNF descriptor catalog table provides a button that allows you
      to onboard a new (third-party) VNF into the catalog.</para>

      <figure>
        <title>Onboard New VNF</title>

        <mediaobject>
          <imageobject>
            <imagedata align="center"
                       fileref="images/onboarding_a_new_vnf.png" scale="70" />
          </imageobject>
        </mediaobject>
      </figure>

      <section id="onboarding_a_vnf_wizard">
        <title>Onboarding a VNF VM Image using the Onboarding Wizard</title>

        <para><emphasis role="bold">How to onboard a VNF into the uCPE Manager
        using the Onboarding Wizard</emphasis></para>

        <orderedlist>
          <listitem>
            <para>Make sure the uCPE device is added and placed on the map in
            the uCPE Manager.</para>
          </listitem>

          <listitem>
            <para>Select from the top toolbar <literal>VNF</literal> -&gt;
            <literal>Descriptors.</literal></para>
          </listitem>

          <listitem>
            <para>Click the <literal>On-board</literal> button.</para>
          </listitem>

          <listitem>
            <para>When prompted by the following UI, make sure the <literal>VM
            Image</literal> radio button is selected.</para>
          </listitem>
        </orderedlist>

        <para>If you click the <literal>VM Image</literal> radio button at the
        top of the onboarding screen, you will get a pop-up containing fields
        which you can fill, suppling the necessary information about the VNF.
        After providing the information and pressing the onboard button, the
        uCPE Manager will create the VNF package and onboard it.</para>

        <figure>
          <title>Onboard a VNF using the Wizard</title>

          <mediaobject>
            <imageobject>
              <imagedata align="center"
                         fileref="images/onboard_a_vnf_image.png" scale="70" />
            </imageobject>
          </mediaobject>
        </figure>

        <para><emphasis role="bold">Main fields</emphasis></para>

        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">VM Image File.</emphasis> This is the
            Virtual Machine image file for the VNF itself. Typically, it is a
            QCOW image. Press <literal>Choose File</literal> and select the
            image to be uploaded.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Image Format</emphasis>. Select the
            format which matches the image file.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">VNF Type Name.</emphasis> This is the
            name that will be used to identify this VNF. It will be shown in
            the VNF tables.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Description.</emphasis> This field
            contains any description you want to provide. It is only displayed
            in the GUI tables in the uCPE Manager.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Version</emphasis>. This is the
            version of the current VNF that you are hosting. It's used to
            distinguish this VNF from other versions of the same type.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Memory in MB.</emphasis> This is the
            amount of memory (in megabytes) that will be provided to this type
            of VNF when it is instantiated. To determine the value for this
            field, consult the VNF vendor.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Num of CPUs.</emphasis> The number of
            CPUs that will be dedicated to an instance of this VNF when
            created. To determine the value for this field, consult the VNF
            vendor.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Storage in GB.</emphasis> How much
            disk space to provide an instance of this VNF. To determine the
            value for this field, consult the VNF vendor.</para>
          </listitem>
        </itemizedlist>

        <para><emphasis role="bold">Interfaces Tab</emphasis></para>

        <figure>
          <title>Interfaces Table</title>

          <mediaobject>
            <imageobject>
              <imagedata align="center" fileref="images/interfaces_table.png"
                         scale="70" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>Click on the <literal>Interfaces</literal> tab to show the
        Interfaces table.</para>

        <para>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 by the uCPE Manager
        only.</para>

        <para><emphasis role="bold">Cloud Init Tab</emphasis></para>

        <para>Click the <literal>Clout Init</literal> tab to provide the
        Clout-Init configuration.</para>

        <figure>
          <title>Cloud-Init Tab</title>

          <mediaobject>
            <imageobject>
              <imagedata align="center" fileref="images/cloud_init_tab.png"
                         scale="70" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>As shown in the picture above, there are three fields that need
        to be populated:</para>

        <orderedlist>
          <listitem>
            <para><emphasis role="bold">Cloud-Init
            Datasource</emphasis></para>

            <para>To onboard the VNF you must specify the<literal> Cloud-Init
            Datasource</literal> that the VNF uses. You can get this
            information from the VNF Vendor. Choose one of the following
            methods to specify the datasource:</para>

            <itemizedlist>
              <listitem>
                <para><emphasis role="bold">None</emphasis>. If there is no
                datasource.</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">ConfigDrive</emphasis>. This
                method allows you to provide any number of content-data files
                containing Cloud-Init data.</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">NoCloud</emphasis>. This is a
                simpler method that uses only one cloud init file
                (User-Data).</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">ISO</emphasis>. Pre-cooked
                cloud-init image. This image must be created by the user
                according to VNF requirements.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Cloud-Init Disk Type</emphasis></para>

            <para>The <literal>Cloud-Init Disk Type </literal>field must be
            set to either <literal>Disk</literal>, or
            <literal>CD-ROM</literal>, depending on what the VNF requires. You
            can get this information from the VNF Vendor.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Content Files Table</emphasis></para>

            <para>The <literal>Content Files Table </literal>is ONLY used if
            you choose <literal>ConfigDrive</literal> as the Cloud-Init
            Datasource. For each content file added, you must provide a
            <literal>Path</literal>. When a user uses the uCPE Manager to
            create an instance of one of these VNFs, they will be prompted to
            provide a data file for each entry in this table. Each type of VNF
            will require different cloud-init files, e.g.: a license
            file.</para>
          </listitem>
        </orderedlist>

        <figure>
          <title>Content Files Table example</title>

          <mediaobject>
            <imageobject>
              <imagedata align="center"
                         fileref="images/content_files_table.png" scale="70" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>Consult with the VNF vendor to determine what is required for
        the VNF you are onboarding.</para>

        <para><emphasis role="bold">Properties Tab</emphasis></para>

        <para>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. These property
        names are well known to the uCPE NFV Access software, and more will be
        added in future versions. You will need to consult with the VNF Vendor
        or ENEA support for values needed by specific VNFs.</para>

        <figure>
          <title>Properties Tab</title>

          <mediaobject>
            <imageobject>
              <imagedata align="center" fileref="images/properties_tab.png"
                         scale="70" />
            </imageobject>
          </mediaobject>
        </figure>

        <para><emphasis role="bold">Property Values</emphasis></para>

        <para><literal>numHugePages</literal> defines the number of huge
        memory pages the VNF uses (for DPDK).</para>
      </section>
    </section>

    <section id="instantiating_a_vnf">
      <title>Instantiating a VNF</title>

      <para>Once the VNF has been onboarded, you can instantiate a VNF on a
      specific uCPE device.</para>

      <para><emphasis role="bold">How to instantiate a VNF using the
      Wizard</emphasis></para>

      <orderedlist>
        <listitem>
          <para>Make sure the uCPE device is added and placed on the map in
          the uCPE Manager.</para>
        </listitem>

        <listitem>
          <para>Make sure the VNF has been onboarded into the uCPE
          Manager.</para>
        </listitem>

        <listitem>
          <para>Select from the top toolbar <literal>VNF</literal> -&gt;
          <literal>Instances</literal></para>
        </listitem>

        <listitem>
          <para>Click the <literal>Add</literal> button.</para>
        </listitem>

        <listitem>
          <para>When prompted by the following UI, fill the required
          fields.</para>
        </listitem>
      </orderedlist>

      <figure>
        <title>Instantiating a VNF</title>

        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/instantiate_a_vnf.png"
                       scale="70" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>There are a number of parameters to be supplied before the VNF can
      be instantiated:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Name</emphasis>. The name of the
          VNF.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">VNF Type</emphasis>. The name of the
          onboarded VNF. In this case <literal>VProbe</literal> VNF.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Flavour</emphasis>. The flavour of VNF
          (as specified in the descriptor) you would like to
          instantiate.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Device</emphasis>. The uCPE device on which
          to instantiate a VNF, i.e. the uCPE device that will run this
          VNF.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Auto-start</emphasis>. If checked, the
          VNF will be stopped and started when unreachable. When the uCPE Device reports that it has lost connection to the VNF, the uCPE Manager
          will ask it to terminate the VM and then start it up again. If
          unchecked, only a <literal>Disconnected</literal> notification will
          appear in the uCPE Manager.</para>
        </listitem>
      </itemizedlist>

      <para>Hitting the <literal>Create</literal> button will cause the VNF to
      be instantiated and run on the specified uCPE device.</para>

      <para>Selecting the<literal> VNF -&gt; Events</literal> menu will show
      that the VNF was created and a connection was established:</para>

      <figure>
        <title>VNF Events menu</title>

        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/instantiate_a_vnf4.png"
                       scale="70" />
          </imageobject>
        </mediaobject>
      </figure>
    </section>
  </section>
</chapter>