Contents

Introduction

Prerequisites

Windows/ MAC Intel/ Linux

MAC ARM Based - M1/M2/M3

Procedure to Set Up Build Environment Using Vagrant

Summary of Actions

Procedure to Build a Custom IOx Application

Deploy the IOx Application

Troubleshoot

Introduction

This document describes how to build IOx applications using Vagrant and Virtualbox and deploy them in IOx local manager GUI.

Prerequisites

Windows/ MAC Intel/ Linux

- Git

- Vagrant

- Virtualbox

MAC ARM Based - M1/M2/M3

- Git

- Vagrant

- VMWare Fusion

- vagrant-vmware-desktop plugin

To download:

- Vagrant

- VirtualBox

Procedure to Set Up Build Environment Using Vagrant

Summary of Actions

- The vagrantfile configuration sets up a VM environment based on its host machine architecture.

- It configures the VM to use either VMware Fusion or VirtualBox, depending on the architecture

- It provisions the VM with necessary software and tools, including QEMU (Quick EMUlator) , Docker and ioxclient.

- Configruation automatically builds a sample iperf application for amd64 target Cisco platform devices.

Step 1. Clone the Github repository in your local system:

git clone https://github.com/suryasundarraj/cisco-iox-app-build.git

Alternatively, copy and paste the contents of the configuration enclosure into "Vagrantfile". This creates a file with the name "Vagrantfile" in the local system:

# -*- mode: ruby -*-

# vi: set ft=ruby :

# All Vagrant configuration is done below. The "2" in Vagrant.configure

# configures the configuration version (we support older styles for

# backwards compatibility). Please don't change it unless you know what

# you're doing.

Vagrant.configure('2') do |config|

arch = `arch`.strip()

if arch == 'arm64'

puts "This appears to be an ARM64 machine! ..."

config.vm.box = 'gyptazy/ubuntu22.04-arm64'

config.vm.boot_timeout = 600

config.vm.provider "vmware_fusion" do |vf|

#vf.gui = true

vf.memory = "8192"

vf.cpus = "4"

end

config.vm.define :ioxappbuild

else

puts "Assuming this to be an Intel x86 machine! ..."

config.vm.box = "bento/ubuntu-22.04"

config.vm.network "public_network", bridge: "ens192"

config.vm.boot_timeout = 600

config.vm.provider "virtualbox" do |vb|

#vb.gui = true

vb.memory = "8192"

vb.cpus = "4"

end

config.vm.define :ioxappbuild

end

config.vm.provision "shell", inline: <<-SHELL

#!/bin/bash

# apt-cache madison docker-ce

export VER="5:24.0.9-1~ubuntu.22.04~jammy"

echo "!!! installing dependencies and packages !!!"

apt-get update

apt-get install -y ca-certificates curl unzip git pcregrep

install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc

chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" |  tee /etc/apt/sources.list.d/docker.list > /dev/null

apt-get update

apt-get install -y qemu binfmt-support qemu-user-static

apt-get install -y docker-ce=$VER docker-ce-cli=$VER docker-ce-rootless-extras=$VER containerd.io docker-buildx-plugin docker-compose-plugin

# apt-get install -y docker.io docker-compose docker-buildx

usermod -aG docker vagrant

echo "!!! generating .ioxclientcfg.yaml file !!!"

echo 'global:' > /home/vagrant/.ioxclientcfg.yaml

echo '  version: "1.0"' >> /home/vagrant/.ioxclientcfg.yaml

echo '  active: default' >> /home/vagrant/.ioxclientcfg.yaml

echo '  debug: false' >> /home/vagrant/.ioxclientcfg.yaml

echo '  fogportalprofile:' >> /home/vagrant/.ioxclientcfg.yaml

echo '    fogpip: ""' >> /home/vagrant/.ioxclientcfg.yaml

echo '    fogpport: ""' >> /home/vagrant/.ioxclientcfg.yaml

echo '    fogpapiprefix: ""' >> /home/vagrant/.ioxclientcfg.yaml

echo '    fogpurlscheme: ""' >> /home/vagrant/.ioxclientcfg.yaml

echo '  dockerconfig:' >> /home/vagrant/.ioxclientcfg.yaml

echo '    server_uri: unix:///var/run/docker.sock' >> /home/vagrant/.ioxclientcfg.yaml

echo '    api_version: "1.22"' >> /home/vagrant/.ioxclientcfg.yaml

echo 'author:' >> /home/vagrant/.ioxclientcfg.yaml

echo '  name: |' >> /home/vagrant/.ioxclientcfg.yaml

echo '    Home' >> /home/vagrant/.ioxclientcfg.yaml

echo '  link: localhost' >> /home/vagrant/.ioxclientcfg.yaml

echo 'profiles: {default: {host_ip: 127.0.0.1, host_port: 8443, auth_keys: cm9vdDpyb290,' >> /home/vagrant/.ioxclientcfg.yaml

echo '    auth_token: "", local_repo: /software/downloads, api_prefix: /iox/api/v2/hosting/,' >> /home/vagrant/.ioxclientcfg.yaml

