VM Image Packaging Utility
A VM image package is a TAR archive file with the root disk image and other descriptor files. This packaging method simplifies the process of a VM image registration and deployment. The attributes specified for the image enable resource requirement specification, creation of VM profiles, and a host of other properties for the VM.
The Cisco Enterprise NFVIS VM image packaging tool, nfvpt.py, helps VM owners package their VMs. The tool takes one or more qcow2 images (raw disk file) as the input file along with VM specific properties, bootstrap configuration files (if any), and generates a compressed TAR file.
Contents
The VM image packaging utility contains the following:
-
nfvpt.py—It is a python based packaging tool that bundles the VM raw disk image/s along with VM specific properties.
-
image_properties_template.xml—This is the template file for the VM image properties file, and has the parameters with default values. If the user provides new values to these parameters while creating the VM package, the default values get replaced with the user-defined values.
-
nfvis_vm_packaging_utility_examples.txt—This file contains examples on how to use the image packaging utility to package a VM image.
Usage
To get the list of parameters that can be included in the command, and to get an explanation of each of the parameters, run the help command for the tool.
nfvpt.py --help
optional arguments:
-h, --help show this help message and exit
--json JSON Provide JSON input for bootstrap variables; mutually
exclusive with custom and bootstrap configs
--newjson NEWJSON Provide JSON input for bootstrap variables; mutually
exclusive with custom and bootstrap configs
--log_dir LOG_DIR Log Directory to for logfiles
--multi_use Add options for use in multiple use-cases
--console_type_serial {true,false}
Attach the console serial to the VM; default is false;
--console_type_serial=true/false;
--root_file_disk_bus {virtio,ide}
root disk file type: --root_file_disk_bus=virtio/ide;
default is virtio
--virtual_interface_model {rtl8139}
--virtual_interface_model=rtl8139; default is none
--thick_disk_provisioning {true,false}
--thick_disk_provisioning=true; default is false
--eager_zero {true,false}
--eager_zero=true; default is false
--nocloud {true,false}
--nocloud=true/false; default is false
--bootstrap_cloud_init_bus_type {ide,virtio}
--bootstrap_cloud_init_bus_type=virtio; default is ide
--bootstrap_cloud_init_drive_type {cdrom,disk}
--bootstrap_cloud_init_drive_type=disk; default is
cdrom
--bootstrap BOOTSTRAP
Every bootstrap file should be a different option Non
HA format: --bootstrap
<mountpoint>:<file1>,<mountpoint>:<file2>... See
usage.txt for more details HA format for SDWAN
NetworkHub: --bootstrap mount_point:<value>,file:<file
2mount>[,<attrib>:<value>] mount_point:<value> and
file:<file2mount> are mandatory followed by one or
more attributes in the format <attrib>:<value>
--interface_hot_add {true,false}
VM supports interface add without power off. Default
is set to true; --interface_hot_add=true/false
--interface_hot_delete {true,false}
VM supports interface delete without power off.
Default is set to false;
--interface_hot_delete=true/false
-v, --verbose verbose
-q, --quiet quiet
--no_compress creates tar file without compressing the input files
--cleanup deletes all the input and configuration files upon tar
file created
--tablet {true,false}
: Add input device of type tablet --tablet=true/false;
--ha_package enable HA packaging
--mgmt_vnic MGMT_VNIC
VM management interface identifier
--pack_dir <DIR> PACK
package all files in directory
Required:
-o PACKAGE_FILENAME, --package_filename PACKAGE_FILENAME
[REQUIRED] file name for the target VNF package name-
default is root disk image name with extension .tar.gz
-i ROOT_DISK_IMAGE, --root_disk_image ROOT_DISK_IMAGE
[REQUIRED] List of root disk images to be bundled
example: --root_disk_image isrv.qcow2;
--root_disk_image isrv1.qcow2,isrv2.qcow2
--prop_template PROP_TEMPLATE
image properties template file name including path
default path is the current dir of the tool and name
is image_properties_template.xml if the user doesn't
input this option example: --prop_template
/usr/bin/image_properties_template.xml
-t VNF_TYPE, --vnf_type VNF_TYPE
[REQUIRED] VNF type, e.g. ROUTER, FIREWALL, vWAAS,
vWLC, and OTHER
-n NAME, --vnf_name NAME
[REQUIRED] Name of the VNF image
-r VNF_VERSION, --vnf_version VNF_VERSION
[REQUIRED] VNF version, e.g. --vnf_version 1.0 or
--vnf_version 0.9
--app_vendor APP_VENDOR
Application Vendor e.g. Cisco, Juniper etc
--monitored {true,false}
[REQUIRED] Monitored VNF: --monitored=true/false;
--optimize {true,false}
[REQUIRED] optimized VM: --optimize=true/false;
HA options:
--ha_capable
--ha_vnic HA_VNIC VM HA vnic
--ha_vnic_count HA_VNIC_COUNT
Number of ha_vnics
Resources:
Resources: min and max - vCPU, memory and disk
--min_vcpu VCPU_MIN min #vCPU : min number of vCPU supported by VM
example:--min_vcpu 2
--max_vcpu VCPU_MAX max #vCPU : max number if vCPU required for VM
example:--max_vcpu 4
--min_mem MEMORY_MB_MIN
min mem : min mem in MB required for VM
example:--min_mem 1024
--max_mem MEMORY_MB_MAX
max mem : max mem in MB required for VM
example:--max_mem 4196
--min_disk ROOT_DISK_GB_MIN
min disk : min disk in GB required for VM
example:--min_disk 8
--max_disk ROOT_DISK_GB_MAX
max disk : max disk in GB required for VM
example:--max_disk 8
--vnic_max VNIC_MAX max number of Vnics allowed for VM example:--vnic_max
8
--vnic_names VNIC_NAMES
list of vnic number to name mapping in format
number:name example --vnic_names
1:GigabitEthernet2,2:GigabitEthernet4
Profile Options:
--profile PROFILE enter the profile name, profile description, no of
vCPU required, min memory required in MB, min disk
space required in MB, example: --profile
profile1,"This is profile 1",2,2048,4096 --profile
profile2,"This is profile 2",4,4096,4096
--default_profile DEFAULT_PROFILE
default profile
Driver Support Options:
--sriov {true,false} Enable/Disable SRIOV support: --sriov=true/false;
default is false
--sriov_list SRIOV_DRIVER_LIST
list of SRIOV drivers example: --sriov_list
igb,igbvf,i40evf
--pcie {true,false} Not supported
--pcie_list PCIE_DRIVER_LIST
Not supported
Privilege/Priority Options:
--privileged {true,false}
Not supported
Custom Properties:
--custom CUSTOM custom properties format: --custom ["propattr_"<attr>:
<value>],key:<value>,[keyattr_<attr>:<value>],type:<va
lue>,val<N>:<value>,[val<N>attr_<attr>:<value>] Allows
specification of custom properties: 0 or more
propattr_<attr>:<value> pairs - 'propattr' is a
keyword and used to specify property attributes
key:<value> pairs 0 or more keyattr_<attr>:value pairs
- 'keyattr' is a keyword and is used to specify key
attributes type:<value> pair - type of value
valN:<value> pair - val1:value,val2:value etc 0 or
more valNattr_<attr>:<value> pairs - 'val<N>attr' is
an attribute for val<N> See usage_examples.txtThe table lists the parameters that can be passed to the nfvpt.py command.
|
Parameter |
Mandatory/Optional |
Description |
|---|---|---|
|
version |
Not applicable |
Show program's version number and exit. |
|
help |
Not applicable |
Show this help message and exit. |
|
package_file_name |
Mandatory |
File name for the target VNF package. The default is the root disk image name with extension .tar.gz. |
|
disk_img_names |
Mandatory |
List of root disk images to be bundled. Only the qcow2 images are supported. |
|
img_name |
Mandatory |
Name of the VNF image. |
|
vnf_type |
Mandatory |
VNF type Supported types are: ROUTER, FIREWALL, vWAAS, vWLC, and OTHER. |
|
vnf_version |
Mandatory |
VNF version |
|
monitored |
Mandatory |
VM health monitoring for those VMs that can be bootstrapped Options are: true/false Monitoring timeout period for a monitored VM is 600 seconds by default |
|
optimize |
Mandatory |
Optimized VM Options are: true/false |
|
virtual_interface_model |
Optional |
Default is none. |
|
thick_disk_provisioning |
Optional |
Default is false. |
|
eager_zero |
Optional |
Default is false. |
|
bootstrap_cloud_init_bus_type |
Optional |
Default is IDE. |
|
bootstrap_cloud_init_drive_type |
Optional |
Mounts the day0 configuration file as disk Default is CD-ROM. |
|
bootstrap |
Optional |
Bootstrap files for VNF. Two parameters are required in the format of dst:src; dst filename including path has to match exactly to what the VM expects; up to 20 bootstrap files are accepted. For example: --bootstrap ovf-env.xml for ISRv and --bootstrap day0-config for ASAv. |
|
min_vcpu |
Optional |
Minimum number of vCPUs supported by the VM. The default is 1. |
|
max_vcpu |
Optional |
Maximum number of vCPUs required for the VM. The default is 8. |
|
min_mem |
Optional |
Minimum memory in MB required for the VM. The default is 4 GB. |
|
max_mem |
Optional |
Maximum memory in MB required for the VM. Physical memory: 2 GB The default is 8 GB. |
|
min_disk |
Optional |
Minimum disk in GB required for the VM. The default is 8 GB. |
|
max_disk |
Optional |
Maximum disk in GB required for the VM. Available disks are SSD and HDD: 15 GB The default is 16 GB |
|
vnic_max |
Optional |
Maximum number of VNICs allowed for the VM. The default is 8. |
|
profile |
Optional |
The profile name, profile description, number of vCPUs required, minimum memory required in MB and minimum disk space required in MB. |
|
default_profile |
Optional |
The default profile. |
|
sriov |
Optional |
Enable or disable SRIOV support. The default is false. |
|
sriov_list |
Optional |
List of SRIOV drivers. |
|
pcie |
Optional |
Not supported. |
|
pcie_list |
Optional |
Not supported. |
|
privileged |
Optional |
Not supported. |
|
custom |
Optional |
Custom properties to be supported and/or passed to the bootstrap configuration with tokenized variables. This is only used for the local portal to display options for the user to choose while deploying. |
|
pack_dir |
Optional |
package all files in directory |
NFVIS Specific Enhancements
 Note |
