IOx Package Descriptor

An IOx package descriptor is a file that describes the requirements, metadata about an IOx application, or a service.

Every IOx package MUST contain a descriptor file. For more details, refer to the IOx application package documentation.

This document describes the details of structure, rules, and format of the descriptor file.

Yaml Template

An IOx descriptor file should be a valid YAML file named as package.yaml that should be present in the root of the package.

Here is package descriptor template with set of mandatory fields for docker app. 

descriptor-schema-version: 2.8
info:
  name: <App Name>
  version: <App Version>

app:
  type: docker
  cpuarch: <x86_64 or aarch64>

  resources:
    profile: <cpu, memory resource profile. Eg., default or c1.tiny or custom >
    
  startup:
    rootfs: rootfs.tar
    target: <command to execute in the container>

Refer below section for exhaustive list of parameters supported in package descriptor.

Check this tutorial for how to define custom package descriptor and package it as part of IOx app.

Note: We recommend using minimum 2.8 as descriptor-schema-version. Unless you need a parameter defined in 2.9+ version, it is not necessary to change this recommended schema version in package.yaml.

Example Package Descriptor File Usage and Format

The usage and format of arrtributes defined in the above table can be found in the following example package.yaml file: Example_package.yaml

Summary

The sections and subsections in the package descriptor yaml file are summarized as a table below. A more formal JSON specification is also available in the next section.

  • Mandatory section, O: Optional section, N/A: Not applicable
  • Yaml Type Boolean takes values - true or false

Schema update from 2.16 to 2.17

Sections and Subsections PaaS LXC Docker VM Constraints Type Comment
app -> resources -> network -> multicast O O O O Boolean Boolean multicast capability

Schema update from 2.15 to 2.16

Sections and Subsections PaaS LXC Docker VM Constraints Type Comment
app -> resources -> ** hugepages ** O O O O N/A Object App developer can provide number of huge pages.
app -> resources -> hugepages M M M M String/Integer String/Integer

Schema update from 2.14 to 2.15

Sections and Subsections PaaS LXC Docker VM Constraints Type Comment
app -> ** child ** O O O O N/A Object Child container managerment.
app -> child -> manage-child M M M M boolean boolean Capability to manage child container.
app -> child -> reserve-disk M M M M String/Integer String/Integer Reservered disk size for child container

Schema update from 2.13 to 2.14

Sections and Subsections PaaS LXC Docker VM Constraints Type Comment
app -> resources -> ** custom-map ** O O O O N/A Object App developer can provide customerized map.
app -> resources -> custom-map -> name M M M M String String
app -> resources -> custom-map -> memory M M M M String/Integer String/Integer
app -> resources -> custom-map -> cpu M M M M String/Integer String/Integer
app -> resources -> custom-map -> disk O O O O String/Integer String/Integer

Schema update from 2.12 to 2.13

Sections and Subsections PaaS LXC Docker VM Constraints Type Comment
app -> signature -> verify-sign O O O O Boolean Boolean Enforce app signature validation
app -> resources -> randomdev N/A N/A N/A O Boolean Boolean Access to random number device for better entropy
app -> resources -> cpu-percent O O O O String String Specify cpu in percentage of total available to IOx app hosting framework for custom resource profile

Schema update from 2.11 to 2.12

Sections and Subsections PaaS LXC Docker VM Constraints Type Comment
app -> startup -> runtime_options N/A N/A O N/A String String Specify docker run options needed while creating the container

descriptor-schema-version section

Sections and Subsections PaaS LXC Docker VM Constraints Type Minimum Schema Version Comment
** descriptor-schema-version** M M M M String String 2.0 Specify the schema version supporting all the attributes used in the package.yaml file

info section

Sections and Subsections PaaS LXC Docker VM Constraints Type Minimum Schema Version Comment
** info ** M M M M N/A Object 1.0 Metadata about the application and app developer.
info -> author-link O O O O String String 1.0 URL to indicate the web address of the app developer.
info -> author-name O O O O String String 1.0 Name of the app developer. Note: The name must not contain spaces.
info -> description O O O O String String 1.0 Description of the application.
info -> name M M M M String String 1.0 Name of the application. Note: The name must not contain spaces.
info -> version M M M M String String 1.0 Version of the application in x.y notation.

app section

Sections and Subsections PaaS LXC Docker VM Constraints Type Minimum Schema Version Comment
** app ** M M M M N/A Object 1.0 Section capturing app details and requirements.
app -> cpuarch O M M M String String 2.0 Target CPU architecture of the app.
app -> type M M M M enum["paas", "lxc", "vm", "docker"] String 2.0 Type of app.
app -> kernel-version O M O O String String 2.0 Minimum version of the kernel required by the app to run.* See notes below.
app -> ** resources ** O O O O N/A Object 2.0 resources required by the app.
app -> resources -> profile M M M M String String 2.0 Valid profile definition supported by the platform. * See notes below.
app -> resources -> cpu O O O O String String 2.0 CPU requirements in units. Applicable only if the profile is chosen as custom.
app -> resources -> memory O O O O String String 2.0 Memory requirements in MB. Applicable only if the profile is chosen as custom.
app -> resources -> disk O O O O String String 2.0 Persistent storage requirements in MB.
app -> resources -> vcpu N/A N/A N/A O String String 2.2 Number of VCPUs required for a VM app. Not applicable for container based apps (PaaS, LXC, Docker).
app -> resources -> ** cpu-topology ** N/A N/A N/A O Object Object 2.2 If a VCPU is requested by a VM app, you can customize how it must be presented to the app in this section.*
app -> resources -> cpu-topology -> cores N/A N/A N/A O String/Integer must be a number String/Integer 2.2 Virtual cores.
app -> resources -> cpu-topology -> sockets-per-core N/A N/A N/A O String/Integer must b a number String/Integer 2.2 Virtual sockets per core.
app -> resources -> platform-env O O O O List of Strings List 2.2 Some platforms can supply platform specific environment variables to apps. These apps must request those variables by specifying the keys under this section.
app -> resources -> device-info O O O O enum ["udi"] List 2.1 Cisco unique device identification (UDI) to identify the device.
app -> resources -> oauth O O O O enum["OauthClient", "OauthValidator"] List 2.1 If you want to access Oauth service, you must specify 'OauthClient.' If you are an oath provider, you must specify "OauthValidator."
app -> resources -> broker O O O O enum["BrokerClient", "Broker"] List 2.1 If you want to access broker service, use 'BrokerClient.' If you are providing broker service, use 'Broker.'
app -> resources -> ** graphics** N/A N/A N/A O 2.1 Graphic interfaces for VNC. This is only applicable for VM apps.
app -> resources -> graphics -> vnc N/A N/A N/A O Boolean Boolean 2.1 Applicable if your VM app needs to be VNC enabled.
app -> resources -> ** devices ** O O O O N/A List 2.0 List of all devices required by the app.
app -> resources -> devices -> device-id O O O O String String 2.0 Used for serial device. Specify value as "serial"
app -> resources -> devices -> type M M M M String String 2.0 Specify value "serial" for Serial device. Specify value "usbdev" for USB Serial or USB storage device
app -> resources -> devices -> label M M M M String String 2.0 Label string that will be exported as ENV variable with device path as value inside the app
app -> resources -> devices -> usage O O O O String String 2.0 Description of device usage
app -> resources -> ** network ** O O O O N/A List 2.0 network requirements of the app (contains the list of below mentioned fields).
app -> resources -> network -> interface-name M M M M String String 2.0 Specify interface name like eth0 or eth1
app -> resources -> network -> description O O O O String String 2.2 (Optional) Description of the interface usage by the app.
app -> resources -> network -> ** ports ** O O O O N/A Object 2.0
app -> resources -> network -> ports -> tcp O O O O List of strings or integers List 2.0 If the ports section is present, either tcp or udp section must be present.
app -> resources -> network -> ports -> udp O O O O List of strings or integers List 2.0 If the ports section is present, either tcp or udp section must be present.
app-> resources -> persistent_data_target O O O O String String 2.9 Customize persistent data dir path mounted by IOx inside the app. Default path is /data.
app -> resources -> ** recommendations ** O O O O N/A List 2.0 App developer can provide recommendations to the administrator about how the application might perform under different resource profiles.*
app -> resources -> recommendations -> profile M M M M String String 2.0 One of the profile names.
app -> resources -> recommendations -> label M M M M String String 2.0 User defined label. This is used by admin tools, for example Fog Director, to show hints.
app -> resources -> recommendations -> description M M M M String String 2.0 Textual description of how the application would behave under a resource profile.
app -> ** monitor ** O O O O N/A Object 2.0 App can provide the health script that will be used for periodically monitoring the app.
app -> monitor -> script M M M O String String 2.0 Path of the script to monitor the app's health. Return status of 0 indicates success. Non zero return code indicates a failure.
app -> monitor -> initial_delay_seconds M M M O Number Number 2.0 Wait time in seconds after the app starts before executing the health monitoring script. Default value is 30 seconds.
app -> monitor -> period_seconds M M M O Number Number 2.0 Interval in seconds (multiple of 30) when this script needs to run. Default value 60 seconds.
app -> ** depends-on ** O O O O N/A Object 2.0 Contains the list of cartridges and services required by the app.
app -> depends-on -> ** cartridges ** O N/A N/A N/A N/A List 2.0
app -> depends-on -> cartridges -> id M O O O String String 2.0 URN of the cartridge.
app -> depends-on -> cartridges -> version M O O O Number Number 2.0 Version of the cartridge.
app -> depends-on -> ** services ** O O O O N/A List 2.0 An app can require one or many IOx services. Dependency on services can be mentioned in this section.
app -> depends-on -> services -> id M M M M String String 2.0 URN of the service bundle.
app -> depends-on -> services -> min-api-version O O O O Number Number 2.0 Minimum API version.
app -> depends-on -> services -> max-api-version O O O O Number Number 2.0 Maximum API version.
app -> depends-on -> services -> required O O O O Boolean Boolean 2.0 If false and the service is not present on the platform, CAF allows the app to be installed assuming that app has the capability to function in a reduced feature mode.
app -> ** startup ** M M M M N/A Object 2.0 Definition of the properties required to start the app. If runtime is selected as 'generic-linux,' then 'runtime-version' is not required.
app -> startup -> ostype N/A N/A N/A O String String 2.1 Only applicable for VM apps. Used to define your OS. If this is not defined, the default assumption is Linux.
app -> startup -> qemu-guest-agent N/A N/A N/A O Boolean Boolean 2.1 Only applicable for VM apps. This flag specifies that the app has package qemu guest agent. If it is not specified, then it is assumed to be present.
app -> startup -> ** disks ** N/A N/A N/A O Object Object 2.1 Only applicable for VM apps. This brings your VM as a whole disk.
app -> startup -> disks -> target-dev N/A N/A N/A M String String 2.1 Target device where the disk has to be mounted. (ex. hda)
app -> startup -> disks -> file N/A N/A N/A M String String 2.1 Points to the actual disk file. (raw image, qcow2)
app -> startup -> rootfs N/A M M M String String 2.0 Specify rootfs file with extension. In case of docker image with platform supporting Union FS use "rootfs.tar". Other options are rootfs.img, rootfs.ext2, rootfs.ext4 based on how the rootfs is built.
app -> startup -> kernel N/A N/A N/A M String String 2.0 Specify path to the kernel image. This is to be used when startup section for VM app uses rootfs attribute instead of disks->file/target-dev options.
app -> startup -> runtime M N/A N/A N/A String String 2.0 In case of PaaS apps, specify runtime like "python" or "java"
app -> startup -> ** runtime-options ** O N/A N/A N/A N/A Object 2.0 Developer can specify language runtime specific options (ex. CLASSPATH) for PaaS apps.
app -> startup -> runtime-options -> classpath M O O O String String 2.0 Specify class path incase of using Java cartridge for PaaS apps
app -> startup -> runtime-version O O O O String String 2.0 Specify runtime version like for python 2.7, set value "2.7"
app -> startup -> target M M M O String String 2.0 Specify target process run inside the app
app -> ** stop ** O N/A N/A N/A N/A Object 2.0 PaaS apps can specify a custom stop script.
app -> stop -> target M N/A N/A N/A String String 2.0 Applicable for PaaS apps to specify target process to stop app
app -> cpu-core N/A O O O String String 2.3 Cpu cores.
app -> resources -> devices -> function O O O O String String 2.4 Device storage type.
app -> resources -> devices -> mandatory O O O O boolean boolean 2.4 Set true or false. This will make activation of app with device assosciation as mandatory.
app -> depends-on -> packages O O O O N/A object 2.5 An app can require one or many IOx packages. Dependency on packages can be mentioned in this section.
app -> devices -> device-directory-to-mount O O O O String String 2.5 Specific mount directory in the device.
app -> devices -> mount-point O O O O String String 2.5 Mount directory in the device.
app -> devices -> productID O O O O String String 2.5 Product ID of peripheral device
app -> devices -> vendorID O O O O String String 2.5 Vendor ID of peripheral device
app -> resources -> network -> ipv6_required O O O O boolean boolean 2.5 Activation of app with IPv6 mandatory (true or false)
app -> resources -> datastore O O O O boolean boolean 2.5 Specifies that datastore service is enabled.
app -> resources -> rootfs_expanded_size N/A O N/A N/A List of strings or integers List 2.5 For LXC apps in IOS-XE platforms, specify additional rootfs size that needs to allocated.
app -> resources -> rootfs_size N/A O N/A N/A List of strings or integers List 2.5 rootfs partition size MB
app -> resources -> visualization O O O O Boolean Boolean 2.5 Set true/false to utilize in-built visualization feature in IOx
app -> startup -> os-mode N/A N/A O N/A Boolean Boolean 2.5 To bootup docker app as system container set to true
app -> ** monitor ** O O O O Object Object 2.6 Monitoring of app status.
app -> monitor -> period_seconds O O O O Number Number 2.6 App health script monitoring interval
app -> monitor -> initial_delay_seconds O O O O Number Number 2.6 App health script monitoring initial delay to start
app -> monitor -> script M M M M String String 2.6 Script used to monitor the app.
app -> resources -> ** filesystem ** O O O O Object Object 2.6 Supported file system in libvirt.
app -> resources -> filesystem -> fstype M M M M String String 2.6 (1) type - "ram", accessmode- "squash"/"passthrough", source has: usage units, target has: dir;
(2) type- "mount", accessmode-"squash"/passthrough, source has: dir, target has: dir, driver has: type, wrpolicy
app -> resources -> filesystem -> target O O O O String String 2.6 Host directory to mount
app -> resources -> filesystem -> permission O O O O String String 2.6 readonly or readwrite
app -> resources -> filesystem -> accessmode O O O O String String 2.6 values are passthrough/mapped/squash - default is passthrough
app -> resources -> filesystem -> driver -> type O O O O String String 2.6 This used if multiple backend drivers are supported but if one has to be selected as primary, could be "path"/"handle" .  type" tag can be used alone or along with "wrpolicy" tag.
app -> resources -> filesystem -> driver -> name O O O O String String 2.6 tag is used to specify the type of driver.  Value could be "loop"(used with type='raw'), "nbd", "ploop" (for Virtuozzo driver with type="ploop")
app -> resources -> filesystem -> driver -> wrpolicy O O O O String String 2.6 value is immediate. This controls host page cache interaction. If this tag is ommitted, default is to write to host page cache, and, in host, its normal page cache management will handle commitment to storage device. The latter does not ensure data integrity upon abrupt shutdown of the system, leaving it in inconsistent state.
app -> resources -> filesystem -> source -> usage O O O O String String 2.6 integer number specifying the number of bytes of 'units' sizes(currently only M/MiB is supported).
app -> resources -> filesystem -> source -> name O O O O String String 2.6 tag is used only with the "template" FS type
app -> resources -> filesystem -> source -> file O O O O String String 2.6 can be file or directory - file in case of FS type "file", directory for all other cases.
app -> system-capabilities O O O O Object Object 2.7 System capabilities supported by the platform.
app -> resources -> host_mounts -> description O O O O String String 2.7 The description of the purpose for which the host file system is needed.
app -> resources -> host_mounts -> target_mount M M M M String String 2.7 The destination mount point in the application container which will be used to access the required host file system.
app -> resources -> host_mounts -> host_mount_path O O O O String String 2.7 The host file system path that the application wants to access.
app -> resources -> access-control -> type O O O O enum["oauth2"] String 2.7 Specify oauth type for authentication. Used in case of dependency with IOx services. options
app -> resources -> access-control -> role O O O O enum["OauthClient","OauthValidator"] String 2.7 Specify role of the app for authentication. Used in case of dependency with IOx services. App needs to specify OauthClient. options
app -> resources -> access-control -> scopes O O O O String String 2.7 Specify scopes of dependent IOx service app would like to use. For eg., "gps:read","gps:write","gps:admin
app -> startup -> args M M M M String String 2.7 Specify args for target process running inside the app
app -> startup -> group M M M M String String 2.7 Specify group name or group id for executing target process inside app
app -> startup -> user M M M M String String 2.7 Specify user name or user id for executing target process inside app
app -> startup -> workdir M M M M String String 2.7 Specify the workdir from which target process inside the app to be started
app -> ** post_upgrade ** O O O O Object Object 2.8
app -> post_upgrade -> post_script M M M M String String 2.8 Post upgrade script that will run to get status of upgrade
app -> post_upgrade -> initial_wait_time O O O O Number Number 2.8 Initial wait time to run post upgrade script
app -> resources -> network -> hint O O O O String String 2.8 Provide hints for a defined network.
app -> resources -> network -> type O O O O enum["external", "east-west", "eobc"] String 2.8 Pick from enum options
app-> resources -> persistent_data_target O O O O String String 2.9 Customize persistent data dir path mounted by IOx inside the app. Default path is /data.
app-> resources -> container-size O O O O String/Integer String/Integer 2.9 For docker apps run as lxc container specify custom read-write layer size, else default 20% of rootfs will be provisioned
app-> resources -> ramfs -> size O O O O String String 2.9 RAM fs size in MB.
app -> startup -> accessmode O O O O enum["readonly","readwrite"] String 2.9 Pick from Enum options. For readonly - Verification of application signature and rootfs checksum verification will be done during activation, irrespective of app signing is enabled or disabled on the device.
app -> devices -> alias O O O O String String 2.10 Alias name for devices which will be auto-selected during activation if it matches with that found on the platform.
app -> resources -> network -> mac_forward_disable_mask O O O O String/Integer String/Integer 2.10 Disable traffic forwarding on a particular MAC address.
app -> resources -> network -> mac_forward_enable_mask O O O O String/Integer String/Integer 2.10 Enable traffic forwarding on a particular MAC address.
app -> resources -> network -> mirroring O O O O Boolean Boolean 2.10 Bridge traffic mirroring capabulity.
app -> startup -> ** cdrom ** N/A N/A N/A O Object Object 2.10
app -> startup -> cdrom -> file N/A N/A N/A M String String 2.10 Support cdrom as boot device. Specify the file ".iso" to boot from
app -> startup -> cdrom -> target-dev N/A N/A N/A M String String 2.10 Specify the boot disk controller type HDA (for IDE) or SDA (for msata or iSCSI)
app -> resources -> ** copy-from-host ** O O O O Object Object 2.11 Capability to copy from host to app.
app -> resources -> copy-from-host -> parent-dirname M M M M String String 2.11 Parent path on the host from which data is copied.
app -> resources -> copy-from-host -> nested-dirname O O O O String String 2.11 Nested dir name under parent path.
app -> kernel-version N/A O N/A N/A String String 2.11 Used for lxc apps. Deprecated, not required since schema version 2.11.

Additional Package Descriptor Information From the Table

  • app -> kernel-version: This is applicable for LXC style applications. The hosting platform will let the application run only if MAJOR_HOST == MAJOR_APP, MINOR_HOST >= MINOR_APP. The major versions of the kernel on the host must match the major version required by the application. Minor version on the host must be >= the minor version required by the app.
  • app > resources -> profile: Each definition translates into CPU units and memory in MB. If the pre-defined profiles are not suitable, this can be specified as "custom" and required values can be specified in subsequent sections.
  • app -> resources -> recommendations: Example recommendation: For profile c1.small, the app can scale to 50 sensors, but for profile c1.large, it can scale to 100.

Generate IOx Package Descriptor File Through Dockerfile LABEL

Package descriptor file can be generated using IOxclient all based on the information available from the Docker image (CMD, USER, AUTHOR, ENTRYPOINT, ENV, USER, EXPOSE and WORKDIR instructions). Defualt values are overridden by user specified values via Docker labels: Docker commands

Example LABELs used in Dockerfile:

LABEL cisco.descriptor-schema-version="2.12" \
           cisco.info.name="Cisco user" \
           cisco.info.description="Cisco End Client" \
           cisco.info.version="0.1" \
           cisco.info.author-link=" https://www.cisco.com " \
           cisco.info.author-name="Cisco Systems, Inc." \
           cisco.type=docker \
           cisco.cpuarch=x86_64 \
           cisco.resources.profile=custom \
           cisco.resources.cpu=54 \
           cisco.resources.memory=64 \
           cisco.resources.disk=2 \
           cisco.resources.network.0.interface-name=eth0 \
           cisco.resources.network.1.interface-name=eth1 \
           cisco.resources.network.0.voice-vlan="'true'"

package.yaml file (as well as iox package) can be generated by using ioxclient command "ioxclient docker package --name <iox package name> <docker image name> <package dir>" based on the docker image built from Dockerfile:

descriptor-schema-version: "2.12"
info:
    name: Cisco user
    description: Cisco End Client
    version: "0.1"
    author-link: https://www.cisco.com
    author-name: Cisco Systems, Inc.
app:
    cpuarch: x86_64
    env:
        PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
        http_proxy:
        https_proxy:
    resources:
        cpu: 54
        disk: 2
        memory: 64
        network:
        - interface-name: eth0
          ports: {}
          voice-vlan: true
        - interface-name: eth1
        profile: custom
    type: docker

Complete List of Dockerfile LABELs:

Dockerfile_labels

JSON Specification

The rules associated with the descriptor file is defined formally as a JSON Schema Draft 4 document.

View the schema definition files here: