Use in Python Sandbox

This page is about running REDHAWK components, inside Docker containers, in the REDHAWK Python sandbox.

For the examples below, consider a user-defined component named sample_comp. A Docker image with the component is stored at registry location container-registry.my-company.org/my-project/sample-comp:latest.

XML Files in SDRROOT

SDRROOT should contain these files related to sample_comp:

SDRROOT/
    dom/
        components/
            sample_comp/
                sample_comp.prf.xml
                sample_comp.scd.xml
                sample_comp.spd.xml

To run sample_comp without using containers, the rest of sample_comp's files should also be in its directory.

To run in a container, only the 3 xml files are used. The complete set of files for the component is in its container. The PRF and SCD files are unchanged. The <code> portion of the SPD files should be modified like this:

<code type="Container">
      <localfile name="python"/>
      <entrypoint>python/sample_comp.py::sample_comp</entrypoint>
</code>

NOTE: These additions have not been reconciled with REDHAWK IDE. Viewing Components with spd.xml files modified in support of using these features will generate visual errors.

There are 2 changes:

The type attribute of code is now "Container".
The value of entrypoint has been expanded.

The first part of entrypoint is the same: python/sample_comp.py. Appended to that are

the separator ::
(part of) the container location

How the container location is specified depends on the orchestration type used.

Docker

The container location should be an entry that shows up under REPOSITORY for docker images. Given:

docker pull container-registry.my-company.org/my-project/sample-comp
docker tag container-registry.my-company.org/my-project/sample-comp sample-comp
docker images
REPOSITORY                                                 TAG       IMAGE ID       CREATED       SIZE
container-registry.my-company.org/my-project/sample-comp   latest    d803047610d8   2 hours ago   3.32GB
sample-comp                                                latest    d803047610d8   2 hours ago   3.32GB

Then, the container location can be specified as either container-registry.my-company.org/my-project/sample-comp or sample-comp.
The tag is optional, and if omitted, defaults to latest.

Kubernetes

The registry portion is container-registry.my-company.org.
The repository portion is my-project/sample-comp:latest.
The repository portion goes into the SPD file.
The tag is optional, and if omitted, defaults to latest.

Configuration

$OSSIEHOME/cluster.cfg contains configuration in INI syntax.

Docker

cluster.cfg initially contains:

[Docker]
local_dir=""
mount_dir=""

Add values to these to enable a mount point between the container (mount_dir) and the host (local_dir).

Kubernetes

cluster.cfg initially contains:

[EksKube]
registry = 
tag = latest
dockerconfigjson = ""

An url value is required for the registry key for the sandbox to find the Docker image. For our example, the url should be:

[EksKube]
registry = container-registry.my-company.org

NOTE: The value of registry must be unquoted and must not end with a slash /.

Run Example

The keyword argument orchestrationType has been added to the method sb.launch(). It can be omitted, to run without containers. Or it can take one of the two values: 'Docker', 'EksKube'.

python3
>>> from ossie.utils import sb
>>> c = sb.launch('sample_comp', orchestrationType='Docker')
['docker', 'run', '--rm', '-d', '--network', 'host', '--name', 'sample_comp_1', 'my-project/sample_comp',
'$SDRROOT/dom/components/sample_comp/python/sample_comp.py COMPONENT_IDENTIFIER DCE:46b808af-ce9d-4763-a9
0c-62f4347d440b NAMING_CONTEXT_IOR IOR:010000002000000049444c3a43462f4170706c69636174696f6e52656769737472
61723a312e3000010000000000000064000000010102000e00000031302e3131342e32302e3138330067a70e000000feec3e8d610
000269b000000000000000200000000000000080000000100000000545441010000001c0000000100000001000100010000000100
0105090101000100000009010100 PROFILE_NAME /var/redhawk/sdr/dom/components/sample_comp/sample_comp.spd.xml
 NAME_BINDING sample_comp_1']
9c56bd3478d0de3378978583a8131fcb534dab5fe9937d4f4a054d71f9474a6b
setTerminateCallback sample_comp_1
>>> c.started
False
>>> c.start()
>>> c.started
True
>>> quit()

The value returned by the launch method is the component's container id, generated by docker. To verify that the container id is correct and the component is running as a container, list the running containers:

> docker container ps -a
CONTAINER ID   IMAGE         COMMAND                  CREATED         STATUS       PORTS      NAMES
9c56bd3478d0   sample_comp   "/bin/bash -lc '$SDR..."   2 minutes ago   Up 2 minutes            sample_comp_1

To release the component, exit the Sandbox's Python session. Verify that the container has been removed by listing the running containers.