echo '    url_scheme: https, ssh_port: 2222, rsa_key: "", certificate: "", cpu_architecture: "",' >> /home/vagrant/.ioxclientcfg.yaml

echo '    middleware: {mw_ip: "", mw_port: "", mw_baseuri: "", mw_urlscheme: "", mw_access_token: ""},' >> /home/vagrant/.ioxclientcfg.yaml

echo '    conn_timeout: 1000, client_auth: "no", client_cert: "", client_key: ""}}' >> /home/vagrant/.ioxclientcfg.yaml

cp /home/vagrant/.ioxclientcfg.yaml /root/.ioxclientcfg.yaml

chown vagrant:vagrant /home/vagrant/.ioxclientcfg.yaml

arch=$(uname -m)

if [[ $arch == x86_64 ]]; then

# download page https://developer.cisco.com/docs/iox/iox-resource-downloads/

echo "!!! downloading and extracting ioxclient for x86_64 architecture !!!"

curl -O https://pubhub.devnetcloud.com/media/iox/docs/artifacts/ioxclient/ioxclient-v1.17.0.0/ioxclient_1.17.0.0_linux_amd64.tar.gz

tar -xvf /home/vagrant/ioxclient_1.17.0.0_linux_amd64.tar.gz

cp /home/vagrant/ioxclient_1.17.0.0_linux_amd64/ioxclient /usr/local/bin/ioxclient

rm -rv /home/vagrant/ioxclient_1.17.0.0_linux_amd64

elif  [[ $arch = aarch64 ]]; then

# download page https://developer.cisco.com/docs/iox/iox-resource-downloads/

echo "!!! downloading and extracting ioxclient for arm64 architecture !!!"

curl -O https://pubhub.devnetcloud.com/media/iox/docs/artifacts/ioxclient/ioxclient-v1.17.0.0/ioxclient_1.17.0.0_linux_arm64.tar.gz

tar -xvf /home/vagrant/ioxclient_1.17.0.0_linux_arm64.tar.gz

cp /home/vagrant/ioxclient_1.17.0.0_linux_arm64/ioxclient /usr/local/bin/ioxclient

rm -rv /home/vagrant/ioxclient_1.17.0.0_linux_arm64

fi

chown vagrant:vagrant /usr/local/bin/ioxclient

echo "!!! pulling and packaging the app for x86_64 architecture !!!"

docker pull --platform=linux/amd64 mlabbe/iperf3

ioxclient docker package mlabbe/iperf3 .

cp package.tar /vagrant/iperf3_amd64-$(echo $VER | pcregrep -o1 ':([0-9.-]+)~').tar

SHELL

end

Step 2. Ensure that the "export VER="5:24.0.9-1~ubuntu.22.04~jammy" line is uncommented and all other export statement are commented. This corresponds to the Docker Engine version you wish to install in this Vagrant environment:

cisco@cisco-virtual-machine:~/Desktop/ioxappbuild$ cat Vagrantfile | grep 'export' | grep -v '#'

export VER="5:24.0.9-1~ubuntu.22.04~jammy"

Step 3. Start the Vagrant environment with the vagrant up command in the directory where the Vagrantfile resides and observe a successful build of the iperf IOx application for amd64 tar file:

vagrant up

Procedure to Build a Custom IOx Application

This section describes, how to build a custom IOx application using the vagrant environment.

Note: The directory "/vagrant" in the VM and the directory which contains the "Vagrantfile" in the host system are in sync.

As shown in the image, the new.js file is created inside the VM and is also accessible on the host system:

Step 1. Clone a sample application to the same folder where "Vagrantfile" resides. On this example "iox-multiarch-nginx-nyancat-sample" application is used:

git clone https://github.com/etychon/iox-multiarch-nginx-nyancat-sample.git

Step 2. SSH into the vagrant machine:

vagrant ssh

Step 3. Build the application:

cd /vagrant/iox-multiarch-nginx-nyancat-sample/

chmod +x build

sh ./build

After the build process is completed, you now have two IOx applications ready for deployment ("iox-amd64-nginx-nyancat-sample.tar.gz" for amd64  and "iox-arm64-nginx-nyancat-sample.tar.gz" for target platforms):

Deploy the IOx Application

Step 1. Access the IR1101 with the use of the web interface:

Step 2. Use the privilege 15 account:

Step 3. In the IOx Local Manager login, use the same account to continue as shown in the image:

Step 4. Click Add New, select a name for the IOx application, and choose the package.tar which was built in Step 3 of the Procedure to Set Up Build Environment Using Vagrant section, as shown in the image:

Step 5. Once the package is uploaded, activate it as shown in the image:

Step 6. In the Resources tab, open the interface setting in order to specify the fixed IP that you want to assign to the app as shown in the image:

Step 7. Click OK, then Activate. Once the action completes, navigate back to the main Local Manager page (Applications button on the top menu), then start the application as shown in the image:

After you go through these steps, your application is ready to be running.

Troubleshoot

In order to troubleshoot your configuration, check the log file which you create in the Python script using a local manager. Navigate to Applications, click Manage on the iox_web application, then select the Logs tab as shown in the image: