VM life cycle management

VM image upload methods

You can upload VM images to an NFVIS server in these ways:

• Copy the images from your local system to the NFVIS server—Use the Image Upload option from the Cisco NFVIS portal.

• Copy using the scp command (scp username@external_server:/path/image.tar.gz intdatastore:image.tar.gz).

Image registration characteristics

Image registration is a one-time activity. Once an image is registered on the http or https server and is in active state, you can perform multiple VM deployments using the registered image. All VM images are available in VM packaging and VM package content.

VM profile creation methods

VM profiles are created using different methods depending on the image package type:

• Flavors are created as part of image registration if you use the tar.gz image packages for registering a VM.

• For other image packages such as .qcow2, iso, and raw, you must define custom flavors based on your requirements.

Note

Unless specified otherwise in the deployment payload, the value assigned to the custom image property default_profile is used at the time of deploying the VM. Only applicable to tar.gz image packages.

Default configuration behavior

Here's an example of the default int-mgmt-net configuration:

vm_lifecycle networks network int-mgmt-net
 subnet int-mgmt-net-subnet
  address 10.20.0.0
  netmask 255.255.255.0
  gateway 10.20.0.1
 !
!

You can update the default configuration before deploying VMs/VNFs. When the default config is deleted, Cisco NFVIS recreates the internal management network upon rebooting the host.

VNF deployment monitoring: Cisco NFVIS lets you configure the VNF deployment to be monitored. To monitor the VM deployment, an interface is attached to the internal management network (int-mgmt-net). The interface attached contains the NIC ID 0 by default.

Here is a sample day-0 config with the IP address and the token/variable:

<?xml version="1.0" encoding="UTF-8"?>
<Environment
xmlns:oe="http://schemas.dmtf.org/ovf/environment/1">
  <PropertySection>
    <Property oe:key="com.cisco.c8000v.config-version.1" oe:value="1.0"/>
    <Property oe:key="com.cisco.c8000v.enable-ssh-server.1" oe:value="True"/>
    <Property oe:key="com.cisco.c8000v.login-username.1" oe:value="${SSH_USERNAME}"/>
    <Property oe:key="com.cisco.c8000v.login-password.1" oe:value="${SSH_PASSWORD}"/>
    <Property oe:key="com.cisco.c8000v.mgmt-interface.1" oe:value="GigabitEthernet1"/>
!!!GigabitEthernet1-nicid(0)-int-mgmt-interface-don't change ip address or don't shutdown
    <Property oe:key="com.cisco.c8000v.mgmt-ipv4-addr.1" oe:value="${NICID_0_IP_ADDRESS}/${NICID_0_CIDR_PREFIX}"/>         ===> IP address set via token
    <Property oe:key="com.cisco.c8000v.mgmt-ipv4-network.1" oe:value=""/>
    <Property oe:key="com.cisco.c8000v.license.1" oe:value="${TECH_PACKAGE}"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0001" oe:value="vrf definition Mgmt-intf"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0002" oe:value="address-family ipv4"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0003" oe:value="exit-address-family"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0004" oe:value="address-family ipv6"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0005" oe:value="exit-address-family"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0006" oe:value="exit"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0007" oe:value="interface GigabitEthernet1"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0008" oe:value="vrf forwarding Mgmt-intf"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0009" oe:value="ip address ${NICID_0_IP_ADDRESS} ${NICID_0_NETMASK}"/>   ===> IP address set via token
    <Property oe:key="com.cisco.c8000v.ios-config-0010" oe:value="no shut"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0011" oe:value="exit"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0012" oe:value="ip route vrf Mgmt-intf 0.0.0.0 0.0.0.0 ${NICID_0_GATEWAY}"/>
  </PropertySection>
</Environment>

Here is a sample day-0 config using DHCP server:

<?xml version="1.0" encoding="UTF-8"?>
<Environment
xmlns:oe="http://schemas.dmtf.org/ovf/environment/1">
  <PropertySection>
    <Property oe:key="com.cisco.c8000v.config-version.1" oe:value="1.0"/>
    <Property oe:key="com.cisco.c8000v.enable-ssh-server.1" oe:value="True"/>
    <Property oe:key="com.cisco.c8000v.login-username.1" oe:value="${SSH_USERNAME}"/>
    <Property oe:key="com.cisco.c8000v.login-password.1" oe:value="${SSH_PASSWORD}"/>
    <Property oe:key="com.cisco.c8000v.mgmt-interface.1" oe:value="GigabitEthernet1"/>
