IOx

Application management

The following sections describe usage of ioxclient to manage applications. Below are the application management commands:

Code Snippet
Copy$ ./ioxclient  application
NAME:
   ioxclient application - Manage lifecycle of applications

USAGE:
   ioxclient application command [command options] [arguments...]

COMMANDS:
   list, li		List installed applications on the system
   run, r		Install, activate and start the application
   install, in		Install an application
   local_install, lin		Install an application that is already present on the target device
   start, sta		Start an installed application
   stop, stp		Stop an installed application
   restart, rs		Restart an installed application
   status, sts		Get current status of an installed application
   info, inf		Get info pertaining to an installed application
   activate, act	Activate application
   deactivate, deact	Deactivate Application
   uninstall, unin	Uninstall an installed application
   upgrade, upgr	Upgrade an application
   getconfig, getconf	Get config information of an installed application
   setconfig, setconf	Set config information for an installed application from the specified file
   logs, lgs			Manage log files
   cores, cores			Manage core files
   datamount, dm		Manage contents of application's data mount directory
   appdata, appdata		Manage files in the appdata directory under datamount
   console, con		Connect to the console of the application
   session, s		Create a new shell session in the container
   exec, ex			Execute a specific command directly in a container-based application
   metrics, met		Get resource usage metrics of installed applications
   help, h		Shows a list of commands or help for one command

OPTIONS:
   --help, -h			show help
   --generate-bash-completion

Ensure that you have right profile activated.

Packaging an application

ioxclient provides ability to package an already created application

Code Snippet
Code Snippet - 1
Copy$ ioxclient package
NAME:
   package - Package an iox application/service/cartridge. Produces an IOx compatible archive
   
   USAGE:
      command package [command options] <path_to_dir>

   OPTIONS:
      --use-targz          Use this to use gz compression on package
      --skip-schema-validation Use this flag to skip package descriptor schema validation
      --layers, -l         Use this option to package application layers by specifying IOx layers directory
      --rsa-key, -k        Use this option to specify a RSA key in PEM format to sign the package
      --certificate, -c    Use this option to specify a x509 Certificate in PEM format
      --skip-signing       Use this option to skip package signing
      --name, -n 			Use this option to specify the package name excluding the file extension

Copy/home/dev/Documents/iox/pkg$ ioxclient package -k ../key.pem -c ../cert.pem .
Currently active profile :  local
Command Name:  package
Using rsa key and cert provided via command line to sign the package
Checking if package descriptor file is present..
Validating descriptor file /home/dev/Documents/iox/pkg/package.yaml with package schema definitions
Parsing descriptor file..
Found schema version  2.5
Loading schema file for version  2.5
Validating package descriptor file..
File /home/dev/Documents/iox/pkg/package.yaml is valid under schema version 2.5
Created Staging directory at :  /tmp/198111141
Copying contents to staging directory
Checking for application runtime type
Couldn't detect application runtime type
Creating an inner envelope for application artifacts
Generated  /tmp/198111141/artifacts.tar.gz
Calculating SHA1 checksum for package contents..
Parsing Package Metadata file :  /tmp/198111141/.package.metadata
Wrote package metadata file :  /tmp/198111141/.package.metadata
Root Directory :  /tmp/198111141
Output file:  /tmp/170359488
Path:  .package.metadata
SHA1 : 09679c5d4b25e4673f1e7d4b7dd2c725a8d5d6cf
Path:  artifacts.tar.gz
SHA1 : 9633a0126b6f02350fe6b5bc185e47acc56abc04
Path:  package.yaml
SHA1 : 7c0a205ff916215538f85e9ff3b34babaac39f0f
Generated package manifest at  package.mf
Signed the package and the signature is available at package.cert
Generating IOx Package..
Package generated at /home/dev/Documents/iox/pkg/package.tar
  • Options RSA key and certificate should be used to provide a private key and cert pair to sign the package.
  • The provided key and certificate pair will take precedence over the ones specified in the active profile

In the above command "." is supplied - indicating that package the current directory. ioxclient ensures that the path supplied for package command contains all the required files before packaging. Refer to IOx package documentation for more details about the structure and layout of the package. Successful completion of this command creates a "package.tar(.gz)" that can be used for installation on your IOx device.

Installing an application

