diff options
3 files changed, 773 insertions, 777 deletions
diff --git a/doc/book-enea-nfv-access-getting-started/doc/book.xml b/doc/book-enea-nfv-access-getting-started/doc/book.xml index abce2c2..9289fe8 100644 --- a/doc/book-enea-nfv-access-getting-started/doc/book.xml +++ b/doc/book-enea-nfv-access-getting-started/doc/book.xml | |||
@@ -23,18 +23,15 @@ | |||
23 | 23 | ||
24 | <xi:include href="getting_started_nfv_access.xml" | 24 | <xi:include href="getting_started_nfv_access.xml" |
25 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | 25 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
26 | 26 | ||
27 | <xi:include href="secure_boot.xml" | 27 | <xi:include href="getting_started_ucpe_manager.xml" |
28 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | 28 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
29 | 29 | ||
30 | <xi:include href="bare_metal_provisioning.xml" | 30 | <xi:include href="secure_boot.xml" |
31 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | 31 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
32 | 32 | ||
33 | <xi:include href="getting_started_ucpe_manager.xml" | 33 | <xi:include href="bare_metal_provisioning.xml" |
34 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | 34 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
35 | |||
36 | <xi:include href="device_configuration_and_provisioning.xml" | ||
37 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | ||
38 | 35 | ||
39 | <xi:include href="in_band_management.xml" | 36 | <xi:include href="in_band_management.xml" |
40 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | 37 | xmlns:xi="http://www.w3.org/2001/XInclude" /> |
diff --git a/doc/book-enea-nfv-access-getting-started/doc/device_configuration_and_provisioning.xml b/doc/book-enea-nfv-access-getting-started/doc/device_configuration_and_provisioning.xml deleted file mode 100644 index a1ebf64..0000000 --- a/doc/book-enea-nfv-access-getting-started/doc/device_configuration_and_provisioning.xml +++ /dev/null | |||
@@ -1,765 +0,0 @@ | |||
1 | <?xml version="1.0" encoding="ISO-8859-1"?> | ||
2 | <chapter id="configuration_provision"> | ||
3 | <title>Device Configuration and Provisioning</title> | ||
4 | |||
5 | <section id="man_config"> | ||
6 | <title>Manual Configuration</title> | ||
7 | |||
8 | <para>This section describes how to connect to an instance of NFV Access | ||
9 | installed on a specific uCPE device, and how to setup the virtual | ||
10 | infrastructure manually.</para> | ||
11 | |||
12 | <para><emphasis role="bold">How to add a uCPE device to the management | ||
13 | system </emphasis></para> | ||
14 | |||
15 | <para>Add the uCPE device running the NFV Access Run Time Platform to the | ||
16 | management system: <literal>Devices -> Manage -> Add</literal>. Supply | ||
17 | information about the uCPE device, and set the parameters that will be used | ||
18 | to connect to it.</para> | ||
19 | |||
20 | <para>The relevant parameters are:</para> | ||
21 | |||
22 | <itemizedlist> | ||
23 | <listitem> | ||
24 | <para>Type. The type of device to be added, i.e <literal>Enea | ||
25 | universal uCPE</literal>.</para> | ||
26 | </listitem> | ||
27 | </itemizedlist> | ||
28 | |||
29 | <itemizedlist> | ||
30 | <listitem> | ||
31 | <para>Name. The name by which the device is referred to in the uCPE | ||
32 | Manager.</para> | ||
33 | </listitem> | ||
34 | </itemizedlist> | ||
35 | |||
36 | <itemizedlist> | ||
37 | <listitem> | ||
38 | <para>IP Address. IP address of the device. If a device is installed | ||
39 | under a local/private network and not directly visible to the uCPE | ||
40 | Manager machine, the Gateway IP of the private network must be | ||
41 | used.</para> | ||
42 | </listitem> | ||
43 | </itemizedlist> | ||
44 | |||
45 | <itemizedlist> | ||
46 | <listitem> | ||
47 | <para>SSH Port. The NETCONF Port used for communications. This is a | ||
48 | relevant parameter if the standard NETCONF SSH (i.e. not Call-Home) is | ||
49 | being used. Default is set to 830.</para> | ||
50 | </listitem> | ||
51 | </itemizedlist> | ||
52 | |||
53 | <itemizedlist> | ||
54 | <listitem> | ||
55 | <para>SSH User Name. The user name for SSH connectivity. Default user | ||
56 | is <literal>root</literal>.</para> | ||
57 | </listitem> | ||
58 | </itemizedlist> | ||
59 | |||
60 | <itemizedlist> | ||
61 | <listitem> | ||
62 | <para>SSH Password. Leave this blank.</para> | ||
63 | </listitem> | ||
64 | </itemizedlist> | ||
65 | |||
66 | <itemizedlist> | ||
67 | <listitem> | ||
68 | <para>Device Calls Home. This checkbox indicates the direction of | ||
69 | device communications. In the Manual Configuration, leave this box | ||
70 | blank. For more info about how to add a device please refer to <link | ||
71 | linkend="adding_a_device">Zero Touch Provisioning, Adding a | ||
72 | Device</link>.</para> | ||
73 | </listitem> | ||
74 | </itemizedlist> | ||
75 | |||
76 | <itemizedlist> | ||
77 | <listitem> | ||
78 | <para>Device ID. The unique instance ID of the device. This is what | ||
79 | links a device to its day-0 configuration (stored in the offline | ||
80 | configuration system). It is a required field if you want to perform | ||
81 | Zero-Touch Provisioning.</para> | ||
82 | </listitem> | ||
83 | </itemizedlist> | ||
84 | </section> | ||
85 | |||
86 | <section id="host_int_net_config"> | ||
87 | <title>Host Interfaces and Network Configuration</title> | ||
88 | |||
89 | <para>The uCPE Manager can list network interfaces found on a device by | ||
90 | selecting: <literal>Device</literal> -> | ||
91 | <literal>Configuration</literal> -> <literal>OpenVSwitch | ||
92 | </literal>-> <literal>Host Interface Caps</literal>:</para> | ||
93 | |||
94 | <figure> | ||
95 | <title>Host Interface Caps</title> | ||
96 | |||
97 | <mediaobject> | ||
98 | <imageobject> | ||
99 | <imagedata align="center" fileref="images/host_interface_caps.png" | ||
100 | scale="55" /> | ||
101 | </imageobject> | ||
102 | </mediaobject> | ||
103 | </figure> | ||
104 | |||
105 | <para>Network interfaces can be set in three modes: DPDK, SR-IOV and | ||
106 | PCI-Passthrough.</para> | ||
107 | |||
108 | <section id="dpdk_interface"> | ||
109 | <title>DPDK Interface Type</title> | ||
110 | |||
111 | <para>Configuring a physical interface in DPDK mode will require a | ||
112 | DPDK-based application (e.g. OVS-DPDK) in order to access and use the | ||
113 | interface. An interface set as DPDK can be attached to an OVS-DPDK | ||
114 | bridge. Select the uCPE device, then from the top toolbar select: | ||
115 | <literal>Configuration</literal> -><literal> OpenVSwitch | ||
116 | </literal>-> <literal>Host Interfaces</literal> -><literal> | ||
117 | Add</literal>:</para> | ||
118 | |||
119 | <figure> | ||
120 | <title>DPDK Host Interface</title> | ||
121 | |||
122 | <mediaobject> | ||
123 | <imageobject> | ||
124 | <imagedata align="center" fileref="images/dpdk_interface_type.png" | ||
125 | scale="90" /> | ||
126 | </imageobject> | ||
127 | </mediaobject> | ||
128 | </figure> | ||
129 | |||
130 | <para>For DPDK mode, the user must set following fields:</para> | ||
131 | |||
132 | <itemizedlist> | ||
133 | <listitem> | ||
134 | <para>Source: PCI address of the physical interface</para> | ||
135 | </listitem> | ||
136 | |||
137 | <listitem> | ||
138 | <para>Type: dpdk</para> | ||
139 | </listitem> | ||
140 | |||
141 | <listitem> | ||
142 | <para>Networking-type: dpdk</para> | ||
143 | </listitem> | ||
144 | |||
145 | <listitem> | ||
146 | <para>Dpdk-type: kernel module that allow user space access of | ||
147 | physical interface</para> | ||
148 | </listitem> | ||
149 | </itemizedlist> | ||
150 | |||
151 | <para>Create an OpenVSwitch bridge (<literal>ovsbr0</literal>) on the | ||
152 | device that uses a DPDK interface, by selecting the uCPE device, then | ||
153 | from the top toolbar selecting: <literal>Configuration</literal>-> | ||
154 | <literal>OpenVSwitch</literal> -> <literal>Bridges</literal> -> | ||
155 | <literal>Add</literal>:</para> | ||
156 | |||
157 | <figure> | ||
158 | <title>OVS bridge</title> | ||
159 | |||
160 | <mediaobject> | ||
161 | <imageobject> | ||
162 | <imagedata align="center" fileref="images/ovs_bridge.png" | ||
163 | scale="95" /> | ||
164 | </imageobject> | ||
165 | </mediaobject> | ||
166 | </figure> | ||
167 | </section> | ||
168 | |||
169 | <section id="sriov_interface_type"> | ||
170 | <title>SR-IOV Interface Type</title> | ||
171 | |||
172 | <para>SR-IOV mode will create a number of virtual functions on host that | ||
173 | can be used to route traffic to VMs. Select the uCPE device, then from | ||
174 | the top toolbar select: <literal>Configuration</literal> -><literal> | ||
175 | OpenVSwitch </literal>-> <literal>Host Interfaces | ||
176 | </literal>-><literal> Add</literal>:</para> | ||
177 | |||
178 | <para>For SR-IOV mode, the user must set following fields:</para> | ||
179 | |||
180 | <itemizedlist> | ||
181 | <listitem> | ||
182 | <para>Source: PCI address of the physical interface</para> | ||
183 | </listitem> | ||
184 | |||
185 | <listitem> | ||
186 | <para>Type: sr-iov</para> | ||
187 | </listitem> | ||
188 | |||
189 | <listitem> | ||
190 | <para>Networking-type: srIov</para> | ||
191 | </listitem> | ||
192 | |||
193 | <listitem> | ||
194 | <para>sriov-mode: adapter-pool</para> | ||
195 | </listitem> | ||
196 | |||
197 | <listitem> | ||
198 | <para>sriov-num-vfs: the number of virtual functions to | ||
199 | create</para> | ||
200 | </listitem> | ||
201 | </itemizedlist> | ||
202 | |||
203 | <figure> | ||
204 | <title>SR-IOV Interface Type</title> | ||
205 | |||
206 | <mediaobject> | ||
207 | <imageobject> | ||
208 | <imagedata align="center" | ||
209 | fileref="images/sriov_interface_type.png" scale="90" /> | ||
210 | </imageobject> | ||
211 | </mediaobject> | ||
212 | </figure> | ||
213 | </section> | ||
214 | |||
215 | <section id="pci_interface_type"> | ||
216 | <title>PCI Passthrough Interface Type</title> | ||
217 | |||
218 | <para>For PCI Passthrough the user does not have to configure a physical | ||
219 | interface, instead simply select the PCI address and connect it to a | ||
220 | virtual port at the VNF instantiation step.</para> | ||
221 | </section> | ||
222 | </section> | ||
223 | |||
224 | <section id="zero_touch_prov"> | ||
225 | <title>Zero Touch Provisioning</title> | ||
226 | |||
227 | <para>Zero-Touch Provisioning (ZTP) is an alternative to Manual | ||
228 | configuration. ZTP refers to the process by which, when a device starts up | ||
229 | for the first time, its initial configuration is pushed down by an | ||
230 | external management system, so that it is setup for proper operation | ||
231 | without additional manual intervention by an operator.</para> | ||
232 | |||
233 | <para>A variety of operations can occur as part of ZTP such as initial | ||
234 | device setup, configuration of managed objects, etc. The goal is to set up | ||
235 | a device to the maximum possible extent without forcing an operator to be | ||
236 | physically present (initially) to manage the device.</para> | ||
237 | |||
238 | <para>In order to create a static configuration supporting ZTP, the uCPE | ||
239 | Manager user needs to identify the <literal>Device ID</literal> of the | ||
240 | machine running NFV Access.</para> | ||
241 | |||
242 | <para>During the automatic installation process when the | ||
243 | <literal>Automatic install</literal> step is reached, enter the option | ||
244 | menu <literal>Customize kernel parameters</literal> and set the | ||
245 | <literal>uCPE Manager IP address</literal>. Please check <xref | ||
246 | linkend="install_ena_stick" />, for how to set the uCPE Manager IP address | ||
247 | at boot time. The Device ID will be listed in the installer under the | ||
248 | <literal>Customize kernel parameters</literal> menu.</para> | ||
249 | |||
250 | <para>With the address parameter set, run | ||
251 | <literal>list_deviceID.sh</literal> after NFV Access is installed and | ||
252 | booted, to get the device ID of the uCPE device.</para> | ||
253 | |||
254 | <note> | ||
255 | <para>It is possible to let NFV Access know the uCPE Manager IP address | ||
256 | at run-time by setting <literal>vcpemgr=<IP></literal> as a kernel | ||
257 | boot parameter in the grub configuration file. Reboot is required after | ||
258 | this update.</para> | ||
259 | |||
260 | <para>This step needs to be done each time the uCPE Manager host changes | ||
261 | its IP address.</para> | ||
262 | </note> | ||
263 | |||
264 | <para>An offline configuration can be prepared in advance for the uCPE | ||
265 | Manager to setup the infrastructure on the device.</para> | ||
266 | |||
267 | <section id="adding_a_device"> | ||
268 | <title>Adding a Device</title> | ||
269 | |||
270 | <para>The uCPE Manager must be configured to bring the uCPE device under | ||
271 | management. This is done by selecting <literal>Device Calls | ||
272 | Home</literal> checkbox when adding a device. When Device Calls Home | ||
273 | checkbox is checked, the device will initiate a connection by opening a | ||
274 | socket to the uCPE Manager for NETCONF traffic (over SSH), while the | ||
275 | uCPE Manager waits for device connection.</para> | ||
276 | |||
277 | <para>For more info about how to add a device please refer to <link | ||
278 | linkend="man_config">Manual Configuration</link>.</para> | ||
279 | </section> | ||
280 | |||
281 | <section id="offline_configuration"> | ||
282 | <title>Offline Configuration</title> | ||
283 | |||
284 | <para>The Offline Configuration subsystem is used to pre-populate a | ||
285 | configuration for a device that will be brought under management at a | ||
286 | future point in time. When creating an offline configuration store, an | ||
287 | optional<literal> Device ID</literal> can be specified - this ID | ||
288 | uniquely identifies the device to be initialized.</para> | ||
289 | |||
290 | <para>Use the GUI (shown below) launched by the <literal>Applications | ||
291 | -> Offline Config -> Add</literal> menu:</para> | ||
292 | |||
293 | <figure> | ||
294 | <title>Onboard New VNF</title> | ||
295 | |||
296 | <mediaobject> | ||
297 | <imageobject> | ||
298 | <imagedata align="center" fileref="images/offline_config.png" | ||
299 | scale="80" /> | ||
300 | </imageobject> | ||
301 | </mediaobject> | ||
302 | </figure> | ||
303 | |||
304 | <para>Specify the exact value of the <literal>Device ID</literal> in the | ||
305 | required field. This will tag the device needed for the initial | ||
306 | configuration provided by the offline configuration store. Choose | ||
307 | <literal>Merge</literal> as the Default Upload Method if you do not want | ||
308 | any boot configuration set on the device, to be wiped out. Selecting | ||
309 | <literal>Replace</literal> will set the entire device configuration to | ||
310 | match values in the offline configuration.</para> | ||
311 | |||
312 | <para>After creating the Offline Config Store, access the device through | ||
313 | <literal> Applications -> offline config -> Config App</literal> | ||
314 | and provision it with the required initial configuration. This operation | ||
315 | mirrors what happens during regular offline configuration.</para> | ||
316 | |||
317 | <para>Now that the store has been provisioned successfully, it is ready | ||
318 | to send this configuration to the device when it first comes | ||
319 | online.</para> | ||
320 | </section> | ||
321 | |||
322 | <section id="initial_communications"> | ||
323 | <title>Initial Communications</title> | ||
324 | |||
325 | <para>There are two possible paths to this process, depending upon | ||
326 | whether or not NETCONF Call-Home functionality is used:</para> | ||
327 | |||
328 | <orderedlist> | ||
329 | <listitem> | ||
330 | <para>If Call-Home is not enabled/supported, the uCPE Manager | ||
331 | creates a SSH session to the device over the port configured through | ||
332 | the <literal>Add Device </literal> process (default 830). It then | ||
333 | initiates NETCONF communications over this session.</para> | ||
334 | </listitem> | ||
335 | |||
336 | <listitem> | ||
337 | <para>If the device uses Call-Home, it creates a socket connection | ||
338 | to port 4334 on the management system which runs the uCPE Manager. | ||
339 | The uCPE Manager then creates a SSH session over this socket and | ||
340 | initiates NETCONF communications as a client.</para> | ||
341 | </listitem> | ||
342 | </orderedlist> | ||
343 | |||
344 | <para>Once communications with the device have been established, the | ||
345 | Device Manager will try and connect to it.</para> | ||
346 | </section> | ||
347 | </section> | ||
348 | |||
349 | <section id="vnf_management"> | ||
350 | <title>VNF Management</title> | ||
351 | |||
352 | <para>As the acting vnf manager, the uCPE Manager is responsible for | ||
353 | handling the life-cycles of VNFs that are instantiated and run on the | ||
354 | various uCPE devices. The vnf manager module is written so as to be able | ||
355 | to manage multiple VNF types. Along with it is provided a generic | ||
356 | infrastructure to allow the end-user to introduce new VNF types | ||
357 | dynamically into the system. This allows for third-party VNFs to be added | ||
358 | over time to an existing network infrastructure without having to perform | ||
359 | an expensive upgrade of the vnf manager itself.</para> | ||
360 | |||
361 | <para>The process of VNF Onboarding consists of providing the system with | ||
362 | sufficient information and resources related to the VNF such that it can | ||
363 | instantiate a flavour of the VNF on the uCPE device, configure and scale | ||
364 | it as appropriate, heal and upgrade it when necessary and tear it down at | ||
365 | the right moment.</para> | ||
366 | |||
367 | <para>The vnf manager subsystem in the uCPE Manager inserts a menu item in | ||
368 | the toolbar, called <literal>VNF</literal> as shown in the screen-shot | ||
369 | below.</para> | ||
370 | |||
371 | <figure> | ||
372 | <title>VNF Management</title> | ||
373 | |||
374 | <mediaobject> | ||
375 | <imageobject> | ||
376 | <imagedata align="center" fileref="images/vnf_management.png" | ||
377 | scale="80" /> | ||
378 | </imageobject> | ||
379 | </mediaobject> | ||
380 | </figure> | ||
381 | |||
382 | <para>Selecting this menu item gives you the following options:</para> | ||
383 | |||
384 | <itemizedlist> | ||
385 | <listitem> | ||
386 | <para><literal>Descriptors</literal>: Choosing this option lets you | ||
387 | manage the VNF Descriptors catalog. The vnf manager maintains a | ||
388 | catalog of all VNFs that can be instantiated and managed by the | ||
389 | system. Before you can use a new VNF, you need to onboard it into the | ||
390 | catalog.</para> | ||
391 | </listitem> | ||
392 | |||
393 | <listitem> | ||
394 | <para><literal>Instances</literal>: Choosing this option lets you | ||
395 | instantiate (or destroy) VNFs on a given uCPE device.</para> | ||
396 | </listitem> | ||
397 | |||
398 | <listitem> | ||
399 | <para><literal>Events</literal>: Choosing this option displays all the | ||
400 | events that are related to VNF lifecycle management. Whenever a VNF | ||
401 | state changes (i.e. it is | ||
402 | created/destroyed/stopped/started/paused/resumed), a state change | ||
403 | event is generated in the uCPE Manager. The screen shown when this | ||
404 | option is chosen displays all events in the system, filtered to show | ||
405 | only VNF state change notifications.</para> | ||
406 | </listitem> | ||
407 | </itemizedlist> | ||
408 | |||
409 | <section id="onboarding_a_vnf"> | ||
410 | <title>Onboarding a VNF</title> | ||
411 | |||
412 | <para>The VNF descriptor catalog table provides a button that allows you | ||
413 | to onboard a new (third-party) VNF into the catalog.</para> | ||
414 | |||
415 | <figure> | ||
416 | <title>Onboard New VNF</title> | ||
417 | |||
418 | <mediaobject> | ||
419 | <imageobject> | ||
420 | <imagedata align="center" | ||
421 | fileref="images/onboarding_a_new_vnf.png" scale="70" /> | ||
422 | </imageobject> | ||
423 | </mediaobject> | ||
424 | </figure> | ||
425 | |||
426 | <section id="onboarding_a_vnf_wizard"> | ||
427 | <title>Onboarding a VNF VM Image using the Onboarding Wizard</title> | ||
428 | |||
429 | <para><emphasis role="bold">How to onboard a VNF into the uCPE Manager | ||
430 | using the Onboarding Wizard</emphasis></para> | ||
431 | |||
432 | <orderedlist> | ||
433 | <listitem> | ||
434 | <para>Make sure the uCPE device is added and placed on the map in | ||
435 | the uCPE Manager.</para> | ||
436 | </listitem> | ||
437 | |||
438 | <listitem> | ||
439 | <para>Select from the top toolbar <literal>VNF</literal> -> | ||
440 | <literal>Descriptors.</literal></para> | ||
441 | </listitem> | ||
442 | |||
443 | <listitem> | ||
444 | <para>Click the <literal>On-board</literal> button.</para> | ||
445 | </listitem> | ||
446 | |||
447 | <listitem> | ||
448 | <para>When prompted by the following UI, make sure the <literal>VM | ||
449 | Image</literal> radio button is selected.</para> | ||
450 | </listitem> | ||
451 | </orderedlist> | ||
452 | |||
453 | <para>If you click the <literal>VM Image</literal> radio button at the | ||
454 | top of the onboarding screen, you will get a pop-up containing fields | ||
455 | which you can fill, suppling the necessary information about the VNF. | ||
456 | After providing the information and pressing the onboard button, the | ||
457 | uCPE Manager will create the VNF package and onboard it.</para> | ||
458 | |||
459 | <figure> | ||
460 | <title>Onboard a VNF using the Wizard</title> | ||
461 | |||
462 | <mediaobject> | ||
463 | <imageobject> | ||
464 | <imagedata align="center" | ||
465 | fileref="images/onboard_a_vnf_image.png" scale="70" /> | ||
466 | </imageobject> | ||
467 | </mediaobject> | ||
468 | </figure> | ||
469 | |||
470 | <para><emphasis role="bold">Main fields</emphasis></para> | ||
471 | |||
472 | <itemizedlist> | ||
473 | <listitem> | ||
474 | <para><emphasis role="bold">VM Image File.</emphasis> This is the | ||
475 | Virtual Machine image file for the VNF itself. Typically, it is a | ||
476 | QCOW image. Press <literal>Choose File</literal> and select the | ||
477 | image to be uploaded.</para> | ||
478 | </listitem> | ||
479 | |||
480 | <listitem> | ||
481 | <para><emphasis role="bold">Image Format</emphasis>. Select the | ||
482 | format which matches the image file.</para> | ||
483 | </listitem> | ||
484 | |||
485 | <listitem> | ||
486 | <para><emphasis role="bold">VNF Type Name.</emphasis> This is the | ||
487 | name that will be used to identify this VNF. It will be shown in | ||
488 | the VNF tables.</para> | ||
489 | </listitem> | ||
490 | |||
491 | <listitem> | ||
492 | <para><emphasis role="bold">Description.</emphasis> This field | ||
493 | contains any description you want to provide. It is only displayed | ||
494 | in the GUI tables in the uCPE Manager.</para> | ||
495 | </listitem> | ||
496 | |||
497 | <listitem> | ||
498 | <para><emphasis role="bold">Version</emphasis>. This is the | ||
499 | version of the current VNF that you are hosting. It's used to | ||
500 | distinguish this VNF from other versions of the same type.</para> | ||
501 | </listitem> | ||
502 | |||
503 | <listitem> | ||
504 | <para><emphasis role="bold">Memory in MB.</emphasis> This is the | ||
505 | amount of memory (in megabytes) that will be provided to this type | ||
506 | of VNF when it is instantiated. To determine the value for this | ||
507 | field, consult the VNF vendor.</para> | ||
508 | </listitem> | ||
509 | |||
510 | <listitem> | ||
511 | <para><emphasis role="bold">Num of CPUs.</emphasis> The number of | ||
512 | CPUs that will be dedicated to an instance of this VNF when | ||
513 | created. To determine the value for this field, consult the VNF | ||
514 | vendor.</para> | ||
515 | </listitem> | ||
516 | |||
517 | <listitem> | ||
518 | <para><emphasis role="bold">Storage in GB.</emphasis> How much | ||
519 | disk space to provide an instance of this VNF. To determine the | ||
520 | value for this field, consult the VNF vendor.</para> | ||
521 | </listitem> | ||
522 | </itemizedlist> | ||
523 | |||
524 | <para><emphasis role="bold">Interfaces Tab</emphasis></para> | ||
525 | |||
526 | <figure> | ||
527 | <title>Interfaces Table</title> | ||
528 | |||
529 | <mediaobject> | ||
530 | <imageobject> | ||
531 | <imagedata align="center" fileref="images/interfaces_table.png" | ||
532 | scale="70" /> | ||
533 | </imageobject> | ||
534 | </mediaobject> | ||
535 | </figure> | ||
536 | |||
537 | <para>Click on the <literal>Interfaces</literal> tab to show the | ||
538 | Interfaces table.</para> | ||
539 | |||
540 | <para>This table will contain the interfaces required by this VNF to | ||
541 | be configured, when creating an instance. Consult the VNF vendor to | ||
542 | determine which and how many are required. Each interface requires a | ||
543 | name, and optionally a description, used by the uCPE Manager | ||
544 | only.</para> | ||
545 | |||
546 | <para><emphasis role="bold">Cloud Init Tab</emphasis></para> | ||
547 | |||
548 | <para>Click the <literal>Clout Init</literal> tab to provide the | ||
549 | Clout-Init configuration.</para> | ||
550 | |||
551 | <figure> | ||
552 | <title>Cloud-Init Tab</title> | ||
553 | |||
554 | <mediaobject> | ||
555 | <imageobject> | ||
556 | <imagedata align="center" fileref="images/cloud_init_tab.png" | ||
557 | scale="70" /> | ||
558 | </imageobject> | ||
559 | </mediaobject> | ||
560 | </figure> | ||
561 | |||
562 | <para>As shown in the picture above, there are three fields that need | ||
563 | to be populated:</para> | ||
564 | |||
565 | <orderedlist> | ||
566 | <listitem> | ||
567 | <para><emphasis role="bold">Cloud-Init | ||
568 | Datasource</emphasis></para> | ||
569 | |||
570 | <para>To onboard the VNF you must specify the<literal> Cloud-Init | ||
571 | Datasource</literal> that the VNF uses. You can get this | ||
572 | information from the VNF Vendor. Choose one of the following | ||
573 | methods to specify the datasource:</para> | ||
574 | |||
575 | <itemizedlist> | ||
576 | <listitem> | ||
577 | <para><emphasis role="bold">None</emphasis>. If there is no | ||
578 | datasource.</para> | ||
579 | </listitem> | ||
580 | |||
581 | <listitem> | ||
582 | <para><emphasis role="bold">ConfigDrive</emphasis>. This | ||
583 | method allows you to provide any number of content-data files | ||
584 | containing Cloud-Init data.</para> | ||
585 | </listitem> | ||
586 | |||
587 | <listitem> | ||
588 | <para><emphasis role="bold">NoCloud</emphasis>. This is a | ||
589 | simpler method that uses only one cloud init file | ||
590 | (User-Data).</para> | ||
591 | </listitem> | ||
592 | |||
593 | <listitem> | ||
594 | <para><emphasis role="bold">ISO</emphasis>. Pre-cooked | ||
595 | cloud-init image. This image must be created by the user | ||
596 | according to VNF requirements.</para> | ||
597 | </listitem> | ||
598 | </itemizedlist> | ||
599 | </listitem> | ||
600 | |||
601 | <listitem> | ||
602 | <para><emphasis role="bold">Cloud-Init Disk Type</emphasis></para> | ||
603 | |||
604 | <para>The <literal>Cloud-Init Disk Type </literal>field must be | ||
605 | set to either <literal>Disk</literal>, or | ||
606 | <literal>CD-ROM</literal>, depending on what the VNF requires. You | ||
607 | can get this information from the VNF Vendor.</para> | ||
608 | </listitem> | ||
609 | |||
610 | <listitem> | ||
611 | <para><emphasis role="bold">Content Files Table</emphasis></para> | ||
612 | |||
613 | <para>The <literal>Content Files Table </literal>is ONLY used if | ||
614 | you choose <literal>ConfigDrive</literal> as the Cloud-Init | ||
615 | Datasource. For each content file added, you must provide a | ||
616 | <literal>Path</literal>. When a user uses the uCPE Manager to | ||
617 | create an instance of one of these VNFs, they will be prompted to | ||
618 | provide a data file for each entry in this table. Each type of VNF | ||
619 | will require different cloud-init files, e.g.: a license | ||
620 | file.</para> | ||
621 | </listitem> | ||
622 | </orderedlist> | ||
623 | |||
624 | <figure> | ||
625 | <title>Content Files Table example</title> | ||
626 | |||
627 | <mediaobject> | ||
628 | <imageobject> | ||
629 | <imagedata align="center" | ||
630 | fileref="images/content_files_table.png" scale="70" /> | ||
631 | </imageobject> | ||
632 | </mediaobject> | ||
633 | </figure> | ||
634 | |||
635 | <para>Consult with the VNF vendor to determine what is required for | ||
636 | the VNF you are onboarding.</para> | ||
637 | |||
638 | <para><emphasis role="bold">Properties Tab</emphasis></para> | ||
639 | |||
640 | <para>In this table, you can enter values for properties that will be | ||
641 | used during instantiation of the VNF. The values will augment the | ||
642 | default values in the Domain.XML file used by libvirt/virsh (running | ||
643 | in NFV Access) when creating an instance of the VNF. These property | ||
644 | names are well known to the uCPE NFV Access software, and more will be | ||
645 | added in future versions. You will need to consult with the VNF Vendor | ||
646 | or ENEA support for values needed by specific VNFs.</para> | ||
647 | |||
648 | <figure> | ||
649 | <title>Properties Tab</title> | ||
650 | |||
651 | <mediaobject> | ||
652 | <imageobject> | ||
653 | <imagedata align="center" fileref="images/properties_tab.png" | ||
654 | scale="70" /> | ||
655 | </imageobject> | ||
656 | </mediaobject> | ||
657 | </figure> | ||
658 | |||
659 | <para><emphasis role="bold">Property Values</emphasis></para> | ||
660 | |||
661 | <para><literal>numHugePages</literal> defines the number of huge | ||
662 | memory pages the VNF uses (for DPDK).</para> | ||
663 | </section> | ||
664 | </section> | ||
665 | |||
666 | <section id="instantiating_a_vnf"> | ||
667 | <title>Instantiating a VNF</title> | ||
668 | |||
669 | <para>Once the VNF has been onboarded, you can instantiate a VNF on a | ||
670 | specific uCPE device.</para> | ||
671 | |||
672 | <para><emphasis role="bold">How to instantiate a VNF using the | ||
673 | Wizard</emphasis></para> | ||
674 | |||
675 | <orderedlist> | ||
676 | <listitem> | ||
677 | <para>Make sure the uCPE device is added and placed on the map in | ||
678 | the uCPE Manager.</para> | ||
679 | </listitem> | ||
680 | |||
681 | <listitem> | ||
682 | <para>Make sure the VNF has been onboarded into the uCPE | ||
683 | Manager.</para> | ||
684 | </listitem> | ||
685 | |||
686 | <listitem> | ||
687 | <para>Select from the top toolbar <literal>VNF</literal> -> | ||
688 | <literal>Instances</literal></para> | ||
689 | </listitem> | ||
690 | |||
691 | <listitem> | ||
692 | <para>Click the <literal>Add</literal> button.</para> | ||
693 | </listitem> | ||
694 | |||
695 | <listitem> | ||
696 | <para>When prompted by the following UI, fill the required | ||
697 | fields.</para> | ||
698 | </listitem> | ||
699 | </orderedlist> | ||
700 | |||
701 | <figure> | ||
702 | <title>Instantiating a VNF</title> | ||
703 | |||
704 | <mediaobject> | ||
705 | <imageobject> | ||
706 | <imagedata align="center" fileref="images/instantiate_a_vnf.png" | ||
707 | scale="70" /> | ||
708 | </imageobject> | ||
709 | </mediaobject> | ||
710 | </figure> | ||
711 | |||
712 | <para>There are a number of parameters to be supplied before the VNF can | ||
713 | be instantiated:</para> | ||
714 | |||
715 | <itemizedlist> | ||
716 | <listitem> | ||
717 | <para><emphasis role="bold">Name</emphasis>. The name of the | ||
718 | VNF.</para> | ||
719 | </listitem> | ||
720 | |||
721 | <listitem> | ||
722 | <para><emphasis role="bold">VNF Type</emphasis>. The name of the | ||
723 | onboarded VNF. In this case <literal>VProbe</literal> VNF.</para> | ||
724 | </listitem> | ||
725 | |||
726 | <listitem> | ||
727 | <para><emphasis role="bold">Flavour</emphasis>. The flavour of VNF | ||
728 | (as specified in the descriptor) you would like to | ||
729 | instantiate.</para> | ||
730 | </listitem> | ||
731 | |||
732 | <listitem> | ||
733 | <para><emphasis role="bold">Device</emphasis>. The uCPE device on which | ||
734 | to instantiate a VNF, i.e. the uCPE device that will run this | ||
735 | VNF.</para> | ||
736 | </listitem> | ||
737 | |||
738 | <listitem> | ||
739 | <para><emphasis role="bold">Auto-start</emphasis>. If checked, the | ||
740 | VNF will be stopped and started when unreachable. When the uCPE Device reports that it has lost connection to the VNF, the uCPE Manager | ||
741 | will ask it to terminate the VM and then start it up again. If | ||
742 | unchecked, only a <literal>Disconnected</literal> notification will | ||
743 | appear in the uCPE Manager.</para> | ||
744 | </listitem> | ||
745 | </itemizedlist> | ||
746 | |||
747 | <para>Hitting the <literal>Create</literal> button will cause the VNF to | ||
748 | be instantiated and run on the specified uCPE device.</para> | ||
749 | |||
750 | <para>Selecting the<literal> VNF -> Events</literal> menu will show | ||
751 | that the VNF was created and a connection was established:</para> | ||
752 | |||
753 | <figure> | ||
754 | <title>VNF Events menu</title> | ||
755 | |||
756 | <mediaobject> | ||
757 | <imageobject> | ||
758 | <imagedata align="center" fileref="images/instantiate_a_vnf4.png" | ||
759 | scale="70" /> | ||
760 | </imageobject> | ||
761 | </mediaobject> | ||
762 | </figure> | ||
763 | </section> | ||
764 | </section> | ||
765 | </chapter> | ||
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 2704fc8..80595e6 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 | |||
@@ -1,5 +1,5 @@ | |||
1 | <?xml version="1.0" encoding="ISO-8859-1"?> | 1 | <?xml version="1.0" encoding="ISO-8859-1"?> |
2 | <chapter id="installation"> | 2 | <chapter id="getting_started_ucpe_manager"> |
3 | <title>Getting Started with Enea uCPE Manager</title> | 3 | <title>Getting Started with Enea uCPE Manager</title> |
4 | 4 | ||
5 | <section id="prere"> | 5 | <section id="prere"> |
@@ -25,7 +25,7 @@ | |||
25 | 25 | ||
26 | <para>Unpack the uCPE Manager and install it by following the instructions | 26 | <para>Unpack the uCPE Manager and install it by following the instructions |
27 | provided within the release archive: | 27 | provided within the release archive: |
28 | <literal>[unpacked_folder]/dist/README.</literal> </para> | 28 | <literal>[unpacked_folder]/dist/README</literal>.</para> |
29 | 29 | ||
30 | <para>There are a few things to consider during the installation phase, as | 30 | <para>There are a few things to consider during the installation phase, as |
31 | there are a few steps where user input is required. In most cases, the | 31 | there are a few steps where user input is required. In most cases, the |
@@ -35,8 +35,9 @@ | |||
35 | defaults to Y), and not the machine as part of a cluster (which defaults | 35 | defaults to Y), and not the machine as part of a cluster (which defaults |
36 | to N). Installing on a Windows machine, will require the user to follow | 36 | to N). Installing on a Windows machine, will require the user to follow |
37 | the Windows password policies when defining the password for the <emphasis | 37 | the Windows password policies when defining the password for the <emphasis |
38 | role="bold">ucpemanager</emphasis> service. A good example for an acceptable | 38 | role="bold">ucpemanager</emphasis> service. A good example for an |
39 | password would be:<emphasis>_1ucpe#2manager!3_</emphasis>.</para> | 39 | acceptable password would |
40 | be:<emphasis>_1ucpe#2manager!3_</emphasis>.</para> | ||
40 | 41 | ||
41 | <para>Check that the Windows or CentOS machine where the uCPE Manager is | 42 | <para>Check that the Windows or CentOS machine where the uCPE Manager is |
42 | installed has the firewall disabled. To disable the firewall, if using | 43 | installed has the firewall disabled. To disable the firewall, if using |
@@ -60,4 +61,767 @@ | |||
60 | </listitem> | 61 | </listitem> |
61 | </orderedlist> | 62 | </orderedlist> |
62 | </section> | 63 | </section> |
64 | |||
65 | <section id="device_config_provision"> | ||
66 | <title>Device Configuration and Provisioning</title> | ||
67 | |||
68 | <section id="device_config"> | ||
69 | <title>Add a uCPE device to the Management System</title> | ||
70 | |||
71 | <para>This section describes how to connect to an instance of NFV Access | ||
72 | installed on a specific uCPE device, and how to setup the virtual | ||
73 | infrastructure.</para> | ||
74 | |||
75 | <section id="man_config"> | ||
76 | <title>Manual Addition</title> | ||
77 | |||
78 | <para>Add the uCPE device running the NFV Access Run Time Platform to | ||
79 | the management system: <literal>Devices -> Manage -> | ||
80 | Add</literal>. Supply information about the uCPE device, and set the | ||
81 | parameters that will be used to connect to it.</para> | ||
82 | |||
83 | <para>The relevant parameters are:</para> | ||
84 | |||
85 | <itemizedlist> | ||
86 | <listitem> | ||
87 | <para>Type. The type of device to be added, i.e <literal>Enea | ||
88 | universal uCPE</literal>.</para> | ||
89 | </listitem> | ||
90 | </itemizedlist> | ||
91 | |||
92 | <itemizedlist> | ||
93 | <listitem> | ||
94 | <para>Name. The name by which the device is referred to in the | ||
95 | uCPE Manager.</para> | ||
96 | </listitem> | ||
97 | </itemizedlist> | ||
98 | |||
99 | <itemizedlist> | ||
100 | <listitem> | ||
101 | <para>IP Address. IP address of the device. If a device is | ||
102 | installed under a local/private network and not directly visible | ||
103 | to the uCPE Manager machine, the Gateway IP of the private network | ||
104 | must be used.</para> | ||
105 | </listitem> | ||
106 | </itemizedlist> | ||
107 | |||
108 | <itemizedlist> | ||
109 | <listitem> | ||
110 | <para>SSH Port. The NETCONF Port used for communications. This is | ||
111 | a relevant parameter if the standard NETCONF SSH (i.e. not | ||
112 | Call-Home) is being used. Default is set to 830.</para> | ||
113 | </listitem> | ||
114 | </itemizedlist> | ||
115 | |||
116 | <itemizedlist> | ||
117 | <listitem> | ||
118 | <para>SSH User Name. The user name for SSH connectivity. Default | ||
119 | user is <literal>root</literal>.</para> | ||
120 | </listitem> | ||
121 | </itemizedlist> | ||
122 | |||
123 | <itemizedlist> | ||
124 | <listitem> | ||
125 | <para>SSH Password. Leave this blank.</para> | ||
126 | </listitem> | ||
127 | </itemizedlist> | ||
128 | |||
129 | <itemizedlist> | ||
130 | <listitem> | ||
131 | <para>Device Calls Home. This checkbox indicates the direction of | ||
132 | device communications. In the Manual Configuration, leave this box | ||
133 | blank. </para> | ||
134 | </listitem> | ||
135 | </itemizedlist> | ||
136 | |||
137 | <itemizedlist> | ||
138 | <listitem> | ||
139 | <para>Device ID. The unique instance ID of the device. This is | ||
140 | what links a device to its day-0 configuration (stored in the | ||
141 | offline configuration system). It is a required field if you want | ||
142 | to perform Zero-Touch Provisioning.</para> | ||
143 | </listitem> | ||
144 | </itemizedlist> | ||
145 | </section> | ||
146 | |||
147 | <section id="using_call_home"> | ||
148 | <title>Using Call-Home</title> | ||
149 | |||
150 | <para>The uCPE Manager must be configured to bring the uCPE device | ||
151 | under management. This is done by selecting the <literal>Device Calls | ||
152 | Home</literal> checkbox when adding a device. When Device Calls Home | ||
153 | is checked, the device will initiate a connection by opening | ||
154 | a socket to the uCPE Manager for NETCONF traffic (over SSH), while the | ||
155 | uCPE Manager waits for device connection.</para> | ||
156 | </section> | ||
157 | </section> | ||
158 | |||
159 | <section id="host_int_net_config"> | ||
160 | <title>Prepare uCPE device for VNF onboarding</title> | ||
161 | |||
162 | <para>The uCPE Manager can list network interfaces found on a device by | ||
163 | selecting: <literal>Device</literal> -> | ||
164 | <literal>Configuration</literal> -> <literal>OpenVSwitch | ||
165 | </literal>-> <literal>Host Interface Caps</literal>:</para> | ||
166 | |||
167 | <figure> | ||
168 | <title>Host Interface Caps</title> | ||
169 | |||
170 | <mediaobject> | ||
171 | <imageobject> | ||
172 | <imagedata align="center" fileref="images/host_interface_caps.png" | ||
173 | scale="55" /> | ||
174 | </imageobject> | ||
175 | </mediaobject> | ||
176 | </figure> | ||
177 | |||
178 | <para>Network interfaces can be set in three modes: DPDK, SR-IOV and | ||
179 | PCI-Passthrough.</para> | ||
180 | |||
181 | <section id="dpdk_interface"> | ||
182 | <title>DPDK Interface Type</title> | ||
183 | |||
184 | <para>Configuring a physical interface in DPDK mode will require a | ||
185 | DPDK-based application (e.g. OVS-DPDK) in order to access and use the | ||
186 | interface. An interface set as DPDK can be attached to an OVS-DPDK | ||
187 | bridge. Select the uCPE device, then from the top toolbar select: | ||
188 | <literal>Configuration</literal> -><literal> OpenVSwitch | ||
189 | </literal>-> <literal>Host Interfaces</literal> -><literal> | ||
190 | Add</literal>:</para> | ||
191 | |||
192 | <figure> | ||
193 | <title>DPDK Host Interface</title> | ||
194 | |||
195 | <mediaobject> | ||
196 | <imageobject> | ||
197 | <imagedata align="center" | ||
198 | fileref="images/dpdk_interface_type.png" scale="90" /> | ||
199 | </imageobject> | ||
200 | </mediaobject> | ||
201 | </figure> | ||
202 | |||
203 | <para>For DPDK mode, the user must set following fields:</para> | ||
204 | |||
205 | <itemizedlist> | ||
206 | <listitem> | ||
207 | <para>Source: PCI address of the physical interface</para> | ||
208 | </listitem> | ||
209 | |||
210 | <listitem> | ||
211 | <para>Type: dpdk</para> | ||
212 | </listitem> | ||
213 | |||
214 | <listitem> | ||
215 | <para>Networking-type: dpdk</para> | ||
216 | </listitem> | ||
217 | |||
218 | <listitem> | ||
219 | <para>Dpdk-type: kernel module that allow user space access of | ||
220 | physical interface</para> | ||
221 | </listitem> | ||
222 | </itemizedlist> | ||
223 | |||
224 | <para>Create an OpenVSwitch bridge (<literal>ovsbr0</literal>) on the | ||
225 | device that uses a DPDK interface, by selecting the uCPE device, then | ||
226 | from the top toolbar selecting: <literal>Configuration</literal>-> | ||
227 | <literal>OpenVSwitch</literal> -> <literal>Bridges</literal> -> | ||
228 | <literal>Add</literal>:</para> | ||
229 | |||
230 | <figure> | ||
231 | <title>OVS bridge</title> | ||
232 | |||
233 | <mediaobject> | ||
234 | <imageobject> | ||
235 | <imagedata align="center" fileref="images/ovs_bridge.png" | ||
236 | scale="95" /> | ||
237 | </imageobject> | ||
238 | </mediaobject> | ||
239 | </figure> | ||
240 | </section> | ||
241 | |||
242 | <section id="sriov_interface_type"> | ||
243 | <title>SR-IOV Interface Type</title> | ||
244 | |||
245 | <para>SR-IOV mode will create a number of virtual functions on host | ||
246 | that can be used to route traffic to VMs. Select the uCPE device, then | ||
247 | from the top toolbar select: <literal>Configuration</literal> | ||
248 | -><literal> OpenVSwitch </literal>-> <literal>Host Interfaces | ||
249 | </literal>-><literal> Add</literal>:</para> | ||
250 | |||
251 | <para>For SR-IOV mode, the user must set following fields:</para> | ||
252 | |||
253 | <itemizedlist> | ||
254 | <listitem> | ||
255 | <para>Source: PCI address of the physical interface</para> | ||
256 | </listitem> | ||
257 | |||
258 | <listitem> | ||
259 | <para>Type: sr-iov</para> | ||
260 | </listitem> | ||
261 | |||
262 | <listitem> | ||
263 | <para>Networking-type: srIov</para> | ||
264 | </listitem> | ||
265 | |||
266 | <listitem> | ||
267 | <para>sriov-mode: adapter-pool</para> | ||
268 | </listitem> | ||
269 | |||
270 | <listitem> | ||
271 | <para>sriov-num-vfs: the number of virtual functions to | ||
272 | create</para> | ||
273 | </listitem> | ||
274 | </itemizedlist> | ||
275 | |||
276 | <figure> | ||
277 | <title>SR-IOV Interface Type</title> | ||
278 | |||
279 | <mediaobject> | ||
280 | <imageobject> | ||
281 | <imagedata align="center" | ||
282 | fileref="images/sriov_interface_type.png" scale="90" /> | ||
283 | </imageobject> | ||
284 | </mediaobject> | ||
285 | </figure> | ||
286 | </section> | ||
287 | |||
288 | <section id="pci_interface_type"> | ||
289 | <title>PCI Passthrough Interface Type</title> | ||
290 | |||
291 | <para>For PCI Passthrough the user does not have to configure a | ||
292 | physical interface, instead simply select the PCI address and connect | ||
293 | it to a virtual port at the VNF instantiation step.</para> | ||
294 | </section> | ||
295 | </section> | ||
296 | |||
297 | <section id="zero_touch_prov"> | ||
298 | <title>Zero Touch Provisioning</title> | ||
299 | |||
300 | <para>Zero-Touch Provisioning (ZTP) is an alternative to Manual | ||
301 | configuration. ZTP refers to the process by which, when a device starts | ||
302 | up for the first time, its initial configuration is pushed down by an | ||
303 | external management system, so that it is setup for proper operation | ||
304 | without additional manual intervention by an operator.</para> | ||
305 | |||
306 | <para>A variety of operations can occur as part of ZTP such as initial | ||
307 | device setup, configuration of managed objects, etc. The goal is to set | ||
308 | up a device to the maximum possible extent without forcing an operator | ||
309 | to be physically present (initially) to manage the device.</para> | ||
310 | |||
311 | <para>In order to create a static configuration supporting ZTP, the uCPE | ||
312 | Manager user needs to identify the <literal>Device ID</literal> of the | ||
313 | machine running NFV Access.</para> | ||
314 | |||
315 | <para>During the automatic installation process when the | ||
316 | <literal>Automatic install</literal> step is reached, enter the option | ||
317 | menu <literal>Customize kernel parameters</literal> and set the | ||
318 | <literal>uCPE Manager IP address</literal>. Please check <xref | ||
319 | linkend="install_ena_stick" />, for how to set the uCPE Manager IP | ||
320 | address at boot time. The Device ID will be listed in the installer | ||
321 | under the <literal>Customize kernel parameters</literal> menu.</para> | ||
322 | |||
323 | <para>With the address parameter set, run | ||
324 | <literal>list_deviceID.sh</literal> after NFV Access is installed and | ||
325 | booted, to get the device ID of the uCPE device.</para> | ||
326 | |||
327 | <note> | ||
328 | <para>It is possible to let NFV Access know the uCPE Manager IP | ||
329 | address at run-time by setting <literal>vcpemgr=<IP></literal> | ||
330 | as a kernel boot parameter in the grub configuration file. Reboot is | ||
331 | required after this update.</para> | ||
332 | |||
333 | <para>This step needs to be done each time the uCPE Manager host | ||
334 | changes its IP address.</para> | ||
335 | </note> | ||
336 | |||
337 | <para>An offline configuration can be prepared in advance for the uCPE | ||
338 | Manager to setup the infrastructure on the device.</para> | ||
339 | |||
340 | <section id="offline_configuration"> | ||
341 | <title>Offline Configuration</title> | ||
342 | |||
343 | <para>The Offline Configuration subsystem is used to pre-populate a | ||
344 | configuration for a device that will be brought under management at a | ||
345 | future point in time. When creating an offline configuration store, an | ||
346 | optional<literal> Device ID</literal> can be specified - this ID | ||
347 | uniquely identifies the device to be initialized.</para> | ||
348 | |||
349 | <para>Use the GUI (shown below) launched by the <literal>Applications | ||
350 | -> Offline Config -> Add</literal> menu:</para> | ||
351 | |||
352 | <figure> | ||
353 | <title>Onboard New VNF</title> | ||
354 | |||
355 | <mediaobject> | ||
356 | <imageobject> | ||
357 | <imagedata align="center" fileref="images/offline_config.png" | ||
358 | scale="80" /> | ||
359 | </imageobject> | ||
360 | </mediaobject> | ||
361 | </figure> | ||
362 | |||
363 | <para>Specify the exact value of the <literal>Device ID</literal> in | ||
364 | the required field. This will tag the device needed for the initial | ||
365 | configuration provided by the offline configuration store. Choose | ||
366 | <literal>Merge</literal> as the Default Upload Method if you do not | ||
367 | want any boot configuration set on the device, to be wiped out. | ||
368 | Selecting <literal>Replace</literal> will set the entire device | ||
369 | configuration to match values in the offline configuration.</para> | ||
370 | |||
371 | <para>After creating the Offline Config Store, access the device | ||
372 | through <literal> Applications -> offline config -> Config | ||
373 | App</literal> and provision it with the required initial | ||
374 | configuration. This operation mirrors what happens during regular | ||
375 | offline configuration.</para> | ||
376 | |||
377 | <para>Now that the store has been provisioned successfully, it is | ||
378 | ready to send this configuration to the device when it first comes | ||
379 | online.</para> | ||
380 | </section> | ||
381 | |||
382 | <section id="initial_communications"> | ||
383 | <title>Initial Communications</title> | ||
384 | |||
385 | <para>There are two possible paths to this process, depending upon | ||
386 | whether or not NETCONF Call-Home functionality is used:</para> | ||
387 | |||
388 | <orderedlist> | ||
389 | <listitem> | ||
390 | <para>If Call-Home is not enabled/supported, the uCPE Manager | ||
391 | creates a SSH session to the device over the port configured | ||
392 | through the <literal>Add Device </literal> process (default 830). | ||
393 | It then initiates NETCONF communications over this session.</para> | ||
394 | </listitem> | ||
395 | |||
396 | <listitem> | ||
397 | <para>If the device uses Call-Home, it creates a socket connection | ||
398 | to port 4334 on the management system which runs the uCPE Manager. | ||
399 | The uCPE Manager then creates a SSH session over this socket and | ||
400 | initiates NETCONF communications as a client.</para> | ||
401 | </listitem> | ||
402 | </orderedlist> | ||
403 | |||
404 | <para>Once communications with the device have been established, the | ||
405 | Device Manager will try and connect to it.</para> | ||
406 | </section> | ||
407 | </section> | ||
408 | </section> | ||
409 | |||
410 | <section id="vnf_management"> | ||
411 | <title>VNF Management</title> | ||
412 | |||
413 | <para>As the acting vnf manager, the uCPE Manager is responsible for | ||
414 | handling the life-cycles of VNFs that are instantiated and run on the | ||
415 | various uCPE devices. The vnf manager module is written so as to be able | ||
416 | to manage multiple VNF types. Along with it is provided a generic | ||
417 | infrastructure to allow the end-user to introduce new VNF types | ||
418 | dynamically into the system. This allows for third-party VNFs to be added | ||
419 | over time to an existing network infrastructure without having to perform | ||
420 | an expensive upgrade of the vnf manager itself.</para> | ||
421 | |||
422 | <para>The process of VNF Onboarding consists of providing the system with | ||
423 | sufficient information and resources related to the VNF such that it can | ||
424 | instantiate a flavour of the VNF on the uCPE device, configure and scale | ||
425 | it as appropriate, heal and upgrade it when necessary and tear it down at | ||
426 | the right moment.</para> | ||
427 | |||
428 | <para>The vnf manager subsystem in the uCPE Manager inserts a menu item in | ||
429 | the toolbar, called <literal>VNF</literal> as shown in the screen-shot | ||
430 | below.</para> | ||
431 | |||
432 | <figure> | ||
433 | <title>VNF Management</title> | ||
434 | |||
435 | <mediaobject> | ||
436 | <imageobject> | ||
437 | <imagedata align="center" fileref="images/vnf_management.png" | ||
438 | scale="80" /> | ||
439 | </imageobject> | ||
440 | </mediaobject> | ||
441 | </figure> | ||
442 | |||
443 | <para>Selecting this menu item gives you the following options:</para> | ||
444 | |||
445 | <itemizedlist> | ||
446 | <listitem> | ||
447 | <para><literal>Descriptors</literal>: Choosing this option lets you | ||
448 | manage the VNF Descriptors catalog. The vnf manager maintains a | ||
449 | catalog of all VNFs that can be instantiated and managed by the | ||
450 | system. Before you can use a new VNF, you need to onboard it into the | ||
451 | catalog.</para> | ||
452 | </listitem> | ||
453 | |||
454 | <listitem> | ||
455 | <para><literal>Instances</literal>: Choosing this option lets you | ||
456 | instantiate (or destroy) VNFs on a given uCPE device.</para> | ||
457 | </listitem> | ||
458 | |||
459 | <listitem> | ||
460 | <para><literal>Events</literal>: Choosing this option displays all the | ||
461 | events that are related to VNF lifecycle management. Whenever a VNF | ||
462 | state changes (i.e. it is | ||
463 | created/destroyed/stopped/started/paused/resumed), a state change | ||
464 | event is generated in the uCPE Manager. The screen shown when this | ||
465 | option is chosen displays all events in the system, filtered to show | ||
466 | only VNF state change notifications.</para> | ||
467 | </listitem> | ||
468 | </itemizedlist> | ||
469 | |||
470 | <section id="onboarding_a_vnf"> | ||
471 | <title>Onboarding a VNF</title> | ||
472 | |||
473 | <para>The VNF descriptor catalog table provides a button that allows you | ||
474 | to onboard a new (third-party) VNF into the catalog.</para> | ||
475 | |||
476 | <figure> | ||
477 | <title>Onboard New VNF</title> | ||
478 | |||
479 | <mediaobject> | ||
480 | <imageobject> | ||
481 | <imagedata align="center" | ||
482 | fileref="images/onboarding_a_new_vnf.png" scale="70" /> | ||
483 | </imageobject> | ||
484 | </mediaobject> | ||
485 | </figure> | ||
486 | |||
487 | <section id="onboarding_a_vnf_wizard"> | ||
488 | <title>Onboarding a VNF VM Image using the Onboarding Wizard</title> | ||
489 | |||
490 | <para><emphasis role="bold">How to onboard a VNF into the uCPE Manager | ||
491 | using the Onboarding Wizard</emphasis></para> | ||
492 | |||
493 | <orderedlist> | ||
494 | <listitem> | ||
495 | <para>Make sure the uCPE device is added and placed on the map in | ||
496 | the uCPE Manager.</para> | ||
497 | </listitem> | ||
498 | |||
499 | <listitem> | ||
500 | <para>Select from the top toolbar <literal>VNF</literal> -> | ||
501 | <literal>Descriptors.</literal></para> | ||
502 | </listitem> | ||
503 | |||
504 | <listitem> | ||
505 | <para>Click the <literal>On-board</literal> button.</para> | ||
506 | </listitem> | ||
507 | |||
508 | <listitem> | ||
509 | <para>When prompted by the following UI, make sure the <literal>VM | ||
510 | Image</literal> radio button is selected.</para> | ||
511 | </listitem> | ||
512 | </orderedlist> | ||
513 | |||
514 | <para>If you click the <literal>VM Image</literal> radio button at the | ||
515 | top of the onboarding screen, you will get a pop-up containing fields | ||
516 | which you can fill, suppling the necessary information about the VNF. | ||
517 | After providing the information and pressing the onboard button, the | ||
518 | uCPE Manager will create the VNF package and onboard it.</para> | ||
519 | |||
520 | <figure> | ||
521 | <title>Onboard a VNF using the Wizard</title> | ||
522 | |||
523 | <mediaobject> | ||
524 | <imageobject> | ||
525 | <imagedata align="center" | ||
526 | fileref="images/onboard_a_vnf_image.png" scale="70" /> | ||
527 | </imageobject> | ||
528 | </mediaobject> | ||
529 | </figure> | ||
530 | |||
531 | <para><emphasis role="bold">Main fields</emphasis></para> | ||
532 | |||
533 | <itemizedlist> | ||
534 | <listitem> | ||
535 | <para><emphasis role="bold">VM Image File.</emphasis> This is the | ||
536 | Virtual Machine image file for the VNF itself. Typically, it is a | ||
537 | QCOW image. Press <literal>Choose File</literal> and select the | ||
538 | image to be uploaded.</para> | ||
539 | </listitem> | ||
540 | |||
541 | <listitem> | ||
542 | <para><emphasis role="bold">Image Format</emphasis>. Select the | ||
543 | format which matches the image file.</para> | ||
544 | </listitem> | ||
545 | |||
546 | <listitem> | ||
547 | <para><emphasis role="bold">VNF Type Name.</emphasis> This is the | ||
548 | name that will be used to identify this VNF. It will be shown in | ||
549 | the VNF tables.</para> | ||
550 | </listitem> | ||
551 | |||
552 | <listitem> | ||
553 | <para><emphasis role="bold">Description.</emphasis> This field | ||
554 | contains any description you want to provide. It is only displayed | ||
555 | in the GUI tables in the uCPE Manager.</para> | ||
556 | </listitem> | ||
557 | |||
558 | <listitem> | ||
559 | <para><emphasis role="bold">Version</emphasis>. This is the | ||
560 | version of the current VNF that you are hosting. It's used to | ||
561 | distinguish this VNF from other versions of the same type.</para> | ||
562 | </listitem> | ||
563 | |||
564 | <listitem> | ||
565 | <para><emphasis role="bold">Memory in MB.</emphasis> This is the | ||
566 | amount of memory (in megabytes) that will be provided to this type | ||
567 | of VNF when it is instantiated. To determine the value for this | ||
568 | field, consult the VNF vendor.</para> | ||
569 | </listitem> | ||
570 | |||
571 | <listitem> | ||
572 | <para><emphasis role="bold">Num of CPUs.</emphasis> The number of | ||
573 | CPUs that will be dedicated to an instance of this VNF when | ||
574 | created. To determine the value for this field, consult the VNF | ||
575 | vendor.</para> | ||
576 | </listitem> | ||
577 | |||
578 | <listitem> | ||
579 | <para><emphasis role="bold">Storage in GB.</emphasis> How much | ||
580 | disk space to provide an instance of this VNF. To determine the | ||
581 | value for this field, consult the VNF vendor.</para> | ||
582 | </listitem> | ||
583 | </itemizedlist> | ||
584 | |||
585 | <para><emphasis role="bold">Interfaces Tab</emphasis></para> | ||
586 | |||
587 | <figure> | ||
588 | <title>Interfaces Table</title> | ||
589 | |||
590 | <mediaobject> | ||
591 | <imageobject> | ||
592 | <imagedata align="center" fileref="images/interfaces_table.png" | ||
593 | scale="70" /> | ||
594 | </imageobject> | ||
595 | </mediaobject> | ||
596 | </figure> | ||
597 | |||
598 | <para>Click on the <literal>Interfaces</literal> tab to show the | ||
599 | Interfaces table.</para> | ||
600 | |||
601 | <para>This table will contain the interfaces required by this VNF to | ||
602 | be configured, when creating an instance. Consult the VNF vendor to | ||
603 | determine which and how many are required. Each interface requires a | ||
604 | name, and optionally a description, used by the uCPE Manager | ||
605 | only.</para> | ||
606 | |||
607 | <para><emphasis role="bold">Cloud Init Tab</emphasis></para> | ||
608 | |||
609 | <para>Click the <literal>Clout Init</literal> tab to provide the | ||
610 | Clout-Init configuration.</para> | ||
611 | |||
612 | <figure> | ||
613 | <title>Cloud-Init Tab</title> | ||
614 | |||
615 | <mediaobject> | ||
616 | <imageobject> | ||
617 | <imagedata align="center" fileref="images/cloud_init_tab.png" | ||
618 | scale="70" /> | ||
619 | </imageobject> | ||
620 | </mediaobject> | ||
621 | </figure> | ||
622 | |||
623 | <para>As shown in the picture above, there are three fields that need | ||
624 | to be populated:</para> | ||
625 | |||
626 | <orderedlist> | ||
627 | <listitem> | ||
628 | <para><emphasis role="bold">Cloud-Init | ||
629 | Datasource</emphasis></para> | ||
630 | |||
631 | <para>To onboard the VNF you must specify the<literal> Cloud-Init | ||
632 | Datasource</literal> that the VNF uses. You can get this | ||
633 | information from the VNF Vendor. Choose one of the following | ||
634 | methods to specify the datasource:</para> | ||
635 | |||
636 | <itemizedlist> | ||
637 | <listitem> | ||
638 | <para><emphasis role="bold">None</emphasis>. If there is no | ||
639 | datasource.</para> | ||
640 | </listitem> | ||
641 | |||
642 | <listitem> | ||
643 | <para><emphasis role="bold">ConfigDrive</emphasis>. This | ||
644 | method allows you to provide any number of content-data files | ||
645 | containing Cloud-Init data.</para> | ||
646 | </listitem> | ||
647 | |||
648 | <listitem> | ||
649 | <para><emphasis role="bold">NoCloud</emphasis>. This is a | ||
650 | simpler method that uses only one cloud init file | ||
651 | (User-Data).</para> | ||
652 | </listitem> | ||
653 | |||
654 | <listitem> | ||
655 | <para><emphasis role="bold">ISO</emphasis>. Pre-cooked | ||
656 | cloud-init image. This image must be created by the user | ||
657 | according to VNF requirements.</para> | ||
658 | </listitem> | ||
659 | </itemizedlist> | ||
660 | </listitem> | ||
661 | |||
662 | <listitem> | ||
663 | <para><emphasis role="bold">Cloud-Init Disk Type</emphasis></para> | ||
664 | |||
665 | <para>The <literal>Cloud-Init Disk Type </literal>field must be | ||
666 | set to either <literal>Disk</literal>, or | ||
667 | <literal>CD-ROM</literal>, depending on what the VNF requires. You | ||
668 | can get this information from the VNF Vendor.</para> | ||
669 | </listitem> | ||
670 | |||
671 | <listitem> | ||
672 | <para><emphasis role="bold">Content Files Table</emphasis></para> | ||
673 | |||
674 | <para>The <literal>Content Files Table </literal>is ONLY used if | ||
675 | you choose <literal>ConfigDrive</literal> as the Cloud-Init | ||
676 | Datasource. For each content file added, you must provide a | ||
677 | <literal>Path</literal>. When a user uses the uCPE Manager to | ||
678 | create an instance of one of these VNFs, they will be prompted to | ||
679 | provide a data file for each entry in this table. Each type of VNF | ||
680 | will require different cloud-init files, e.g.: a license | ||
681 | file.</para> | ||
682 | </listitem> | ||
683 | </orderedlist> | ||
684 | |||
685 | <figure> | ||
686 | <title>Content Files Table example</title> | ||
687 | |||
688 | <mediaobject> | ||
689 | <imageobject> | ||
690 | <imagedata align="center" | ||
691 | fileref="images/content_files_table.png" scale="70" /> | ||
692 | </imageobject> | ||
693 | </mediaobject> | ||
694 | </figure> | ||
695 | |||
696 | <para>Consult with the VNF vendor to determine what is required for | ||
697 | the VNF you are onboarding.</para> | ||
698 | |||
699 | <para><emphasis role="bold">Properties Tab</emphasis></para> | ||
700 | |||
701 | <para>In this table, you can enter values for properties that will be | ||
702 | used during instantiation of the VNF. The values will augment the | ||
703 | default values in the Domain.XML file used by libvirt/virsh (running | ||
704 | in NFV Access) when creating an instance of the VNF. These property | ||
705 | names are well known to the uCPE NFV Access software, and more will be | ||
706 | added in future versions. You will need to consult with the VNF Vendor | ||
707 | or ENEA support for values needed by specific VNFs.</para> | ||
708 | |||
709 | <figure> | ||
710 | <title>Properties Tab</title> | ||
711 | |||
712 | <mediaobject> | ||
713 | <imageobject> | ||
714 | <imagedata align="center" fileref="images/properties_tab.png" | ||
715 | scale="70" /> | ||
716 | </imageobject> | ||
717 | </mediaobject> | ||
718 | </figure> | ||
719 | |||
720 | <para><emphasis role="bold">Property Values</emphasis></para> | ||
721 | |||
722 | <para><literal>numHugePages</literal> defines the number of huge | ||
723 | memory pages the VNF uses (for DPDK).</para> | ||
724 | </section> | ||
725 | </section> | ||
726 | |||
727 | <section id="instantiating_a_vnf"> | ||
728 | <title>Instantiating a VNF</title> | ||
729 | |||
730 | <para>Once the VNF has been onboarded, you can instantiate a VNF on a | ||
731 | specific uCPE device.</para> | ||
732 | |||
733 | <para><emphasis role="bold">How to instantiate a VNF using the | ||
734 | Wizard</emphasis></para> | ||
735 | |||
736 | <orderedlist> | ||
737 | <listitem> | ||
738 | <para>Make sure the uCPE device is added and placed on the map in | ||
739 | the uCPE Manager.</para> | ||
740 | </listitem> | ||
741 | |||
742 | <listitem> | ||
743 | <para>Make sure the VNF has been onboarded into the uCPE | ||
744 | Manager.</para> | ||
745 | </listitem> | ||
746 | |||
747 | <listitem> | ||
748 | <para>Select from the top toolbar <literal>VNF</literal> -> | ||
749 | <literal>Instances</literal></para> | ||
750 | </listitem> | ||
751 | |||
752 | <listitem> | ||
753 | <para>Click the <literal>Add</literal> button.</para> | ||
754 | </listitem> | ||
755 | |||
756 | <listitem> | ||
757 | <para>When prompted by the following UI, fill the required | ||
758 | fields.</para> | ||
759 | </listitem> | ||
760 | </orderedlist> | ||
761 | |||
762 | <figure> | ||
763 | <title>Instantiating a VNF</title> | ||
764 | |||
765 | <mediaobject> | ||
766 | <imageobject> | ||
767 | <imagedata align="center" fileref="images/instantiate_a_vnf.png" | ||
768 | scale="70" /> | ||
769 | </imageobject> | ||
770 | </mediaobject> | ||
771 | </figure> | ||
772 | |||
773 | <para>There are a number of parameters to be supplied before the VNF can | ||
774 | be instantiated:</para> | ||
775 | |||
776 | <itemizedlist> | ||
777 | <listitem> | ||
778 | <para><emphasis role="bold">Name</emphasis>. The name of the | ||
779 | VNF.</para> | ||
780 | </listitem> | ||
781 | |||
782 | <listitem> | ||
783 | <para><emphasis role="bold">VNF Type</emphasis>. The name of the | ||
784 | onboarded VNF. In this case <literal>VProbe</literal> VNF.</para> | ||
785 | </listitem> | ||
786 | |||
787 | <listitem> | ||
788 | <para><emphasis role="bold">Flavour</emphasis>. The flavour of VNF | ||
789 | (as specified in the descriptor) you would like to | ||
790 | instantiate.</para> | ||
791 | </listitem> | ||
792 | |||
793 | <listitem> | ||
794 | <para><emphasis role="bold">Device</emphasis>. The uCPE device on | ||
795 | which to instantiate a VNF, i.e. the uCPE device that will run this | ||
796 | VNF.</para> | ||
797 | </listitem> | ||
798 | |||
799 | <listitem> | ||
800 | <para><emphasis role="bold">Auto-start</emphasis>. If checked, the | ||
801 | VNF will be stopped and started when unreachable. When the device | ||
802 | reports that it has lost connection to the VNF, the uCPE Manager | ||
803 | will ask the device to terminate the VM and then start it up again. | ||
804 | If unchecked, only a <literal>Disconnected</literal> notification | ||
805 | will appear in the uCPE Manager.</para> | ||
806 | </listitem> | ||
807 | </itemizedlist> | ||
808 | |||
809 | <para>Hitting the <literal>Create</literal> button will cause the VNF to | ||
810 | be instantiated and run on the specified uCPE device.</para> | ||
811 | |||
812 | <para>Selecting the<literal> VNF -> Events</literal> menu will show | ||
813 | that the VNF was created and a connection was established:</para> | ||
814 | |||
815 | <figure> | ||
816 | <title>VNF Events menu</title> | ||
817 | |||
818 | <mediaobject> | ||
819 | <imageobject> | ||
820 | <imagedata align="center" fileref="images/instantiate_a_vnf4.png" | ||
821 | scale="70" /> | ||
822 | </imageobject> | ||
823 | </mediaobject> | ||
824 | </figure> | ||
825 | </section> | ||
826 | </section> | ||
63 | </chapter> | 827 | </chapter> |