Page tree
Skip to end of metadata
Go to start of metadata

This page is intended to provide instructions for using Docker images in the context of OPEN-O Mercury Release.

Each OPEN-O Docker images is preconfigured to run a micro service.

Note

This page was developed as a way to convey within the OPEN-O Mercury Release community the procedures to get intermediate builds installed and configured on Docker. As such, the links provided below point to Docker images that are the most up-to-date Docker images. In other words, these Docker images are current development images. Use theses Docker images with that information in mind. The OPEN-O Mercury Release (Sign-Off on April 27, 2017) Docker images can be downloaded from this Hub Docker location (Tag 2.0.0)

 

 

Docker: The basics (Video Record)

Topic: Basic Training Session for how to use docker image (in Chinese??) 
Date: Oct 25, 2016 4:53 PM (GMT-7:00) Pacific Time (US and Canada)

 

Recording-1 (98 MB) 
Video Record

Getting Started

Install Docker

On CentOS:

 

sudo yum install docker
sudo systemctl enable docker.service
sudo systemctl start docker.service

 

On Ubuntu:

sudo apt install docker.io

Install Docker Toolbox https://www.docker.com/products/docker-toolbox requires Virtualbox. Docker will run in a VM, and it is called docker-machine

 

Proxy: If you are behind a company proxy you need to configure the docker-machine

docker-machine ssh default
sudo -s
echo "export HTTP_PROXY=http://[uid]:[pw]@corporate.proxy.com:[port]" >> /var/lib/boot2docker/profile
echo "export HTTPS_PROXY=http://[uid]:[pw]@corporate.proxy.com:[port]" >> /var/lib/boot2docker/profile
exit
exit
docker-machine restart default

CLIENT

Pre-requisites

Run Mircorservice Bus (MSB) and Auth service and make sure auth service is registered in the MSB properly