!!!GigabitEthernet1-nicid(0)-int-mgmt-interface-don't change ip address or don't shutdown
    <Property oe:key="com.cisco.c8000v.mgmt-ipv4-addr.1" oe:value=""/>                                      ===> IP address left blank here
    <Property oe:key="com.cisco.c8000v.mgmt-ipv4-network.1" oe:value=""/>
    <Property oe:key="com.cisco.c8000v.license.1" oe:value="${TECH_PACKAGE}"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0001" oe:value="vrf definition Mgmt-intf"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0002" oe:value="address-family ipv4"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0003" oe:value="exit-address-family"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0004" oe:value="address-family ipv6"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0005" oe:value="exit-address-family"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0006" oe:value="exit"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0007" oe:value="interface GigabitEthernet1"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0008" oe:value="vrf forwarding Mgmt-intf"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0009" oe:value="ip address dhcp setroute"/>               ===> DHCP specified vs IP address
    <Property oe:key="com.cisco.c8000v.ios-config-0010" oe:value="no shut"/>
    <Property oe:key="com.cisco.c8000v.ios-config-0011" oe:value="exit"/>
  </PropertySection>
</Environment>

Port forwarding configuration

The bridge interface that is used to redirect traffic coming from the WAN side can be modified using the source_bridge tag in the deployment payload as shown in this example:

<port_forwarding>
  <port>
  <type>ssh</type>
  <protocol>tcp</protocol>
  <vnf_port>22</vnf_port>
  <source_bridge>MGMT</source_bridge>
  <external_port_range>
    <start>20122</start>
    <end>20122</end>
  </external_port_range>
  </port>
</port_forwarding>

With this payload, the traffic coming from the WAN side is redirected through the management interface (MGMT) instead of the default WAN bridge (WAN-br) interface.

vCPU pinning configuration

Similar to the NFVIS VM model, containers can also be pinned to a specific vCPU. If a container requires a dedicated core, a low latency flag can be set using the configuration options. By default, no low latency flag is set, this means that the core may be shared with other containers. Because the workflow for container vCPU pinning is the same as VM deployments, VimManager reuses the Node.js CPU allocation API to interface with the NFVIS CPU allocation scripts.

Volumes support for container deployments uses the same datamodel as VM deployments and provides external storage options to the containers. The storage_location tag in the payload refers to the file path within the container where the volume is mounted.

Note

• Volumes are equivalent to docker binds.

• All container volumes are stored on datastore1.

Example: Container volume configuration

To mount a container using a volume or a specific path, use this configuration:

<vm_group>
    <name>docker-nginx</name>
    <image>nginx</image>
    . . .
    <volumes>
      <volume>
        <name>test1</name>
        <volid>1</volid>
        <storage_location>/etc/datastore</storage_location> <!-- the path to mount inside the container -->
        <size>120</size>
        <sizeunit>MiB</sizeunit>
      </volume>
      <!-- using default size allocations - 10 gibibytes (GiB) -->
      <volume>
        <name>test2</name>
        <volid>2</volid>
        <storage_location>/var/logs</storage_location>
      </volume>

For more information, see VNF volumes.

VM name requirements

The VM name must meet these requirements:

• Must contain an uppercase character and a lowercase character.

• Must contain a digit.

• Must contain one of the following special characters: dot (.), underscore (_) and hyphen (-).

• Must not have more than 256 characters.

Note

Ensure that you have registered a VM image before attempting to deploy it. For more details, see Image Registration.

Bootstrap configuration methods

You can include the bootstrap configuration (day zero configuration) of a VM in the VM deployment payload in these ways:

• Bundle bootstrap configuration files into the VM package: In this method, the bootstrap configuration variables can be assigned tokens. Token names must be in bold text. For each variable with a token assigned, key-value pairs must be provided during deployment in the deployment payload.

• Bootstrap configuration as part of the deployment payload: The entire bootstrap configuration is copied to the payload without tokens.

• Bootstrap configuration file in the NFVIS server: In this method, the configuration file is copied or downloaded to the NFVIS server, and referenced from the deployment payload with the filename, which includes the full path.

