Tutorial: Build Sample Docker Type Python Simple App
This page will demonstrate how to create a simple python docker image using the Cisco provided docker base image and package repository. We will then create an IOx package to be installed and deployed on Cisco's platform.
The goals of this tutorial are to demonstrate various development tasks and concepts and to implement a simple Python based Container application package using Docker tooling.
Sample Code
This sample application code is maintained here.
Clone this repo and use branch master. Find the application under the following directory: 'simple-python-app'
Some parts of the code may be reproduced in this document to give more context. But, always use the above git repo and branch for the latest code.
Procedure Overview
We will cover the following procedures:
- Implementing a simple python application
- Creating a docker image with python application
- Testing your application locally using docker tools
- Creating an IOx application package from the docker image
- Deploying and testing on the target platform
Before going through the tutorial, become familiar with cisco provided artifacts for an IOx app development.
We will write a simple Python application that virtually simulates gathering temperature data from the device and saving this information to a file poll-temp.log in /var/log directory.
Note: The application examples are demonstrated for IR800 platforms, but the same procedure will be applicable
for all other supported IOx platforms. Use the correct docker base image per the IOx platform.**Refer for images supported platforms & corresponding base images
Implementing a simple python application
Setup project directory
Writing a Python Application
Creating a docker image with python application
Let us create a docker image with the above application in it. In this tutorial we will develop an application for IR800(809/829).
We will use latest 'ir800/base-rootfs' base image from devhub-docker.cisco.com, update opkg package database, install python and
setup our application. In this example we will run our application in foreground when container starts.
Write a Dockerfile
Below is a Dockerfile that accomplishes these tasks:
Note: Assuming poll-temperature.py in the same directory as Dockerfile
Note: You could use a Dockerfile or build the image interactively (run the base devhub-docker.cisco.com:latest image with /bin/sh, run the commands in a shell and later commit the changes into a new image.)
Creating a docker image
Login to the devhub using docker daemon before building a docker image. Instructions for devhub login
Now let us build an image from this Dockerfile and tag it with a name (iox-simple-py:1.0).
Check your built image
Let us run the image locally to make sure it works fine. Since
In order to see your application collecting data we need to exec to the container
Note: This example is shown for x86 based docker container. At this step, to run a non-x86 docker container, respective qemu should be used.
Ex:
For an arm based docker container
docker exec -ti b5205d87312c4e6f058dcbf6289c3d18299127dd8f211407d581fd07b1092a6d /.iox/qemu-arm /bin/sh
For a ppc based docker container
docker exec -ti b5205d87312c4e6f058dcbf6289c3d18299127dd8f211407d581fd07b1092a6d /.iox/qemu-ppc /bin/sh
Package descriptor file
Package descriptor file specifies requirements for the application. For docker type applications, creating a package
descriptor file is an optional. ioxclient creates a default package descriptor file while creating IOx docker
application package. If the developer want to add custom entries in a package descriptor file, he can add those
entries using docker's LABEL directive. Ioxclient uses those labels, add it in a package descriptor
file during creation of an IOx docker application package.
Refer ioxclient page to learn how to use docker Label's
and package.yaml.
Here is a sample application descriptor (package.yaml) file looks like:
Note: If you are using application descriptor file for non x86 architecture, Refer the docker images table for appropriate value of "cpuarch" in yaml file
Ex: For ie4k platform use the 'cpuarch' as 'ppc' in following yaml file
Creating an IOx application package from the docker image
ioxclient (>= 1.4.0) provides a convenience command that generates an IOx application package from a docker image.
Refer this page for ioxclient usage: ioxclient
Let us use this command. First navigate to the project directory.
Create an empty directory ex. 'app_package' and execute the ioxclient command in this directory
Make sure the profile for target platform is created and activated before creating package
The package.tar is an IOx application package that can be used to deploy on an IOx platform.
Ensure that your target platform supports docker style applications. Refer to Platform Matrix for details about your platform. This tutorial uses IR829 as the target IOx platform.
We will use ioxclient to demonstrate deployment and lifecycle management of this application. You can do the same using Local Manager or Fog Director.
Add your device to ioxclient
Install, Activate and Test on the device
Install the app we just created on the target platform.
Let us activate with a bridge network and start the application.
Let us get the ip address of the application.
This tells us that the app's ip address is 192.168.1.47.
Note: Since this application is a client not a server, IOS NAT configuration is not required
Console login to the application container to check if the application was deployed successfully.
Summary
As part of this tutorial we saw:
- Using docker tools and image to quickly build simple python application
- Packaging a docker image into an IOx application package.
- Deploying this package to an IR829 router and testing the application functionality.