To create an IoTC package, a specification file (YML) is required. The .yml file describes the content of the package and its associated metadata. You must create a .yml file before creating an IoTC package.

The package-cli.zip archive contains a example-iotc-package folder. Review the contents in this folder before creating the IoTC package.

Alternatively, you can use the following sample YML file as a template to create a file named test_package.yml. Change the values in the test_package.yml file according to your organization's requirements. 
package:
    manifest:
        headlessExecution: true
        lifecycle:
            # Note the paths written in the action sections. If they don't match
            # any of the install paths in the attachments section, the tool will
            # warn you, but it will make a package. This is so you can address
            # executables that are on the GW but not in this package, but this
            # requires a full path to be specified in the action section.
            - phase: verify
              action: <parent directories of build machine>/example-iotc-package/package-source/verify.sh
            - phase: execute
              action: <parent directories of build machine>/example-iotc-package/package-source/execute.sh

              # This phase's action matches the install path of the validate.sh
              # attachment, so no warning will be issued.
            - phase: validate
              action: <parent directories of build machine>/example-iotc-package/package-source/validate_package.sh

              # This phase's action points to an attachment that doesn't match
              # any install path, even though there is an attachment named activate.sh
            - phase: activate
              action: activate.sh
            - phase: reset
              action: <parent directories of gateway>/reset.sh
    attachments:
        # path describe where the attachments are on the system you're building the package.
        # installPath describes where on the gateway the attachment will be installed.
        # If no installPath is added, the 'path' value will be used.
        # Any the directories in the installPaths that don't exist on the gateway
        # will be created.
        - path: <parent directories of build machine>/example-iotc-package/package-source/test_file.txt
        - path: <parent directories of build machine>/example-iotc-package/package-source/verify.sh
        - path: <parent directories of build machine>/example-iotc-package/package-source/execute.sh
        - path: <parent directories of build machine>/example-iotc-package/package-source/validate.sh
          # This will install the validate.sh attachment
          # in the same directories but named validate_package.sh
          installPath: <parent directories of build machine>/example-iotc-package/package-source/validate_package.sh
        - path: <parent directories of build machine>/example-iotc-package/package-source/activate.sh
        - path: <parent directories of build machine>/example-iotc-package/package-source/reset.sh
          # You can specify a completely different directory
          # for attachment installation
          installPath: <parent directories of gateway>/reset.sh

    name: hello_iotcp

    # This is one of the many ways you can create a multiline string in yaml
    description: "A test IoT Center package with\n
    a multiline description."

    version: 1.1.0

    # This tag is empty. That means the tool will default to noarch.
    architecture:

    # This is just a string so you could write anything, but there are
    # standardized names for many of the operating systems.
    # If this tag is empty, the tool will use the value which was
    # used to compile it for the certain OS (windows, linux or darwin).
    # If it can't read the compile-time value or it's empty, it will
    # default to noos.
    os: linux

    # This is a simple array of strings which are just that - labels by
    # which you could search a package in Pulse IoT Center
    labels:
      - test
      - example
In this example:
The attachments section lists the files to be included in the package:
  • path - The path on the disk where the file to be included in the package is located.
  • installPath - The path on the gateway where the attachments are installed.
    Note:
    • If installPath is not specified, the path value is used.
    • If any of the directories specified in the installPath do not exist, they are created on the gateway if the iotc-user has the required permissions.

The manifest section describes the package lifecycle and execution. It allows custom actions to be associated with lifecycle events.

The headlessExecution flag:
  • Controls the automatic transition of each lifecycle phase, without any interaction. By default, the value is true.
  • If headlessExecution is set to true and the IoTC Agent is configured with manifestExecution = ENABLED, then the campaign runs automatically without any interaction.
  • If headlessExecution is set to false and the IoTC Agent is configured with manifestExecution = ENABLED, then the campaign scheduling depends on an external input such as DefaultClient or SDK client that must be registered with the IoTC Agent. The executable specified for a particular phase is run by the IoTC Agent at each lifecycle phase.
  • If the IoTC Agent is configured with manifestExecution = DISABLED, then the headlessExecution property and the executable steps are ignored. Here, all the associated executables are disabled and an SDK client must be configured to run the campaign.
action - An executable file that performs the required tasks for the current phase. For example, the executable file performs tasks such as verifying the downloaded content, setting up the environment, running the installer, and validating whether the installation is successful. The executable file is run in an isolated shell that has the environmental variable DATADIR set to the path of the directory that contains the extracted package files. If relative paths are used, DATADIR is set to access the files. For example, the path to access the update_data.tar.gz file is: 
$DATADIR/update_data.tar.gz
Note:
  • All the files from the package with relative paths are deployed in a unique directory at the default path that is configured in the IoTC Agent. The default path can be found in the iotc-agent configuration file, at agent host: /opt/vmware/iotc-agent/conf/iotc-agent.cfg. 
    agentDataDirPath = /opt/vmware/iotc-agent/data
  • Ensure that you provide appropriate access and execution rights to the files, if needed. You can provide permissions through the executables for the lifecycle phases.
  • You can specify a relative or an absolute install path for the attachments. If you do not specify the install path, the Package Management CLI tool creates an install path for each attachment.

The lifecycle section defines the different lifecycle phases and the corresponding action to take for each phase. For the IoTC Agent to locate an action executable after the payload is extracted, and to run the executable, the action path must match the installPath in the attachments section. Or, the action path must point to an existing executable on the gateway. The specification file also specifies the external executables to run at each lifecycle phase.

The lifecycle phases are:
  • ENTRYPOINT
  • VERIFY
  • EXECUTE
  • VALIDATE
  • ACTIVATE
  • RESET

You can attach executables to all lifecycle phases except the ENTRYPOINT phase. The executable for the ENTRYPOINT phase must be present on the Gateway's file system and ready to run.

These lifecycle phases are optional. If you use lifecycle phases, you cannot modify the phases or the order in which the phase actions are run. If you do not specify executables in the action field, then no action is performed and the phase is considered to pass successfully and the lifecycle moves to the next phase. For example, if you do not provide a verify.sh executable in the VERIFY phase, the package runs without verification (other than the default verification steps provided in the packaging format, such as checksum and RPM signatures), and moves to the VALIDATE state. This process continues until the package moves to the ACTIVATE phase. The phases ACTIVATE and RESET are mutually exclusive. The update is either activated or reset depending on the VALIDATE phase result.
Note:
  • For all the executables that are attached for the action field, the IoTC Agent sets the execute permission to (700 / -rwx------) for the iotc user by default.
  • If there are other executables listed in packages/files/scripts beside the executables that are specified in the action field, the author of the executables must manage the required permissions.
The architecture and os sections are strings that describe the operating system and architecture that the package is built for. If the architecture or os sections are not present or have empty values, the Package Management CLI tool detects the values. These values are supplied to the Package Management CLI tool when building the tool itself. The Package Management CLI tool is available in the following variants. These variants are available in a downloadable file within the package-cli.zip file:
  • OS = linux, Architecture = amd64
  • OS = darwin, Architecture = 386
  • OS = windows, Architecture = amd64
  • OS = windows, Architecture = 386
You cannot use a variant of the Package Management CLI tool that is not built for the specific system architecture or operating system. For example, you cannot use the Windows Package Management CLI tool on a Linux machine. This way, the Package Management CLI tool detects the system architecture or operating system and populates them with the values that are built into the tool. The default operating system values that are built in for detection are Windows, MacOS, and Linux. The tool defaults to noos if it is unable to detect an operating system. Similarly, the Package Management CLI tool defaults to noarch if it is unable to detect a system architecture.