scenario_execution library for docker interaction

docs/dictionary.txt

@@ -35,4 +35,6 @@ Kubernetes
 yaml
 absolutized
 moveit
-replan
+replan
+effector
+mnt

docs/libraries.rst

@@ -10,6 +10,8 @@ Beside ``osc.standard`` provided by OpenSCENARIO 2 (which we divide into ``osc.s
 
    * - Name
      - Description
+   * - ``osc.docker``
+     - Docker Library (provided with :repo_link:`libs/scenario_execution_docker`)
    * - ``osc.gazebo``
      - Gazebo Library (provided with :repo_link:`libs/scenario_execution_gazebo`)
    * - ``osc.helpers``
@@ -32,6 +34,163 @@ Beside ``osc.standard`` provided by OpenSCENARIO 2 (which we divide into ``osc.s
 Additional features can be implemented by defining your own library.
 
 
+Docker
+------
+
+The library contains actions to interact with `Docker <https://www.docker.com/>`_. Import it with ``import osc.docker``. It's provided by the package :repo_link:`libs/scenario_execution_docker`.
+
+``docker_run()``
+^^^^^^^^^^^^^^^^
+
+Runs a Docker container
+
+.. list-table:: 
+   :widths: 15 15 5 65
+   :header-rows: 1
+   :class: tight-table   
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``image``
+     - ``string``
+     -
+     - The image to run
+   * - ``command``
+     - ``string``
+     - 
+     - The command to run in the container
+   * - ``container_name``
+     - ``string``
+     - 
+     - The name for this container
+   * - ``detach``
+     - ``bool``
+     - false
+     - Whether to run container in the background
+   * - ``environment``
+     - ``list of string``
+     - 
+     - Environment variables to set inside the container, i.e., a list of strings in the format ["SOMEVARIABLE=xxx"].
+   * - ``network``
+     - ``string``
+     - 
+     - Name of the network this container will be connected to at creation time
+   * - ``privileged``
+     - ``bool``
+     - false
+     - Give extended privileges to this container
+   * - ``remove``
+     - ``bool``
+     - true
+     - Remove the container when it as finished running
+   * - ``stream``
+     - ``bool``
+     - true
+     - If true and detach is false, return a log generator instead of a string. Ignored if detach is true.
+   * - ``volumes``
+     - ``list of string``
+     - 
+     - A list of strings which each one of its elements specifies a mount volume: ['/home/user1/:/mount/vol2','/home/user2/:/mount/vol1']
+
+``docker_exec()``
+^^^^^^^^^^^^^^^^^
+
+Runs a command inside a given Docker container
+
+.. list-table:: 
+   :widths: 15 15 5 65
+   :header-rows: 1
+   :class: tight-table   
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``container``
+     - ``string``
+     - 
+     - The name or id of the container to run the command in 
+   * - ``container``
+     - ``string``
+     - 
+     - The name or id of the container to run the command in 
+   * - ``command``
+     - ``string``
+     - 
+     - The command to run inside the container
+   * - ``environment``
+     - ``list of string``
+     - 
+     - Environment variables to set inside the container, i.e., a list of strings in the format ["SOMEVARIABLE=xxx"].
+   * - ``privileged``
+     - ``bool``
+     - false
+     - Give extended privileges to this container
+   * - ``user``
+     - ``string``
+     - root
+     - User to execute command as
+   * - ``workdir``
+     - ``string``
+     - 
+     - Path to working directory for this exec session
+
+``docker_copy()``
+^^^^^^^^^^^^^^^^^
+
+Copy a file or folder from the container.
+Note that this actions potentially blocks other action calls if the copied content is large.
+In case large files or folders need to be copied, consider mounting a volume to the container instead of this action.
+
+.. list-table:: 
+   :widths: 15 15 5 65
+   :header-rows: 1
+   :class: tight-table   
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``container``
+     - ``string``
+     - 
+     - The name or id of the container to run the command in 
+   * - ``file_path``
+     - ``string``
+     - 
+     - Path to the file or folder inside the container to retrieve
+
+``docker_put()``
+^^^^^^^^^^^^^^^^^
+
+Copy a file or folder from the local system into a running container.
+Note that this actions potentially blocks other action calls if the copied content is large.
+In case large files or folders need to be copied, consider mounting a volume to the container instead of this action.
+
+.. list-table:: 
+   :widths: 15 15 5 65
+   :header-rows: 1
+   :class: tight-table   
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``container``
+     - ``string``
+     - 
+     - The name or id of the container to put the file or folder into 
+   * - ``source_path``
+     - ``string``
+     - 
+     - Path to the file or folder in the local system to copy
+   * - ``target_path``
+     - ``string``
+     - 
+     - Target path inside the container to put the file or folder
+
 Gazebo
 ------
 
@@ -1604,4 +1763,4 @@ Capture the screen content within a video.
    * - ``frame_rate``
      - ``float``
      - ``25.0``
-     - Frame-rate of the resulting video
+     - Frame-rate of the resulting video

libs/scenario_execution_docker/MANIFEST.in

@@ -0,0 +1 @@
+include scenario_execution_docker/lib_osc/*.osc

libs/scenario_execution_docker/README.md

@@ -0,0 +1,8 @@
+# Scenario Execution Library for Docker interaction
+
+The `scenario_execution_docker` package provides actions to interact with docker.
+
+It provides the following scenario execution library:
+
+- `docker.osc`: Actions to interact with docker
+

libs/scenario_execution_docker/package.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>scenario_execution_docker</name>
+  <version>1.2.0</version>
+  <description>Scenario Execution library for docker interactions</description>
+  <author email="[email protected]">Intel Labs</author>
+  <maintainer email="[email protected]">Intel Labs</maintainer>
+  <license file="../../LICENSE">Apache-2.0</license>
+
+  <depend>scenario_execution</depend>
+
+  <exec_depend>python3-docker</exec_depend>
+
+  <test_depend>ament_copyright</test_depend>
+  <test_depend>ament_flake8</test_depend>
+  <test_depend>ament_pep257</test_depend>
+  <test_depend>python3-pytest</test_depend>
+
+  <export>
+    <build_type>ament_python</build_type>
+  </export>
+</package>

libs/scenario_execution_docker/scenario_execution_docker/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (C) 2024 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions
+# and limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0

libs/scenario_execution_docker/scenario_execution_docker/actions/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (C) 2024 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions
+# and limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0

libs/scenario_execution_docker/scenario_execution_docker/actions/docker_copy.py

@@ -0,0 +1,99 @@
+# Copyright (C) 2024 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions
+# and limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from enum import Enum
+
+import os
+import docker
+import tempfile
+import tarfile
+import py_trees
+from scenario_execution.actions.base_action import BaseAction, ActionError
+
+
+class CopyStatus(Enum):
+    IDLE = 1
+    FOUND_CONTAINER = 2
+    COPYING = 3
+    DONE = 4
+
+
+class DockerCopy(BaseAction):
+    """
+    Copy a file or folder from a running container
+    """
+
+    def __init__(self, container: str, file_path: str):
+        super().__init__()
+        self.container = container
+        self.file_path = file_path
+
+        self.container_object = None
+        self.current_state = CopyStatus.IDLE
+        self.output_dir = None
+        self.client = None
+        self.result_data = None
+
+    def setup(self, **kwargs):
+        # create docker client
+        self.client = docker.from_env()
+
+        # check output_dir
+        if "output_dir" not in kwargs:
+            raise ActionError("output_dir not defined.", action=self)
+
+        if kwargs['output_dir']:
+            if not os.path.exists(kwargs['output_dir']):
+                raise ActionError(f"Specified destination dir '{kwargs['output_dir']}' does not exist", action=self)
+            self.output_dir = kwargs['output_dir']
+
+    def update(self) -> py_trees.common.Status:
+        if self.current_state == CopyStatus.IDLE:
+            try:
+                self.container_object = self.client.containers.get(self.container)
+                self.current_state = CopyStatus.FOUND_CONTAINER
+            except docker.errors.APIError as e:
+                self.feedback_message = f"Docker container {self.container} not yet running {e}"  # pylint: disable= attribute-defined-outside-init
+                return py_trees.common.Status.RUNNING
+
+        if self.current_state == CopyStatus.FOUND_CONTAINER:
+            try:
+                self.result_data, _ = self.container_object.get_archive(
+                    path=self.file_path)
+                self.current_state = CopyStatus.COPYING
+                self.feedback_message = f"Copying data from path {self.file_path} in container {self.container} to {self.output_dir}"  # pylint: disable= attribute-defined-outside-init
+            except docker.errors.APIError as e:
+                self.feedback_message = f"Copying of data from path {self.file_path} failed: {e}"  # pylint: disable= attribute-defined-outside-init
+                return py_trees.common.Status.FAILURE
+
+        if self.current_state == CopyStatus.COPYING:
+            output_tar = tempfile.NamedTemporaryFile(suffix=".tar")
+            try:
+                with open(output_tar.name, 'wb') as f:
+                    for chunk in self.result_data:
+                        f.write(chunk)
+                with tarfile.open(output_tar.name, 'r') as tar:
+                    tar.extractall(self.output_dir)
+                self.current_state = CopyStatus.DONE
+            except tarfile.ReadError as e:
+                self.feedback_message = f"Copying of data from path {self.file_path} failed: {e}"  # pylint: disable= attribute-defined-outside-init
+                return py_trees.common.Status.FAILURE
+
+        if self.current_state == CopyStatus.DONE:
+            self.feedback_message = f"Finished copying of data from path {self.file_path} to {self.output_dir}"  # pylint: disable= attribute-defined-outside-init
+            return py_trees.common.Status.SUCCESS
+
+        return py_trees.common.Status.RUNNING