For examples on how to use bootstrap configuration options in the deployment payload, see the API Reference for Cisco Enterprise Network Function Virtualization Infrastructure Software.

Placement configuration requirements

See VNF Deployment Parameters for more information on supported placement parameters and their accepted values.

Note

If you are placing the VNF deployment on nfs, ensure that you have configured this storage option to be mounted on NFVIS using appropriate CLIs before deploying the VNF.

Example: VM deployment using placement

curl -k -v -u admin:admin -H Accept:application/vnd.yang.data+xml -H 
Content-Type:application/vnd.yang.data+xml -X POST https://209.165.201.1/api/config/vm_lifecycle/tenants
/tenant/admin/deployments --data
'<deployment>
<name>WINIsodep</name>
<vm_group>
		<name>WINIsovmgrp</name>
		<image>WinServer2012R2.iso</image>
		<flavor>windows</flavor>
		<bootup_time>-1</bootup_time>
		<recovery_wait_time>0</recovery_wait_time>
		<kpi_data>
		 <enabled>true</enabled>
		</kpi_data>
	  <scaling>
		 <min_active>1</min_active>
		 <max_active>1</max_active>
		 <elastic>true</elastic>
	  </scaling>
	  <placement>
		 <type>zone_host</type>
		 <enforcement>strict</enforcement>
		 <host>datastore1</host>
	  </placement>
	  <recovery_policy>
		 <recovery_type>AUTO</recovery_type>
		 <action_on_recovery>REBOOT_ONLY</action_on_recovery>
	  </recovery_policy>
</vm_group>
</deployment>'

Container deployment restrictions and capabilities

NFVIS container deployment has the following restriction:

• Import and export of containers is not supported.

The container deployment process in container lifecycle management supports the following features:

• SRIOV/Host Interface

• Day 0 Configuration

• Configuration Options

• vCPU Pinning

• Volumes

SRIOV/Host interface configuration

To attach an SRIOV or host interface to the container's interface, specify the SRIOV or host interface in the configuration. Either physical interfaces or SRIOV VFs can be specified in the configuration.

To attach an SRIOV or host interface to the container's interface, use this configuration:

<?xml version="1.0" encoding="UTF-8"?>
<vm_lifecycle xmlns:ns0="http://www.cisco.com/nfvis/vm_lifecycle" xmlns="http://www.cisco.com/nfvis/vm_lifecycle">
    <tenants>
        <tenant>
            <name>admin</name>
            <deployments>
                <deployment>
                    <name>ubuntu-2</name>
                    <vm_group>
                        ...
                        <interfaces>
                            <interface>
                                <nicid>0</nicid>
                                <network>int-LAN-vf-1</network>
                            </interface>
                        </interfaces>
                    </vm_group>
                </deployment>
            </deployments>
        </tenant>
    </tenants>
</vm_lifecycle>

Day 0 configuration

Day 0 support for container deployments follows the same process as that of VM deployments. Refer to VM Bootstrap Configuration Options with a VM Deployment.

Configuration options setup

There are multiple boot options available, that allow you to customize the container behavior.

To customize the container behavior using different configuration options, use this configuration:

<config_data>
  <config_type>CONFIG_DATA_OPTIONS</config_type> <!-- type is required or options below are ignored -->
  <config_options>
    <options>
      <option><name>ENV_VARIABLE</name><value>env=test</value></option>
      <option><name>ENV_VARIABLE</name><value>env2=test2</value></option>
    </options>
  </config_options>
  <configuration>
     <dst>/etc/ovf-env.xml</dst>
     . . .

Hot and cold update methods

All the options related to updating interfaces can be done in two ways: hot or cold.

Hot Update: Hot update refers to an update operation that runs when a VM is in ACTIVE STATE. In such cases, the VM does not reboot during the update.

Cold Update: Cold update refers to an update operation that runs after a VM is put in a VM_SHUTOFF_STATE. In such cases, the VM reboots during the update.

Note

The need to do a hot or cold update depends on the custom image properties set during image registration. Refer to the table below for various custom image properties related to hot and cold updates.

Custom Image Property	Value	Interface Update Description	Default Value
interface_hot_add	true	Hot add an interface to a VM	true
interface_hot_add	false	Cold add an interface to VM
interface_hot_delete	true	Hot delete a VM interface	false
interface_hot_delete	false	Cold delete a VM interface