Use pack_dir option if the *.tar.gz already exists and you want to modify the bootstrap configuration file or image_properties.xml manually. |
The following parameters are added as part of the NFVIS specific enhancements:
--pack_dir <DIR> PACK
package all files in directory
Resources:
--vnic_names VNIC_NAMES
list of vnic number to name mapping in format
number:name example --vnic_names
1:GigabitEthernet2,2:GigabitEthernet4
Usage
Follow the steps to change a single line in day-0 configuration file or add a single option in image_properties.xml:
-
Get the working VM packaging image - isrv*.tar.gz.
-
Extract the contents - tar -xvf isrv*.tar.gz.
-
Modify the file contents as required.
-
nfvpt.py --pack_dir current-working-dir-with-files -i isrv.qcow2 -o isrv.tar.gz
VM Packaging Utility Usage Examples
Given below are the contents of the file nfvis_vm_packaging_utility_examples.txt:
Example 1: Usage for TinyLinux
nfvpt.py -o TinyLinux -i TinyLinux.qcow2 -n TinyLinux -t linux -r 1.0 --monitored false
--min_vcpu 1 --max_vcpu 2 --min_mem 1024 --max_mem 1024 --min_disk 1 --max_disk 2
--vnic_max 1 --optimize false
Example 2: Usage for ASAv
Note |
The bootstrap filename has to be day0-config. This cannot be modified as ASAv looks for the exact filename. |
nfvpt.py -o asav961-201 -i asav961-201.qcow2 -n ASAv -t firewall -r 961-201 --monitored true --bootstrap day0-config:filename1
--min_vcpu 1 --max_vcpu 4 --min_mem 1024 --max_mem 8192 --min_disk 8 --max_disk 16 --vnic_max 8 --optimize true
--profile ASAv5,"ASAv5 profile",1,1024,8192 --profile ASAv10,"ASAv10 profile",1,4096,8192 --profile ASAv30,"ASAv30 profile",4,8192,16384
--default_profile ASAv5
Example 3: Usage for ISRv
Note |
The bootstrap filename has to be ovf-env.xml . This cannot be modified as ISRv looks for the exact filename. |
nfvpt.py -o isrv.16.03.01 -i isrv-universalk9.16.03.01.qcow2 -n ISRv.16.03.01 -t ROUTER -r 16.03.01 --monitored true --privileged true
--bootstrap ovf-env.xml:file1,ios-xe.txt:file2 --min_vcpu 2 --max_vcpu 8 --min_mem 4096 --max_mem 8192 --min_disk 8 --max_disk 8
--vnic_max 8 --optimize true --profile ISRv-small,"ISRv small profile",2,4096,8192 --profile ISRv-medium,"ISRv medium profile",4,4096,8192
--default_profile ISRv-small --sriov_list igb,igbvf,i40evf --custom tech_package,ax
nfvpt.py -o test.1.0 -i test-1.0.qcow2 -n TEST -t OTHER -r 1.0 --monitored true --privileged true
--bootstrap /:bootstrap.xml,/license/lic.txt:license.txt --min_vcpu 2 --max_vcpu 8 --min_mem 4096 --max_mem 8192
--min_disk 8 --max_disk 8 --vnic_max 8 --optimize true --profile small,"small profile",2,4096,8192
--profile medium,"medium profile",4,4096,8192 --default_profile small
In this case, test.1.0.pkg : bootstrap.xml gets mounted as bootstrap.xml at the root, and the license.txt gets mounted as /license/lic.txt.
Example 5: Usage for Palo Alto Firewall
nfvpt.py -o PA_L3_HA -i PA-VM-KVM-8.0.5.qcow2 --json d.json -t firewall -n "PA FIREWALL" -r 8.0.5 --app_vendor PA --monitor true --ha_package
Example 6: Usage for Asav
nfvpt.py -i foo.qcow2 -o asav.tar.gz --json pa1.json --app_vendor cisco -t firewall -r 10 --optimize true -n asav --monitored true --ha_package —ha_capable
Example 7: Usage for csr
nfvpt.py --ha_package --pack_dir /data/intdatastore -i csr1000v-universalk9.16.09.01.qcow2 -o csr1000v-universalk9.16.09.01-ha.tar.gz
Feedback