Run Open-O GUI

  1. Run command : docker pull openoint/client-gui (or Download https://hub.docker.com/r/openoint/client-gui)
  2. Run command : docker run -i -t --name clien-gui -e MSB_ADDR=172.17.0.2:80 openoint/client-gui
    This will launch the Openo CLI container with Bash console and configure them to use with given MSB URL.
  3. Open the web browser and enter URL : http://localhost/openoui/login/index.html

Run Open-O CLI

  1. docker pull openoint/client-cli (or Download https://hub.docker.com/r/openoint/client-cli)
  2. run docker run -i -t -e MSB_ADDR=172.17.0.2:80  -e OPENO_USERNAME=admin -e OPENO_PASSWORD=password --name openo-cli  openoint/client-cli This will launch the Openo CLI container with Bash console and configure them to use with given MSB URL.
  3. Run the Open-O command by using the command openo

Run Microservice Bus

First, get the latest image for the MSB. Later you might want to re-pull periodically (maybe once a day) to get the latest changes.

docker pull openoint/common-services-msb

Then, boot the MSB image in a container.

docker run -i -t --name i-msb openoint/common-services-msb

The --name allows us to associate an easy name to go with this container. The -i -t means to attach an interactive TTY to the container; this also means that if you press Ctrl-C, you will terminate the container.

At this point you should see the log messages from MSB. Congratulations, you have successfully started the MSB!

From a new window, find out what the container ID is for the MSB container you just started:

docker ps
CONTAINER ID        IMAGE                          COMMAND                  CREATED             STATUS              PORTS               NAMES
69fff7d692f4        openoint/common-services-msb   "/bin/sh -c /service/"   8 seconds ago       Up 8 seconds        80/tcp              i-msb

In this example, my container ID is 69fff7d692f4. Yours will vary. You also note that the container was named "i-msb".

Now we wish to find out what IP address this container has:

docker inspect --format '{{ .NetworkSettings.IPAddress }}' i-msb
172.17.0.2

In this example, the MSB's container has the IP address 172.17.0.2. Make a note of the MSB's IP address, as you will need to pass it in as a parameter to all other containers.

Open a browser window, and point it to the MSB's IP address at port 80, and you should be able to see the MSB's web UI.

NOTE: If you are running the docker containers inside a VM, note that by default the docker container IP addresses are only visible inside that VM. To deal with this you can either start a browser within the VM, or by mapping a port as shown below.

You can map a port on a container to a port of the host VM by adding the -p parameter to the docker run command seen earlier:

docker run -i -t --name i-msb -p 80:80 openoint/common-services-msb

This will allow you to access the container's port from outside the VM by accessing port 80 of the host VM.

NOTE PER OSx / Windows

In this case you have installed the Docker Toolbox that uses a VM in Virtualbox where Docker runs. In order to use the browser in the host to access the MSB, you have also to map ports from the Host OS to the docker-machine. You can accomplish this by configuring the port forwarding in the Virtualbox Manager (Settings->Network->Adapter1->Advanced->Port Forwarding) or by issuing the following command:

 docker-machine ssh -L <hostport>:<localhost>:<port>

Of course before running the containers For more info there is a script here https://github.com/johanhaleby/docker-machine-port-forwarder


Let the MSB continue running in its own window so that you can easily see the log messages. There is a way to run containers in background mode so that you don't have to keep so many windows open, but let's not worry about that for now.

Run External System Register

First, pull the ESR image:

docker pull openoint/common-services-extsys

Then, boot the ESR image, making sure that you change the IP address for your own:

docker run -i -t -e MSB_ADDR=172.17.0.2:80 openoint/common-services-extsys

The -e parameter allows us to define environment variables for the container. All of the Open-O docker containers are designed to expect the MSB's IP and port be passed in an environment variable named MSB_ADDR. The default port for the MSB is 80.

Wait a little bit, and refresh your MSB browser UI. You should now see that "extsys" has added itself as an API service to your instance of MSB. Congratulations, you have now successfully started ESR!

Run Driver Manager

Hopefully by now you have a better sense as to what to do next:

docker pull openoint/common-services-drivermanager
docker run -i -t -e MSB_ADDR=172.17.0.2:80 openoint/common-services-drivermanager

Wait a little bit, and refresh your MSB browser UI. You should now see that "drivermgr" has added itself as an API service to your instance of MSB. Congratulations, you have now successfully started the Driver Manager!

Memory

It is possible to see how much memory each container is using by running

docker stats $(docker ps --format={{.Names}})

By default each container is limited to a max mem, and in some circumstances you might decide to change this.

To change the default you should add the parameter -m <value>M in the docker run, for example:

 docker run -p 80:80 -m 500M --name i-msb8 openoint/common-services-msb

Docker Image Status

Check Docker Image Status to see the latest status on which docker images are working, which ones need to be fixed, which ones haven't been tested, etc.

Testing, Debugging, and Fixing a Docker Image

So far you have only run the docker images directly, and pressing Ctrl-C will terminate the container. What if you want to explore what's inside a container?

Exploring a Docker Container

Using the example of the ESR, do:

docker run -i -t -e MSB_ADDR=172.17.0.2:80 --entrypoint /bin/bash openoint/common-services-extsys
[root@cb1909d6a0d0 service]#

The difference from before is the addition of "--entrypoint /bin/bash" in the parameters. What this does is, instead of running the pre-configured entrypoint script, runs an alternate program called "/bin/bash". What you should now see is a shell command prompt; you are now running bash inside the container instance, and you can look around. The default entrypoint script will NOT have executed.

For example, you can run the "ls" command:

[root@cb1909d6a0d0 service]# ls
conf  dbscripts  docker-entrypoint.sh  extsys-service.jar  init-mysql.sh  initDB.sh  instance-config.sh  instance-init.sh  instance-run.sh  instance-workaround.sh  run.sh  stop.sh

You can go into the various directories, read/modify any files, and run any code inside a container as if it were a virtual machine. Once you're done exploring, exiting bash (exit or Ctrl-D) will cause the container to terminate.

Microservice Directory Structure

All of the Open-O docker images have been set up with an uniform structure:

  • The microservice is placed in the top level directory /service
  • All binaries and dependencies (e.g. Tomcat) have been unzipped into /service
  • In addition, there are always five files placed in /service that compose the entrypoint script structure:
    • docker-entrypoint.sh # main entrypoint script; do not modify
    • instance-config.sh # modify config files based on environment variables, e.g. $MSB_ADDR
    • instance-workaround.sh # workarounds for defects in the release binary
    • instance-init.sh # one-time initialization, e.g. create database schema
    • instance-run.sh # runs the microservice

Let's see some example files from the ESR image.

docker-entrypoint.sh

This is the main script that gets run by default when you start a Open-O microservice container. You should not modify this script, as it is auto-generated based on metadata about the microservice (e.g. does it require MySQL), but it is shown here so that you can see how it invokes the instance-* scripts.

[root@cb1909d6a0d0 service]# cat docker-entrypoint.sh 
#!/bin/bash
#
# This file was auto-generated by gen-all-dockerfiles.sh; do not modify manually.
#
# ./common-services-extsys/docker-entrypoint.sh
#

if [ -z "$MSB_ADDR" ]; then
    echo "Missing required variable MSB_ADDR: Microservices Service Bus address <ip>:<port>"
    exit 1
fi

# Configure service based on docker environment variables
./instance-config.sh

# Perform one-time config
if [ ! -e init.log ]; then
    # Perform workarounds due to defects in release binary
    ./instance-workaround.sh
    # Init mysql; set root password
    ./init-mysql.sh

    # microservice-specific one-time initialization
    ./instance-init.sh

    date > init.log
fi

# Start the microservice
./instance-run.sh

The key thing to note is that instance-workaround.sh and instance-init.sh are set up to run only once, even if a container is stopped and restarted multiple times. instance-config.sh and instance-run.sh, by contrast, will run every time the container is restarted.

instance-config.sh

The instance-config.sh script should handle modifying any config files required by the microservice. The most common use is to update a config file based on the environment variables passed into the container. For example, usually a config file needs to be changed to specify the MSB's IP/port. Here is the example from ESR:

[root@cb1909d6a0d0 service]# cat instance-config.sh 
# Configure MSB IP address
sed -i "s|msbServerAddr:.*|msbServerAddr: http://$MSB_ADDR|" conf/extsys.yml
cat conf/extsys.yml

The cat command at the end helps you verify from the logs that the configuration successfully modified the config files.

instance-workaround.sh

The instance-workaround.sh is there to handle workarounds for defects in the release binary. Ideally this script should be empty; any workarounds placed here should be logged as a bug for the respective project team to fix. The goal is that once the defect is fixed, then the workaround will not be necessary anymore.

Let's see an example from openoint/common-tosca-inventory:

[root@de2228a9755e service]# cat instance-workaround.sh 
# strange character on line 17 of all the SQL scripts
sed -i -e '17d' dbscripts/mysql/*.sql

This script deletes line 17 from all the .sql scripts in the dbscripts/mysql/ directory.

instance-init.sh

The instance-init script handles one-time initialization steps required by the microservice, specifically things that should only the first time the container is started, but not when it is stopped and restarted. The typical use case is to initialize the MySQL database schema. See the example from ESR:

[root@cb1909d6a0d0 service]# cat instance-init.sh 
# Initialize DB schema
./initDB.sh root rootpass 3306 127.0.0.1

The initDB.sh script in this case was a script provided by the ESR binary.

instance-run.sh

The instance-run.sh is the command that actually starts the microservice after all the preparation is done. As the last command in the entrypoint script, this command should remain running in the foreground and not terminate; once it terminates, the container stops.

Let's see an example from ESR:

[root@cb1909d6a0d0 service]# cat instance-run.sh
# Start service
./run.sh

The ESR instance-run.sh is simple because run.sh runs in the foreground and remains running.

What if the default run script provided by the binary actually starts a process in the background? If we just run it by itself, it will return immediately, and instance-run.sh will terminate, causing the container to terminate. So, we need to run something else that will remain running in the foreground. Using "tail -F" to poll a log file is a good choice for this. Let's see an example from openoint/common-services-protocolstack:

[root@a520b73d239b service]# cat instance-run.sh 
# Start microservice
cd bin
./start.sh
while [ ! -e ../logs/protcolstack.log ]; do
    sleep 1
done
tail -F ../logs/protcolstack.log

How to Fix a Docker Image?

The ultimate goal and process of testing and configuring the Docker image is to set up the following scripts:

  • instance-config.sh
  • instance-workaround.sh
  • instance-init.sh
  • instance-run.sh

so that the microservice can start automatically using the pre-defined docker-entrypoint.sh script.

Typical Flow

Create a directory where you'll store a local copy of the instance-*.sh scripts. Go to that directory.

Create a new container from an image without starting it. This return a container ID. Let's store that in a variable directly:

CONTAINER=`docker create -i -t -e MSB_ADDR=172.17.0.2:80 --entrypoint /bin/bash openoint/common-services-extsys`
echo $CONTAINER
a39b0bbaced3306e77280762ec21e76e21083c7ef84baa20b801086940147107

Copy the default instance-* scripts out of the container to your local machine:

docker cp $CONTAINER:/service/instance-config.sh .
docker cp $CONTAINER:/service/instance-workaround.sh .
docker cp $CONTAINER:/service/instance-init.sh .
docker cp $CONTAINER:/service/instance-run.sh .

If you like, you may locally version control these scripts so that you can experiment with them.

Once you made some changes, and you want to try to run them in the container, do the following.

Copy the new scripts back into the container:

docker cp instance-config.sh $CONTAINER:/service
docker cp instance-workaround.sh $CONTAINER:/service
docker cp instance-init.sh $CONTAINER:/service
docker cp instance-run.sh $CONTAINER:/service

Boot the container. Note that since we created the container using "--entrypoint /bin/bash", this will drop you directly into the bash shell without running docker-entrypoint.sh.

docker start -a -i $CONTAINER
[root@a39b0bbaced3 service]# 

 

Look around and verify that the scripts are what you have copied in from your local machine. Once everything looks good, run docker-entrypoint.sh:

[root@a39b0bbaced3 service]# ./docker-entrypoint.sh

Hopefully everything works. If not, terminate the process or container, and fiddle with the instance-*.sh scripts some more. Make sure that if you make some changes to the scripts inside the container that you want to keep, copy them out of the container to your local machine before you delete the container.

Since some of the script do one-time initialization, you may need to re-create a container from scratch instead of trying to get the same scripts to run multiple times in the same container. To do so, first exist from the current container.

[root@a39b0bbaced3 service]# exit

Remove the existing container that is no longer running:

docker rm $CONTAINER

Now you can create a fresh new one using the same instruction as before:

CONTAINER=`docker create -i -t -e MSB_ADDR=172.17.0.2:80 --entrypoint /bin/bash openoint/common-services-extsys` 

Actually you can create new containers without deleting old ones; they just take up space.

It works! Now what?

Once you have a working set of instance-*.sh scripts for a particular microservice, please email them to (me) Gary Wu <gary.i.wu@huawei.com>. I'll check them into the Open-O source control and push out a new docker image definition.

Available SDNO Docker Images

Browse Open-O Docker Images for the full list of available images.

 * sdno-monitoring                        SDNO Monitoring
 * sdno-optimize                          SDNO Optimize
 * sdno-service-brs                       SDNO Services BRS
 * sdno-service-ipsec                     SDNO Services IpSec
 * sdno-service-l2vpn                     SDNO Services L2VPN
 * sdno-service-l3vpn                     SDNO Services L3VPN
 * sdno-service-lcm                       SDNO Services LCM (model driven version of sdno-service-nslcm, mutually exclusive installation)
 * sdno-service-mss                       SDNO Services MSS
 * sdno-service-nslcm                     SDNO Services Nslcm
 * sdno-service-overlayvpn                SDNO Services Overlay VPN
* sdno-service-route         SDNO Services Route * sdno-service-servicechain SDNO Services Service Chain
* sdno-service-site         SDNO Services Site * sdno-service-vpc SDNO Services VPC * sdno-service-vxlan SDNO Services VxLAN * sdno-vsitemgr SDNO Vsite Manager

SDNO Docker images for simulated Network Services

  • openoint/simulate-sdno-services

Starting entire SDNO from Docker containers

The scripts for pulling and running SDNO related containers are  available in Gerrit.

Memory usage

SDN-O

These are the values obtained on a machine with Ubuntu 16.04 LTS 64-bit, 15.6 GB RAM

Dockerfiles downloaded 7th March 2017

imageAllocated Memory in Mbytes
openoint/common-services-drivermanager689.2
openoint/common-services-extsys634.4
openoint/common-services-msb146.4
openoint/sdno-service-brs243.4
openoint/sdno-service-ipsec237.8
openoint/sdno-service-l2vpn238.8
openoint/sdno-service-l3vpn256.4
openoint/sdno-service-lcm505.8
openoint/sdno-service-mss918.1
openoint/sdno-service-nslcm324.6
openoint/sdno-service-route272
openoint/sdno-service-overlayvpn162
openoint/sdno-service-servicechain257.7
openoint/sdno-service-site251.6
openoint/sdno-service-site260.4
openoint/sdno-service-vxlan253
openoint/sdno-vsitemgr517.8
openoint/sdno-optimize499.8
openoint/sdno-monitoring436.4
Total memory used:7,105.60

 

Method:

  • Start the MSB image in a container using command:
docker run -i -t --name i-msb openoint/common-services-msb
  • Service starting check memory usage
docker run -i -t -e MSB_ADDR=172.17.0.2:80 openoint/$service_name
  • Check docker instance memory usage:

Find the instance ID using the command:

docker ps | grep $service_name”

Check memory usage for that instance using the command

docker stats –no-stream $container_id

Also you can check the entire memory usage by calculating the difference between memory usage of the OS before and after starting the image using “free –t -h”