
================================================================================
README for App QoS Docker container

October 2021
================================================================================

CONTENTS
========

- Building
- Usage

BUILDING
========

Run ./build_docker.sh script to build App QoS docker container locally

$ sudo ./build_docker.sh
...
Successfully built 8a3f2216bbe3
Successfully tagged appqos:latest

USAGE
=====

At first, prepare directory with App QoS config and certificate - this directory will be shared with
the running container. Name of this directory and location doesn't really matter but make sure that
it will be accessible only to the 'root' user:

$ mkdir -p /opt/intel/appqos/
$ chmod 700 /opt/intel/appqos/

Then, create there 'appqos.conf' configuration file with an empty configuration

$ cd /opt/intel/appqos/
$ cat > appqos.conf <<EOF
{"apps": [], "sstbf": {"configured": false}, "pools": [], "power_profiles_expert_mode": true}
EOF

Now it is time to copy ca.crt, appqos.crt and appqos.key files for mutual TLS connection to
directory that we have just created. Instructions for creating certificate files for App QoS mTLS
connection can be found at: https://github.com/intel/intel-cmt-cat/blob/master/appqos/README.md in
section 'Creating evaluation mTLS certificate for testing'

When configuration file is prepared and certificate files are in place, the directory is ready to
be shared with the App QoS container:

$ ls -l
total 16
-rw-r--r-- 1 root root   94 Apr  7 15:50 appqos.conf
-rw-r--r-- 1 root root 1428 Apr  7 17:44 appqos.crt
-rw------- 1 root root 2484 Apr  7 17:44 appqos.key
-rw-r--r-- 1 root root 1545 Apr  7 17:44 ca.crt

$ sudo docker run --privileged --env APPQOS_PORT=5000 --expose 5000 \
-v /opt/intel/appqos:/opt/intel/appqos \
--mount type=bind,bind-propagation=shared,source=/sys/fs,target=/sys/fs \
--pid=host --network=host --rm -it appqos
...
2021-06-25 11:34:35,874 INFO  Interface MSR, MBA BW: unsupported.
2021-06-25 11:34:35,879 INFO  Interface OS, MBA BW: supported.
2021-06-25 11:34:35,879 INFO  Supported RDT interfaces: ['msr', 'os']
2021-06-25 11:34:35,887 INFO  RDT initialized with 'os' interface
2021-06-25 11:34:36,065 INFO  Supported capabilities:
2021-06-25 11:34:36,065 INFO  ['l3cat', 'mba']
2021-06-25 11:34:36,097 INFO  SST-BF not enabled
2021-06-25 11:34:36,097 INFO  Power Profiles/EPP not enabled
2021-06-25 11:34:36,097 INFO  Configuring RDT
2021-06-25 11:34:36,272 INFO  RDT MBA CTRL disabled
2021-06-25 11:34:36,278 INFO  Configuration changed, processing new config...
2021-06-25 11:34:36,284 INFO  New configuration processed

Note: For security reasons the container should not be exposed to any external network interfaces.

Explanation of options used:
--privileged - run container in privileged mode to get access to device drivers
--env APPQOS_PORT=5000 --expose 5000 - run App QoS on port 5000 and expose that port outside of the container
-v /opt/intel/appqos:/opt/intel/appqos - shared volume with App QoS configuration and mTLS certificates
--mount type=bind,bind-propagation=shared,source=/sys/fs,target=/sys/fs - share fs directory with container for resctrl interface
--pid=host - needed for access to host processes from container
--network=host - (optional) map container exposed ports to localhost port
--rm - remove container after use