Application management
The following sections describe usage of ioxclient to manage applications. Below are the application management commands:
$ ./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
$ 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
/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
~/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
~/projects/sample-apps-v2/paas/python/nettest$ ioxclient application install nettest ./package.tar.gz --resolve-dependencies --service-activation-payload activation-file.json
Output -
~$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.
~/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 -
~$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
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.,
$ ./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.
{
"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:
~/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
~/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
~/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
~/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
~/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
$ 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:
$ 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:
$ioxclient application setconfig nettest config.ini
Currently using profile : default
Command Name: application-setconfig
Successfully updated apps configuration.