Code Snippet
Copy~/projects/sample-apps-v2/paas/python/nettest$ ioxclient  application install nettest ./package.tar.gz
Currently using profile :  default
Command Name: application-install
Installation Successful. App is available at :  https://127.0.0.1:8443/iox/api/v2/hosting/apps/nettest
Successfully deployed

Installing an application with dependent IOx Services

A user who wants the dependencies of the application to be taken care of, can specify the ioxclient to resolve dependencies in two methods -

There are three flags available to achieve this functionality -

  • --resolve-dependencies or --rd : specify this flag to enable automatic dependency resolution
  • --service-source or --src : specify a folder containing service bundles to use them for dependency resolution. If no folder is specified, fogportal will be searched for the required packages.
  • --service-activation-payload or --p - where the path of the activation payload for services is specified.

Resolve Service Dependencies from the Fog portal -

Here, the installer searches for the required services from the Fog portal, downloads them into a temp folder and installs, activates using the activation payload, and runs them in order to install the required application

Code Snippet
Copy~/projects/sample-apps-v2/paas/python/nettest$ ioxclient  application install nettest ./package.tar.gz --resolve-dependencies --service-activation-payload activation-file.json

Output -

Code Snippet
Copy~$ioxclient app in oauth sample-oauth.tar --rd --p test_resources\nat-activation.json
Currently active profile :  vm211
Command Name: application-install
Resolve Dependencies flag specified by user
Reading  sample-oauth.tar ......
Parsing  sample-oauth.tar .yaml
map[sample-app:{{{sample-app} { paas {[{1 true urn:cisco:system:service:nbi}]} {50}} {[]}} false 2 sample-oauth.tar -1 false}]map[]map[urn:cisco:system:service:nbi:{{1 true urn:cisco:syste
Checking CAF for the already existing services
Existing services in CAF are -
Resolving dependencies from Fog portal
Checking fog portal for the dependencies that are not in CAF
Requesting  http://10.78.106.35:8090/api/v1/fogportal/service_bundles/
Requesting -   http://10.78.106.35:8090/api/v1/fogportal/service_bundles/
The following services are available in the Fog portal
1 .  Middleware Message Broker
2 .  middleware-core
Saving current configuration
Constructing a Dependency tree for sample-app
|_sample-app
|_|_middleware-core
|_|_|_Middleware Message Broker
Checking CPU architecture compatibility of the service  Middleware Message Broker
Middleware Message Broker  is present in the FogPortal
Downloading  Middleware Message Broker ....
200 OK

C:\Users\cheb\AppData\Local\Temp\185222e322175b49ebe62449798d47f48dbe449932d5b752e2c7a2321031952b with 3319559 bytes downloaded
Service bundle to be stored in  C:\Users\cheb\AppData\Local\Temp\185222e322175b49ebe62449798d47f48dbe449932d5b752e2c7a2321031952b
Installation Successful. Service is available at : https://10.78.106.211:8443/iox/api/v2/hosting/service-bundles/MiddlewareMessageBroker
Successfully deployed
Payload file : test_resources\nat-activation.json. Will pass it as application/json in request body..
Service MiddlewareMessageBroker is Activated
Service MiddlewareMessageBroker is Started

Resolved status of  Middleware Message Broker  -  true
middleware-core  is present in the FogPortal
Downloading  middleware-core ....
200 OK

C:\Users\cheb\AppData\Local\Temp\9b22331ad31f16c00c108f7c4de8cda0796304632664175cbece439d18a21ca8 with 13270313 bytes downloaded
Service bundle to be stored in  C:\Users\cheb\AppData\Local\Temp\9b22331ad31f16c00c108f7c4de8cda0796304632664175cbece439d18a21ca8
Installation Successful. Service is available at : https://10.78.106.211:8443/iox/api/v2/hosting/service-bundles/middlewareCore
Successfully deployed
Payload file : test_resources\nat-activation.json. Will pass it as application/json in request body..
Service middlewareCore is Activated
Service middlewareCore is Started

Resolved status of  middleware-core  -  true
Installation Successful. App is available at : https://10.78.106.211:8443/iox/api/v2/hosting/apps/oauth
Successfully deployed

Resolve Service Dependencies from the folder -

In this case, the specified folder is searched for the required dependencies and the ones required are installed, activated and started in order to install the application.

Code Snippet
Copy~/projects/sample-apps-v2/paas/python/nettest$ ioxclient  application install nettest ./package.tar.gz --resolve-dependencies --src path/to/service/bundles --service-activation-payload activation-file.json

Output -

Code Snippet
Copy~$ioxclient app in apc package.tar.gz --rd localrepo --f path/to/folder --p activation-file.json
Currently active profile :  vm211
Command Name: application-install
Resolve Dependencies flag specified by user
Reading  test_resources\fog-apps\apcargo-fog-app-master-72c451defc2c1f2e33bcc4ef24745e0b4019dcb0\package.tar.gz ......
Reading .yaml of  package.tar.gz
Checking CAF for the already existing services
Existing services in CAF are -
Flag for Local repository dependency resolution recognized
Searching the specified local repo for the dependencies..
Unpacking  dartBroker.tar.gz
Reading  test_resources\svc-bundles\dartBroker.tar.gz ......
Reading .yaml of  dartBroker.tar.gz
Unpacking  mw-package.tar.gz
Reading  test_resources\svc-bundles\mw-package.tar.gz ......
Reading .yaml of  mw-package.tar.gz
Resolving dependencies for  APCargo
|_Resolving  APCargo
|_|_Resolving  iox:middleware:core
|_|_|_Resolving  Middleware Message Broker
Installation Successful. Service is available at : https://10.78.106.211:8443/iox/api/v2/hosting/service-bundles/MiddlewareMessageBroker
Successfully deployed
Payload file : test_resources\nat-activation.json. Will pass it as application/json in request body..
Service MiddlewareMessageBroker is Activated
Service MiddlewareMessageBroker is Started

Resolved status of  Middleware Message Broker  -  true
Installation Successful. Service is available at : https://10.78.106.211:8443/iox/api/v2/hosting/service-bundles/ioxMiddlewareCore
Successfully deployed
Payload file : test_resources\nat-activation.json. Will pass it as application/json in request body..
Service ioxMiddlewareCore is Activated
Service ioxMiddlewareCore is Started

Resolved status of  iox:middleware:core  -  true
Installation Successful. App is available at : https://10.78.106.211:8443/iox/api/v2/hosting/apps/apc
Successfully deployed

Installing an application package already available on the device

If the application package is too large to transfer over http, please copy the package to the device by other means and use the below command to install the application

Code Snippet
Copy
dev@dev-VirtualBox:~$ ioxclient application local_install 
Insufficient Args.

NAME:
   local_install - Install an application that is already present on the target device

USAGE:
   command local_install <application_id> <path_to_package_on_the_platform>

dev@dev-VirtualBox:~$ ioxclient application local_install test /home/iox/package.tar
Currently active profile :  caf
Command Name:  application-local_install
Attempting to install app already available on the platform at /home/root/iox/package.tar
Installation Successful. App is available at : https://10.41.51.109:8443/iox/api/v2/hosting/apps/test 
Successfully deployed
dev@dev-VirtualBox:~$

Activating application

An application has to be activated before starting. At the time of activation, the developer/administrator has to supply the right resource mapping based on what the application needs.

Refer IOx application states documentation for more information about application states. Refer IOx application descriptor documentation for more information about application resource requirements.

For ex, the above installed app asks for network interface. That interface has to be associated with the right logical network available on the device. Similarly, you could assign the right device, map external ports etc.,

Code Snippet
Copy$ ./ioxclient  application activate
NAME:
   activate - Activate application

USAGE:
   command activate [command options] <application_id>

DESCRIPTION:

Activation of an app causes the resources to be committed.
Pass a JSON file with the right payload. Here is a sample:

* port_map: The mode (auto, 1to1) governs how the ports are mapped.
* If no mode is given, auto is the default
* A mode can be specified, and you can still set a custom port mapping for individual/range of ports that overrides the mode settings.
{
    "resources": {
        "profile": "custom",
        "cpu": "50",
        "memory": "50",
        "disk": "100",
        "devices": [{
            "type": "serial",
            "label": "HOST_DEV1",
            "device-id": "/dev/ttyS1"
        }],
        "network": [{
            "interface-name": "eth0",
            "network-name": "iox-nat0",
            "port_map": {
                "mode": "auto",
                "tcp": {
                    "9000": "15000",
                    "10100-10200": "20100-20200"
                },
                "udp": {
                    "19000": "25000"
                }
            }
        }]
    }
}

* To specify docker run time options, please see below example usage:
    ioxclient app activate --docker-opts "--dns 8.8.8.8 --dns-search testsearch.com -h testhostname --cap-drop setfcap" <appid>

OPTIONS:
   --payload 	Pass the path to a JSON file containing your payload
   --debug 	Set to on/off.
   --docker-opts, -d 	Pass docker runtime options as a quoted string
   --disable-auto-instance-delete, --dis	Use this flag to disable auto container instance delete

Pass a JSON file path to --payload that contains the right activation payload.

For the above app, we will use a "activation.json" that contains the right content.

json
Copy{
    "resources": {
        "profile": "c1.small",
        "network": [{"interface-name": "eth0", "network-name": "iox-nat0"}]
    }
}

We are associating "eth0" interface requested by the app to "iox-nat0" network available on the device We are also setting the resource profile to "c1.small"

A note about "--debug" flag

At the time of activation, you can set the --debug on. Setting this instructs the IOx platform to activate this app in debug mode. For platforms that use LXC container technology this means that even if the application stops/crashes, the container is still kept running, so that you can connect to the application console for further debugging.

Here is a sample activation command:

Code Snippet
Copy~/projects/sample-apps-v2/paas/python/nettest$ ioxclient  application activate nettest --payload activation.json
Currently using profile :  default
Command Name: application-activate
Payload file : activation.json. Will pass it as application/json in request body..
App nettest is Activated

Starting the application

Code Snippet
Copy~/projects/sample-apps-v2/paas/python/nettest$ ioxclient  application start nettest
Currently using profile :  default
Command Name: application-start
App nettest is Started

View application information

Code Snippet
Copy~/projects/sample-apps-v2/paas/python/nettest$ ioxclient  application info nettest
Currently using profile :  default
Command Name: application-info
Details of App : nettest
-----------------------------
{
 "appCustomOptions": "",
 "appType": "paas",
 "author": "Cisco Systems",
 "authorLink": "http://www.cisco.com",
 "dependsOn": {
  "cartridges": [
   {
    "id": "urn:cisco:system:cartridge:language-runtime:python",
    "version": "2.7"
   }
  ]
 },
 "description": "Provides a REST end point on port 9000 and also tests outbound traffic",
 "id": "nettest",
 "is_service": false,
 "name": "PyNetTest",
 "networkInfo": {
  "eth0": {
   "ipv4": "192.168.223.10",
   "ipv6": null,
   "libvirt_network": "dpbr_n_0",
   "mac": "52:54:99:99:00:00",
   "mac_address": "52:54:99:99:00:00",
   "network_name": "iox-nat0",
   "port_mappings": {
    "tcp": [
     [
      9000,
      40003
     ]
    ],
    "udp": [
     [
      10000,
      42003
     ]
    ]
   }
  }
 },
 "resources": {
  "cpu": 200,
  "disk": 10,
  "memory": 64,
  "network": [
   {
    "interface-name": "eth0",
    "network-name": "iox-nat0",
    "ports": {
     "tcp": [
      9000
     ],
     "udp": [
      10000
     ]
    }
   }
  ],
  "profile": "c1.small",
  "vcpu": 1
 },
 "state": "RUNNING",
 "toolkitServicesUsed": null,
 "version": "1.5"
}

Listing all the applications on the system

Code Snippet
Copy~/projects/sample-apps-v2/paas/python/nettest$ ioxclient  application list
Currently using profile :  default
Command Name: application-list
List of installed apps :
 1. nettest    --->    STOPPED

View application status

Code Snippet
Copy~/projects/sample-apps-v2/paas/python/nettest$ ioxclient  application status nettest
Currently using profile :  default
Command Name: application-status
App nettest is RUNNING

Get application bootstrap configuration

Code Snippet
Copy$ ioxclient application getconfig nettest
Currently using profile :  default
Command Name: application-getconfig
Retrieved app config successfully. Content stored at nettest-app_config.ini

Setting application bootstrap configuration

You can set the application bootstrap configuration by passing a new configuration file.

Usage:

Code Snippet
Copy$ ioxclient  application setconfig
NAME:
   setconfig - Set config information for an installed application from the specified file

USAGE:
   command setconfig <application_id> <config_file> [log_level]

If the content is present in a "config.ini" file, you can use the command as below:

Code Snippet
Copy$ioxclient application setconfig nettest config.ini
Currently using profile :  default
Command Name: application-setconfig
Successfully updated apps configuration.
Next