Starting from ISRv 17.1, interface_hot_add and interface_hot_delete are set to true by default.

The VNF interface update prerequisites are:

• The VNF should support hot add or hot delete operations for the interface.

• The custom image properties for interface update should be set during image registration to allow values other than the default.

• The VM to be updated needs to be in one of the following states: VM_ALIVE_STATE, VM_ERROR_STATE or VM_SHUTOFF_STATE.

This table shows which hot interface update operations are supported for various interface types.

Note

NFVIS also supports moving VNICs from one interface to another. For example, you can move a VNIC from a VIRTIO interface to SRIOV, or from SRIOV to DPDK, and so on.

If the VNIC is updated to a different interface type like SRIOV or DPDK, the configuration of the VNIC will not be preserved.

Syslog is not generated in ISRv when an interface is updated from a DPDK enabled network to another DPDK enabled network.

Interface update of any SRIOV interface to remove from one interface and add the same to another or swap, in a single transaction fails. Use two separate requests for a successful update.

VM monitoring configuration details

VM monitoring behavior is controlled through specific settings and parameters:

• If the bootup_time is set at -1, it signifies that VM monitoring is disabled.

• You are not required to set a boot up time during image registration. However, you must set it during VM deployment.

• If a qcow2 image is used during registration, the bootup_time defaults to -1.

Disabling VM monitoring

This example shows how to disable monitoring for a VM.

curl -k -v -u "admin:password" -H 
"Accept:application/vnd.yang.data+xml" -H 
"Content-Type:application/vnd.yang.data+xml" -X POST 
https://<NFVIS_IP>/api/operations/vmAction --data '<vmAction>
<actionType>DISABLE_MONITOR</actionType><vmName><vm-instance name></vmName></vmAction>'

VM export and import limitations

VM export and import operations have specific requirements and limitations:

• The imported VM cannot change datastore.

• The original registered image must exist.

• The OVS network name must be identical to the one used by original deployment.

• VM export is dependant on the amount of free space available in the deployed datastore, regardless of the free space available in the destination datastore. For example, when the VM is deployed in the intdatastore (default), you should ensure that the available free space is at least twice that of the deployed VM.

To export a VM ensure that:

• Backup file must be saved to NFVIS datastore or USB.

• Provide a backup name for NFVIS to append .vmbkp extension to the backup name.

You can only create and save a VM backup to datastores. The backup file has .vmbkp extension. To verify the backup:

nfvis# show system file-list disk local | display xpath | include backup

/system/file-list/disk/local[si-no='84']/name tiny_backup.vmbkp
nfvis# show system file-list disk local 84
SI NO  NAME               PATH                SIZE  TYPE               DATE MODIFIED
--------------------------------------------------------------------------------------------
84     tiny_backup.vmbkp  /mnt/extdatastore1  17M   VM Backup Package  2019-01-31 19:31:32

To import a VM ensure that:

• The Backup file is placed under NFVIS datastores or USB.

• The registered image used by the original deployed VM is in the same datastore, with same properties.

• The exported VM does not exist on the system.

• OVS network used by the original deployment should exist.

• Restored VM is created with the same datastore with same deployment properties.

• The full path name to backup file is used (for example, /mnt/extdatastore1/backup.vmbkp, not extdatastore1:backup)

nfvis# vmImportAction importPath /mnt/extdatastore1/tiny_backup.vmbkp
System message at 2019-01-31 19:53:32...
Commit performed by admin via ssh using maapi.

An optional unique MAC UID support is added to VM import.

vmImportAction importPath <vm backup file with location> uniqueMacUid

Specifying the uniqueMACUid flag ensures that the imported VM is not deployed with the same UID and interface MAC addresses.

VM backup using vmExportAction:

Export and import failures

These examples show export failures:

• Original deployment is not deleted

  
  nfvis# vmImportAction importPath /mnt/extdatastore1/tiny_backup.vmbkp
  Error: Exception from action callback: Deployment Configuration : 'SystemAdminTenantIdtiny' already exists , can not be imported/restored due to conflict!
  
  

• OVS network used by original deployment is deleted.

  
  nfvis# vmImportAction importPath /mnt/extdatastore1/tiny_backup.vmbkp
  Error: Exception from action callback: Restoration Request rejected, see logs for root cause
  
  

VM restore using vmImportAction: