Tutorial: Create Custom Package Descriptor for IOx Docker App

In this tutorial, we will go through how to define a custom package descriptor for IOx docker app. This custom package descriptor file is used to define attributes or resources apart from what is defined in the Docker image or override that specified in the Docker image.

Note: You can deploy a Docker image directly to an IOx enabled device, if a custom package descriptor specifications is not required. In this case, IOx infra will automatically create a package descriptor from the Docker image. Check this tutorial for more details.

Requirements

  • PC/Laptop with connectivity to the public Dockerhub registry
  • Docker daemon up and running on PC/Laptop
  • ioxclient (Download from here)

Package Descriptor

A package descriptor file represents the metadata and the resources required by the container application. The filename is called package.yaml. You can read more about package descriptor here.

Package descriptor is in yaml format and contains metadata attributes, for example: descriptor-schema-version, info, and app. Here is the package descriptor template with set of mandatory fields.

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>

Note: We recommend using a minimum of 2.8 as descriptor-schema-version.

Nginx Docker Image - Package Descriptor

In this section, we will create a custom package.yaml for nginx Dockerhub image (x86 CPU arch). Pull the nginx Docker image from Dockerhub to your local PC. For Cisco platforms with arm64v8 CPU arch, pull docker image (arm64v8/nginx:latest) for the corresponding architecture.

# If Cisco platform is x86_64 CPU architecture
$ docker pull nginx:latest

There are two approaches you can take with writing up package descriptor.

  1. You can start from scratch, manually define every required descriptor attribute for the Docker app following the documentation.
  2. You can autogenerate the package.yaml using ioxclient and then edit package descriptor.

We have examples for both these approaches in below sections.

Starting from scratch

Define the package descriptor with the below attributes for the nginx Docker container:

  • CPU/memory resource profile as default
  • Persistent storage disk size in MB
  • Env variables
  • One network interface with port to expose
  • Target command to run inside the container

Here is the nginx package.yaml descriptor file:

descriptor-schema-version: "2.8"
info: {name: nginx, version: latest, description: "Nginx Web App"}
app:
  cpuarch: x86_64
  type: docker
  profile: default
  disk: 10
  env: {NGINX_VERSION: "1.15.12", PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", PAYLOAD_SIZE: "100"}
  resources:
    network:
    - interface-name: eth0
      ports:
        tcp: ["80"]    
  startup:
    rootfs: rootfs.tar
    target: [nginx, -g, daemon off;]

Keep this package.yaml in our project working directory. We can create a final IOx package with this package descriptor using ioxclient tool as described below.

workdir$  ioxclient docker package  nginx:latest .

Autogenerate Using ioxclient

Instead of writing package.yaml manually from scratch, we can also utilize the ioxclient tool which autogenerates the package descriptor file for a given Docker image based on the configurations present in the image. For an nginx Docker image, you can run the following command to build an IOx package (package.tar) that also autogenerates a package.yaml under the current working directory.

workdir$  ioxclient docker package  nginx:latest .

workdir$  ls 
package.tar package.yaml

You can now edit this auto generated package.yaml as needed. You can read more about the package descriptor attributes here.

Once the changes are completed, rebuild the IOx package by issuing same command as above under same working directory. ioxclient will pick up the package.yaml in the current working directory if present, instead of autogenerating it. With this approach, you must run the ioxclient docker package command twice.

Summary

In this tutorial we learned how to create a custom package.yaml for a Docker image and build it into an IOx package for deployment.