Tutorial: Build sample VM type IOx app

In this tutorial, we will go through quick start guide on how to build a sample VM type application using a Kernel-based Virtual Machine (KVM) Type 2 hypervisor (such as VMWare, VMWarePlayer, VMWare Fusion, Virtual-box) development environment and package it to an IOx application. For more details on what are the different types of IOx application supported, refer this section.

Requirements

Supported development environment architecture for ioxclient tool
- amd64
- darwin_386 (MACOS 10)
- darwin_amd64
- linux_386
- linux_amd64
- windows_386
- windows_amd64
Selected VM guest-os is hardware compatible with the targeted platform hardware (eg Intel x86_64)
VM guest-os, max system file size, and required system memory do not exceed the maximum targeted platform hardware limits.

Setup Type 2 KVM Hypervisor Development Environment

The end goal is to have a KVM virtual machine with applications (or capable of downloading and running application) that can be installed on a Cisco platform that supports IOx. Refer to the specific platforms limits defined for VM applications for supported disk space, system memory size and vcpu allotments. To build a KVM virtual machine requires a Linux development environment with about 2GB more RAM than what is needed for the KVM virtual machine, and disk space double the size of the KVM virtual machine plus 15GB. In other words 6GB RAM and 55GB disk space would be adequate for an example KVM that requires 4GB RAM with 20GB of disk space.
If developing on a PC or Mac, the Linux development environment can be installed on the laptop using one of the below choices (this is the preferred development method) :

Build the VM Application

After the Hypervisor Development environment is setup, the next step is to build the VM application. Typical steps in building a VM within a KVM Hypervisor:

Use VM Manager hypervisor installed from one of the choices above to create a VM from an ISO file. The ISO file typically is the required complete guest-os which may be a linux or non-linux (eg Windows) based OS. Installation steps are hypervisor specific, so consult the above links for details.
Customize and add applications, libraries, tools, VM kernel specific drivers/features, etc to the VM.
Verify the VM application is functioning correctly using the VM development environment.

Add Required IOx Support Tools To VM

IOx requires specific services to be installed and running after bootup in the Application's VM.

Install required qemu "qemu-guest-agent" tools for Fog Director (FD) statistic gathering support. Fog Director periodically polls the IOx applications for various application's CPU, memory, disk usage and other resource metrics which the "qemu-guest-agent" tool provides.

For more details: qemu guest agent

Install commands for the given Linux distributions:

Debian, Ubuntu :
apt-get install qemu-guest-agent

Fedora/CentOS :
yum install qemu-guest-agent

Alpine :
apk add qemu-guest-agent

Optimize the Size of the VM

To reduce the size of the vm, any unused diskspace should be zero'ed out to maximize compression. Below are the steps to do this which should be done as the last modification to VM before IOX packaging:
1. From a Linux guest, fill all free space with zeroes by creating a file consisting of all zeroes.
```
dd if=/dev/zero of=~/mytempfile
```
1. Delete the zero-filled file to restore the unused disk space.
```
rm -f ~/mytempfile
```

Build the IOx Application Package

Once the KVM is operational, a KVM .vmdk file (VMware virtual DisK) is created. The KVM's virtual disk that contains the KVM's root filesystem. A simple step in repackaging the KVM's vmdk file to an IOx compatible package is required:

Locate the KVM's .vmdk file:
1. Certain Hypervisor's support an "export" feature to create an *.ova image of the VM. The *.ova file is a tarfile of various files required for the KVM image. A *.vmdk file is one of those files tarred into the *ova. The vmdk file can be extracted from the ova image using:
  
  tar -xvf FILENAME.ova
2. If the hypervisor tool does not provide the convenient "export" ova feature, you will have to search on your development server's harddisk where the corresponding *.vmdk is saved.
  For example, VMware Workstation Player for Windows saves the KVM vmdk file under C:\Users<USERID>"My Documents""Virtual Machines"<KVM-APPNAME>\KVM-APPNAME.vmdk .
  Refer to the hypervisor documentation for details.
Convert KVM vmdk image to IOx Packaging steps: The KVM generated vmdk file created by the hypervisor tool and located above needs to be converted to qcow2 file format required for IOx packaging by following the below steps:
Copy the KVM vmdk file to the build platform that has the "ioxclient" tool installed.
Convert VMDK to QCOW2
1. install required qemu-utils tool in IOX build setup:
  
  Install commands for the given Linux distributions: Debian, Ubuntu :
  apt-get install qemu-utils
  
  Fedora/CentOS :
  yum install qemu-utils
  
  Alpine :
  apk add qemu-utils
2. Convert VM image to a new QCOW2 output file:
  
  qemu-img convert -c -O qcow2 .vmdk .qcow2

 Example:
 ```
 bash:~/KVM$ qemu-img convert -c -O qcow2 KVM-disk1.vmdk KVM-disk1.qcow2
 bash:~/KVM$ ls -alt
 total 1317044
 -rw-r--r--  1 cisco cisco 281739264 May  3 13:47 KVM-disk1.qcow2
 -rwxr-xr-x  1 cisco cisco 785842176 Mar 20 18:36 KVM-disk1.vmdk

 ```

Create IOx package descriptor file
IOx package descriptor file contains metadata about the application, minimum resource requirements for running the application. Refer this section for more detailed description of various attributes and schema for package descriptor contents. Change the ostype attribute value under startup section to linux for Linux distro VM app. Note: Specify vnc attribute in the graphics section of the yaml to be able to access the VM via a VNC session. Copy below contents into a file called package.yaml.

NOTE:

Be sure to specify the exact same .qcow2 filename created above for the package.yaml "file:" attributed.

Example KVM package.yaml:

descriptor-schema-version: "2.4"

info:
  name: hello world 
  description: "Hello world VM type application"
  version: "1.0"
  author-link: "http://www.cisco.com"
  author-name: "Cisco Systems"

app:
  type: vm
  cpuarch: x86_64
  resources:
    profile: custom
    cpu: 200
    memory: 64
    disk: 2

    network:
      -
        interface-name: eth0
    graphics:
        vnc: true
  # Specify runtime and startup
  startup:
    ostype: windows
    disks:
      -
        target-dev: "hdc"
        file: "KVM-disk1.qcow2"

    qemu-guest-agent: True

NOTE: if "qemu-guest-agent" is not installed, set "qemu-guest-agent: False".

Create final IOx application package
Download and install latest version of ioxclient for your development environment from this location. Setup ioxclient device profile by configuring device IP, credentials and SSH port. Refer to Section "Configuring ioxclient" in "ioxclient Reference" for details.

bash$ ioxclient profiles create

Use below ioxclient command to build final IOx application package named package.tar. Prepend sudo if the ioxclient command fails due to permission restrictions.

ioxclient package command to generate IOX App.tar file in the output-dir :
ioxclient package --name
where is the directory that contains:

package.yaml
converted qcow2 rootfs generated above

bash$ ~/KVM/output-dir$ ls -alt
-rw-rw-r-- 1 cisco cisco        514 Oct  4 10:47 package.yaml
-rw-r--r-- 1 cisco cisco 1132194816 Oct  4 10:47 KVM-disk1.qcow2
                                                                                
bash$ cd ~/KVM
bash$ ioxclient package --name kvm output-dir

bash$ ls -alt output-dir
-rw-r--r-- 1 cisco cisco 1159280113 Oct  4 10:54 kvm.tar
-rw-rw-r-- 1 cisco cisco        514 Oct  4 10:47 package.yaml
-rw-r--r-- 1 cisco cisco 1132194816 Oct  4 10:47 KVM-disk1.qcow2

The final application tarfile is generated in the "output-dir" as "kvm.tar".

Deploy/Activate/Start the application

Now you can deploy the application onto a physical or virtual IOx device using either of the clients ioxclient or Local Manager or Fog Director. You can access device Local Manager UI using the URL path https://:8443 or https://:443. Let's use ioxclient to deploy this application to a device. Execute below ioxclient commands to setup device profile, install, activate and start the application. Note that if the application is activated using ioxclient, an activation payload that consists of VNC password and port number should be passed. Use these details in the VNC client that you use to access the app. Port number is optional. A port number is automatically assigned if it is not specified in the activation payload. Valid port numbers are 5900 through 65535. An example of activation payload activation.json:

{"resources":{"profile":"custom","network":[{"interface-name":"eth0","network-name":"iox-nat0"}],"cpu":200,"memory":64,"vcpu":"1","disk":"2","graphics":{"vnc":true,"vnc-password":"cisco123","port":"6665"}}}

Refer profiles and app management for more ioxclient details. Note: Here we are using default attributes for application activation.

bash$ ioxclient app install helloworld_app kvm.tar

bash$ ioxclient app activate helloworld_app --payload activation.json

bash$ ioxclient app start helloworld_app

Verify the application is running

Using a VNC Client like the default vnc on Mac and Remmina Desktop Client on Ubuntu, provide the IP address of the device and the VNC port that was specified in the activation payload and press Connect. This should start a VNC session and allow access to the VM application. On MAC OS,

$ open vnc://172.27.103.169:6665

The above command opens up a dialog that requests for VNC password. This is the VNC password that was input using the activation payload or the LM activation page:

VM Application MAC

On Ubuntu,

VM Application Ubuntu

Once the password is entered, you should be logged into the VM as below:

VM Application Session