Configure a Small Alpine Linux Docker Image on IOx

Introduction

This document describes the configuration process in order to create, deploy and manage Docker-based applications on Cisco IOx-capable devices.

Prerequisites

Requirements

There are no specific requirements for this document.

Components Used

The information in this document is based on these software and hardware versions:

• IOx capable device that is configured for IOx:
  
  • IP address configured
  • Guest Operating System (GOS) and Cisco Application Framework (CAF) running
  • Network Address Translation (NAT) configured for access to CAF (port 8443)
  • NAT configured for access to GOS shell (port 2222)
• Linux host (a minimal CentOS 7 installation is used for this article)
• IOx client installation files which can be downloaded from: https://software.cisco.com/download/release.html?mdfid=286306005&softwareid=286306762

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, make sure that you understand the potential impact of any command.

Background Information

IOx can host different types of packages mainly Java, Python, LXC, Virtual Machine (VM) etc, and it can also run Docker containers. Cisco offers a base image and a complete Docker hub repository: https://devhub.cisco.com/artifactory/webapp/#/artifacts/browse/tree/General/iox-docker that can be used to build Docker containers.

Here is a step-by-step guide on how to build a simple Docker container with the use of Alpine Linux. Alpine Linux is a small Linux image (around 5MB), which is often used as a base for Docker containers. In this article, you start from a configured IOx device, an empty CentOS 7 Linux machine and you build a small Python web server, package it in a Docker container and deploy that on an IOx device.

Configure

1. Install and prepare IOx client on the Linux host.

IOx client is the tool that can package applications and communicate with the IOx-capable device to manage IOx applications.

After you download the ioxclient installation package, it can be installed as follows:

[jedepuyd@db ~]$ ll ioxclient_1.3.0.0_linux_amd64.tar.gz
-rw-r--r--. 1 jedepuyd jedepuyd 4668259 Jun 22 09:19 ioxclient_1.3.0.0_linux_amd64.tar.gz

[jedepuyd@db ~]$ tar -xvzf ioxclient_1.3.0.0_linux_amd64.tar.gz
ioxclient_1.3.0.0_linux_amd64/ioxclient
ioxclient_1.3.0.0_linux_amd64/README.md

[jedepuyd@db ~]$ ./ioxclient_1.3.0.0_linux_amd64/ioxclient --version
Config file not found : /home/jedepuyd/.ioxclientcfg.yaml
Creating one time configuration..
Your / your organization's name : Cisco
Your / your organization's URL : www.cisco.com
Your IOx platform's IP address[127.0.0.1] : 10.48.43.197
Your IOx platform's port number[8443] :
Authorized user name[root] : admin
Password for admin :
Local repository path on IOx platform[/software/downloads]:
URL Scheme (http/https) [https]:
API Prefix[/iox/api/v2/hosting/]:
Your IOx platform's SSH Port[2222]:
Activating Profile default
Saving current configuration
ioxclient version 1.3.0.0

[jedepuyd@db ~]$ ./ioxclient_1.3.0.0_linux_amd64/ioxclient --version
ioxclient version 1.3.0.0

As you can see, on the first launch of IOx client, a profile can be generated for the IOx device which you can manage with IOx client. In case you would like to do this later or if you want to add/change the settings, you can run this command later: ioxclient profiles create

2. Install and prepare Docker on the Linux host.

Docker is used to build a container and test the execution of our sample application.

The installation steps to install Docker heavily depends on the Linux OS you install it on. For this article, you can use CentOS 7. For installation instructions for different distributions, refer to: https://docs.docker.com/engine/installation/.

Install prerequisites:

[jedepuyd@db ~]$ sudo yum install -y yum-utils device-mapper-persistent-data lvm2
...
Complete!

Add the Docker repo:

[jedepuyd@db ~]$ sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
Loaded plugins: fastestmirror
adding repo from: https://download.docker.com/linux/centos/docker-ce.repo
grabbing file https://download.docker.com/linux/centos/docker-ce.repo to /etc/yum.repos.d/docker-ce.repo
repo saved to /etc/yum.repos.d/docker-ce.repo

Install Docker (accept the GPG key verification when you install):

[jedepuyd@db ~]$ sudo yum install docker-ce
...
Complete!

Start Docker:

[jedepuyd@db ~]$ sudo systemctl start docker

[jedepuyd@db iox_docker_pythonweb]$ vi Dockerfile
[jedepuyd@db iox_docker_pythonweb]$ cat Dockerfile
FROM alpine:3.3

RUN apk add --no-cache python
COPY webserver.py /webserver.py

In order to be able to access/run Docker as a regular user, add this user to the Docker group and refresh group membership:

[jedepuyd@db ~]$ sudo usermod -a -G docker jedepuyd
[jedepuyd@db ~]$ newgrp docker

Log in to Docker Hub:

Docker Hub contains the Alpine base image which you can use. In case you do not have a Docker ID yet, you need to register on: https://hub.docker.com/.

[jedepuyd@db ~]$ docker login
Log in with your Docker ID to push and pull images from Docker Hub. If you do not have a Docker ID, head over to https://hub.docker.com to create one.
Username: jensdepuydt
Password:
Login Succeeded

3. Create the Python web server.

Now that the preparation is done, you can start to build the actual application that can run on the IOx-enable device. 

[jedepuyd@db ~]$ mkdir iox_docker_pythonweb
[jedepuyd@db ~]$ cd iox_docker_pythonweb/
[jedepuyd@db iox_docker_pythonweb]$ vi webserver.py
[jedepuyd@db iox_docker_pythonweb]$ cat webserver.py
#!/usr/bin/env python
from BaseHTTPServer import BaseHTTPRequestHandler, HTTPServer
import SocketServer
import os

class S(BaseHTTPRequestHandler):
    def _set_headers(self):
        self.send_response(200)
        self.send_header('Content-type', 'text/html')
        self.end_headers()

    def do_GET(self):
        self._set_headers()
        self.wfile.write("<html><body><h1>IOX python webserver</h1></body></html>")

def run(server_class=HTTPServer, handler_class=S, port=80):
    server_address = ('', port)
    httpd = server_class(server_address, handler_class)
    print 'Starting webserver...'
    log_file_dir = os.getenv("CAF_APP_LOG_DIR", "/tmp")
    log_file_path = os.path.join(log_file_dir, "webserver.log")
    logf = open(log_file_path, 'w')
    logf.write('Starting webserver....\n')
    logf.close()

    httpd.serve_forever()

if __name__ == "__main__":
    from sys import argv

    if len(argv) == 2:
        run(port=int(argv[1]))
    else:
        run()

This code is a very minimal Python web server, which you create in webserver.py. The web server simply returns IOx python webserver as soon as a GET is requested. The port on which the web server starts can either be port 80 or the first argument given to webserver.py.

This code also contains, in the run function, a write to a log file. The log file is available for consultation from the IOx client or local manager.

4. Create the Dockerfile and Docker container.

Now that you have the application (webserver.py) that should run in your container, it's time to build the Docker container. A container is defined in a Dockerfile:

[jedepuyd@db iox_docker_pythonweb]$ vi Dockerfile
[jedepuyd@db iox_docker_pythonweb]$ cat Dockerfile
FROM alpine:3.3

RUN apk add --no-cache python
COPY webserver.py /webserver.py

As you can see, the Dockerfile is also kept simple. You start with the Alpine base image, install Python and copy your webserver.py to the root of the container.

Once you have your Dockerfile ready, you can build the Docker container:

jedepuyd@db iox_docker_pythonweb]$ docker build -t ioxpythonweb:1.0 .
Sending build context to Docker daemon 3.584 kB
Step 1/3 : FROM alpine:3.3
3.3: Pulling from library/alpine
10462c29356c: Pull complete
Digest: sha256:9825fd1a7e8d5feb52a2f7b40c9c4653d477b797f9ddc05b9c2bc043016d4819
Status: Downloaded newer image for alpine:3.3
 ---> 461b3f7c318a
Step 2/3 : RUN apk add --no-cache python
 ---> Running in b057a8183250
fetch http://dl-cdn.alpinelinux.org/alpine/v3.3/main/x86_64/APKINDEX.tar.gz
fetch http://dl-cdn.alpinelinux.org/alpine/v3.3/community/x86_64/APKINDEX.tar.gz
(1/10) Installing libbz2 (1.0.6-r4)
(2/10) Installing expat (2.1.1-r1)
(3/10) Installing libffi (3.2.1-r2)
(4/10) Installing gdbm (1.11-r1)
(5/10) Installing ncurses-terminfo-base (6.0-r6)
(6/10) Installing ncurses-terminfo (6.0-r6)
(7/10) Installing ncurses-libs (6.0-r6)
(8/10) Installing readline (6.3.008-r4)
(9/10) Installing sqlite-libs (3.9.2-r0)
(10/10) Installing python (2.7.12-r0)
Executing busybox-1.24.2-r1.trigger
OK: 51 MiB in 21 packages
 ---> 81e98c806ee9
Removing intermediate container b057a8183250
Step 3/3 : COPY webserver.py /webserver.py
 ---> c9b7474b12b2
Removing intermediate container 4705922100e6
Successfully built c9b7474b12b2

[jedepuyd@db iox_docker_pythonweb]$ docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
ioxpythonweb        1.0                 c9b7474b12b2        11 seconds ago      43.4 MB
alpine              3.3                 461b3f7c318a        2 days ago          4.81 MB

The Docker build command downloads the base image and installs Python and dependencies, as you requested in the Dockerfile. The last command is for verification.

5. Test the created Docker container.

This step is optional but it's good to verify that your just built Docker container is ready to work as expected.

[jedepuyd@db iox_docker_pythonweb]$ docker run -ti ioxpythonweb:1.0
/ # python /webserver.py 9000 &
/ # Starting webserver...

/ # netstat -tlpn
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
tcp        0      0 0.0.0.0:9000            0.0.0.0:*               LISTEN      7/python
/ # exit

As you can see in the output of netstat, after you start the webserver.py, it listens on port 9000.

6. Create the IOx package with the Docker container.

Now that you have verified the functionality of your web server in the container, it's time to prepare and build the IOx package for deployment. As the Dockerfile provides instructions to build a Docker container, the package.yaml provides instructions for IOx client to build your IOx package.

jedepuyd@db iox_docker_pythonweb]$ vi package.yaml
[jedepuyd@db iox_docker_pythonweb]$ cat package.yaml
descriptor-schema-version: "2.2"

info:
  name: "iox_docker_pythonweb"
  description: "simple docker python webserver on port 9000"
  version: "1.0"
  author-link: "http://www.cisco.com"
  author-name: "Jens Depuydt"

app:
  cpuarch: "x86_64"
  type: docker
  resources:
    profile: c1.small
    network:
      -
        interface-name: eth0
        ports:
            tcp: [9000]

  startup:
    rootfs: rootfs.tar
    target: ["python","/webserver.py","9000"]

More information on the contents of the package.yaml can be found here: https://developer.cisco.com/media/iox-dev-guide-3-10-16/concepts/package_descriptor/.

After you create the package.yaml, you can start to build the IOx package.

First step is to export the root FS of the Docker image:

[jedepuyd@db iox_docker_pythonweb]$ docker save -o rootfs.tar ioxpythonweb:1.0

Next, you can build the package.tar:

[jedepuyd@db iox_docker_pythonweb]$ ../ioxclient_1.3.0.0_linux_amd64/ioxclient package .
Currently active profile:  default
Command Name: package
Checking if package descriptor file is present.
Validating descriptor file /home/jedepuyd/iox_docker_pythonweb/package.yaml with package schema definitions
Parsing descriptor file.
Found schema version  2.2
Loading schema file for version  2.2
Validating package descriptor file..
File /home/jedepuyd/iox_docker_pythonweb/package.yaml is valid under schema version 2.2
Created Staging directory at :  /tmp/700740789
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/700740789/artifacts.tar.gz
Calculating SHA1 checksum for package contents..
Parsing Package Metadata file :  /tmp/700740789/.package.metadata
Wrote package metadata file :  /tmp/700740789/.package.metadata
Root Directory :  /tmp/700740789
Output file:  /tmp/335805072
Path:  .package.metadata
SHA1 : 55614e72481a64726914b89801a3276a855c728a
Path:  artifacts.tar.gz
SHA1 : 816c7bbfd8ae76af451642e652bad5cf9592370c
Path:  package.yaml
SHA1 : ae75859909f6ea6947f599fd77a3f8f04fda0709
Generated package manifest at  package.mf
Generating IOx Package..
Package generated at /home/jedepuyd/iox_docker_pythonweb/package.tar

The result of the build is an IOx package (package.tar), which contains the Docker container, ready to be deployed on IOx.

Note: IOxclient can do the docker save command in one step as well. On CentOS, this results to export to the default rootfs.img instead of rootfs.tar, which gives trouble later in the process. The one step to create can be done with the use of: IOx client docker package IOxpythonweb:1.0.

8. Deploy, activate and start the package on the IOx device.

Last steps are to deploy the IOx package to the IOx device, activate it and start. These steps can either be done with the use of IOx client, Local Manager or Fog Network Director. For this article, you can use IOx client.

In order to deploy the package to the IOx device, use name python_web:

[jedepuyd@db iox_docker_pythonweb]$ ../ioxclient_1.3.0.0_linux_amd64/ioxclient app install python_web package.tar
Currently active profile:  default
Command Name: application-install
Installation Successful. App is available at: https://10.48.43.197:8443/iox/api/v2/hosting/apps/python_web
Successfully deployed

Before you can activate the application, you need to define how the network configuration would be. To do so, you need to create a JSON file. When you activate, it can be attached to the activation request.

[jedepuyd@db iox_docker_pythonweb]$ vi activate.json
[jedepuyd@db iox_docker_pythonweb]$ cat activate.json
{
    "resources": {
        "profile": "c1.small",
        "network": [{"interface-name": "eth0", "network-name": "iox-nat0","port_map": {"mode": "1to1"},"ports":{"tcp":9000}}]
    }
}
[jedepuyd@db iox_docker_pythonweb]$ ../ioxclient_1.3.0.0_linux_amd64/ioxclient app activate python_web --payload activate.json
Currently active profile :  default
Command Name: application-activate
Payload file : activate.json. Will pass it as application/json in request body..
App python_web is Activated

Last action here is to start the application which you just deployed and activated:

[jedepuyd@db iox_docker_pythonweb]$ ../ioxclient_1.3.0.0_linux_amd64/ioxclient app start python_web
Currently active profile :  default
Command Name: application-start
App python_web is Started 

Since you configured your IOx application to listen on port 9000 for tor HTTP-requests, you still need to forward that port from your IOx-device to the container as the container is behind NAT. Perform this on Cisco IOS® to do so.

BRU-IOT-809-1#sh iox host list det | i IPV4
    IPV4 Address of Host:       192.168.1.2
BRU-IOT-809-1#conf t
Enter configuration commands, one per line.  End with CNTL/Z.
BRU-IOT-809-1(config)#ip nat inside source static tcp 192.168.1.2 9000 interface GigabitEthernet0 9000
BRU-IOT-809-1(config)#exit

The first command lists the internal IP-address of GOS (responsible for start/stop/run the IOx containers).

The second command configures a static port forward for port 9000 on the Gi0 interface of the IOS-side to GOS. In case your device is connected via a L2 port (which is most likely the case on IR829), you need to replace the Gi0 interface by the correct VLAN which has the ip nat outside statement configured. 

Verify

Use this section in order to confirm that your configuration works properly.

In order to verify if the web server runs and responds properly, you can try to access the web server with this command.

[jedepuyd@db iox_docker_pythonweb]$ curl http://10.48.43.197:9000/
<html><body><h1>IOX python webserver</h1></body></html>

Or, from a real browser as shown in the image.

You can also verify the application status from the IOxclient CLI:

[jedepuyd@db iox_docker_pythonweb]$ ../ioxclient_1.3.0.0_linux_amd64/ioxclient app status python_web
Currently active profile :  default
Command Name: application-status
Saving current configuration
App python_web is RUNNING

and you can also verify the application status from the Local Manager GUI as shown in the image.

In order to have a look at the log file which you write to in webserver.py:

[jedepuyd@db iox_docker_pythonweb]$ ../ioxclient_1.3.0.0_linux_amd64/ioxclient app logs info python_web
Currently active profile :  default
Command Name: application-logs-info

Log file information for :  python_web
	Size_bytes : 711
	Download_link : /admin/download/logs?filename=python_web-watchDog.log
	Timestamp : Thu Jun 22 08:21:18 2017
	Filename : watchDog.log

	Size_bytes : 23
	Download_link : /admin/download/logs?filename=python_web-webserver.log
	Timestamp : Thu Jun 22 08:21:23 2017
	Filename : webserver.log

	Size_bytes : 2220
	Download_link : /admin/download/logs?filename=python_web-container_log_python_web.log
	Timestamp : Thu Jun 22 08:21:09 2017
	Filename : container_log_python_web.log

Troubleshoot

This section provides information you can use in order to troubleshoot your configuration.

In order to troubleshoot the application and/or container, the easiest way is to connect to the console of the application that runs:

[jedepuyd@db iox_docker_pythonweb]$ ../ioxclient_1.3.0.0_linux_amd64/ioxclient app console python_web
Currently active profile:  default
Command Name: application-console
Console setup is complete..
Running command: [ssh -p 2222 -i python_web.pem appconsole@10.48.43.197]
The authenticity of host '[10.48.43.197]:2222 ([10.48.43.197]:2222)' can't be established.
ECDSA key fingerprint is 1d:e4:1e:e1:99:8b:1d:d5:ca:43:69:6a:a3:20:6d:56.
Are you sure you want to continue connecting (yes/no)? yes
/ # netstat -tlpn
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
tcp        0      0 0.0.0.0:9000            0.0.0.0:*               LISTEN      19/python
/ # ps aux | grep python
   19 root       0:00 python /webserver.py 9000