Add library to interact with kubernetes (#123)

* add k8s library

* add dep

* add patch-network-policy

* debug

* debug

* debug

* format

* update documentation

* update kubernetes_delete action to also support deletion of
networkpolicies

* format

* fix

* remove debug prints

* test fix

* code cleanup

* update requirements

* docs update

* update README

* remove debug output

---------

Co-authored-by: Florian Mirus <florian.mirus@intel.com>

.devcontainer/Dockerfile

@@ -39,6 +39,7 @@ RUN chmod +x /ros_entrypoint.sh
 RUN --mount=type=bind,target=/tmp_setup export DEBIAN_FRONTEND=noninteractive && \
     apt-get update && \
     xargs -a /tmp_setup/deb_requirements.txt apt-get install -y --no-install-recommends && \
+    xargs -a /tmp_setup/libs/scenario_execution_kubernetes/deb_requirements.txt apt-get install -y --no-install-recommends && \
     rosdep update --rosdistro="${ROS_DISTRO}" && \
     for d in /tmp_setup/*; do \
         [[ ! -d  "$d" ]] && continue; \

docs/dictionary.txt

@@ -30,4 +30,6 @@ junit
 runtime
 dot
 png
-svg
+svg
+Kubernetes
+yaml

docs/libraries.rst

@@ -10,18 +10,20 @@ Beside ``osc.standard`` provided by OpenSCENARIO 2 (which we divide into ``osc.s
 
    * - Name
      - Description
+   * - ``osc.gazebo``
+     - Gazebo Library (provided with :repo_link:`libs/scenario_execution_gazebo`)
    * - ``osc.helpers``
      - Helpers Library (provided with :repo_link:`scenario_execution`)
-   * - ``osc.robotics``
-     - Robotics Library (provided with :repo_link:`scenario_execution`)
-   * - ``osc.ros``
-     - ROS Library (provided with :repo_link:`scenario_execution_ros`)
+   * - ``osc.kubernetes``
+     - Kubernetes Library (provided with :repo_link:`libs/scenario_execution_kubernetes`)
    * - ``osc.nav2``
      - ROS Nav2 navigation stack Library (provided with :repo_link:`libs/scenario_execution_nav2`)
    * - ``osc.os``
      - Library to interact with the operating system (provided with :repo_link:`libs/scenario_execution_os`)
-   * - ``osc.gazebo``
-     - Gazebo Library (provided with :repo_link:`libs/scenario_execution_gazebo`)
+   * - ``osc.robotics``
+     - Robotics Library (provided with :repo_link:`scenario_execution`)
+   * - ``osc.ros``
+     - ROS Library (provided with :repo_link:`scenario_execution_ros`)
 
 Additional features can be implemented by defining your own library.
 
@@ -309,18 +311,46 @@ Modifier to set a timeout for a sub-tree.
      - Maximum number of permitted failures
 
 
-OS
---
+Kubernetes
+----------
 
-The library contains actions to interact with the operating system. Import it with ``import osc.os``. It is provided by the package :repo_link:`libs/scenario_execution_os`.
+The library contains actions to interact with the `Kubernetes API <https://kubernetes.io>`_. Import it with ``import osc.kubernetes``. It's provided by the package :repo_link:`libs/scenario_execution_kubernetes`.
 
 Actions
 ^^^^^^^
 
-``check_file_exists()``
+``kubernetes_create_from_yaml()``
+"""""""""""""""""""""""""""""""""
+
+Create a Kubernetes object (e.g., a pod or network policy) from a yaml file. 
+
+.. list-table:: 
+   :widths: 15 15 5 65
+   :header-rows: 1
+   :class: tight-table   
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``namespace``
+     - ``string``
+     - ``default``
+     - Kubernetes namespace
+   * - ``within_cluster``
+     - ``bool``
+     - ``false``
+     - set to true if you want to access the cluster from within a running container/pod
+   * - ``yaml_file``
+     - ``string``
+     - 
+     - The yaml-file to use create the object from
+
+
+``kubernetes_delete()``
 """""""""""""""""""""""
 
-Report success if a file exists.
+Delete a Kubernetes element (e.g., a pod or network policy).
 
 .. list-table:: 
    :widths: 15 15 5 65
@@ -331,23 +361,134 @@ Report success if a file exists.
      - Type
      - Default
      - Description
-   * - ``file_name``
+   * - ``namespace``
      - ``string``
-     -
-     - File to check
+     - ``default``
+     - Kubernetes namespace
+   * - ``within_cluster``
+     - ``bool``
+     - ``false``
+     - set to true if you want to access the cluster from within a running container/pod
+   * - ``target``
+     - ``string``
+     - 
+     - The target element to delete
+   * - ``regex``
+     - ``bool``
+     - ``false``
+     - Is the specified target a regular expression
+   * - ``element_type``
+     - ``kubernetes_element_type``
+     - 
+     - Type of the element to delete (e.g., ``kubernetes_element_type!pod``)
+   * - ``grace_period``
+     - ``time``
+     - ``5s``
+     - Grace period to wait before forcing deletion
 
 
-Robotics
---------
+``kubernetes_patch_network_policy()``
+"""""""""""""""""""""""""""""""""""""
 
-The library contains elements reusable in different robotic contexts. Import it with ``import osc.robotics``. It is provided by the package :repo_link:`scenario_execution`.
+Patch an existing Kubernetes network policy.
 
-Actors
-^^^^^^
+.. list-table:: 
+   :widths: 15 15 5 65
+   :header-rows: 1
+   :class: tight-table   
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``namespace``
+     - ``string``
+     - ``default``
+     - Kubernetes namespace
+   * - ``within_cluster``
+     - ``bool``
+     - ``false``
+     - set to true if you want to access the cluster from within a running container/pod
+   * - ``target``
+     - ``string``
+     - 
+     - The target network policy to patch
+   * - ``network_enabled``
+     - ``bool``
+     - 
+     - Should the network be enabled
+   * - ``match_label``
+     - ``key_value``
+     - 
+     - key-value pair to match (e.g., ``key_value("app", "pod_name"))``
 
-``robot``
-"""""""""
-A general robot actor.
+
+``kubernetes_wait_for_network_policy_status()``
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+Wait for an existing Kubernetes network policy to reach a specified state.
+
+.. list-table:: 
+   :widths: 15 15 5 65
+   :header-rows: 1
+   :class: tight-table   
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``namespace``
+     - ``string``
+     - ``default``
+     - Kubernetes namespace
+   * - ``within_cluster``
+     - ``bool``
+     - ``false``
+     - set to true if you want to access the cluster from within a running container/pod
+   * - ``target``
+     - ``string``
+     - 
+     - The target network policy to monitor
+   * - ``status``
+     - ``kubernetes_network_policy_status``
+     - 
+     - Expected status of the network policy, e.g., ``kubernetes_network_policy_status!added``
+
+
+``kubernetes_wait_for_pod_status()``
+""""""""""""""""""""""""""""""""""""
+
+Wait for a Kubernetes pod to reach a specified state.
+
+.. list-table:: 
+   :widths: 15 15 5 65
+   :header-rows: 1
+   :class: tight-table   
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``namespace``
+     - ``string``
+     - ``default``
+     - Kubernetes namespace
+   * - ``within_cluster``
+     - ``bool``
+     - ``false``
+     - set to true if you want to access the cluster from within a running container/pod
+   * - ``target``
+     - ``string``
+     - 
+     - The name of the pod to monitor
+   * - ``status``
+     - ``kubernetes_pod_status``
+     - 
+     - Expected status of the pod, e.g., ``kubernetes_pod_status!running``
+   * - ``regex``
+     - ``bool``
+     - ``false``
+     - Is the specified target a regular expression
 
 
 Nav2
@@ -451,6 +592,47 @@ Use nav2 to navigate to goal pose.
      - If yes, the action returns after the goal is reached or on failure. If no, the action returns after request.
 
 
+OS
+--
+
+The library contains actions to interact with the operating system. Import it with ``import osc.os``. It is provided by the package :repo_link:`libs/scenario_execution_os`.
+
+Actions
+^^^^^^^
+
+``check_file_exists()``
+"""""""""""""""""""""""
+
+Report success if a file exists.
+
+.. list-table:: 
+   :widths: 15 15 5 65
+   :header-rows: 1
+   :class: tight-table   
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``file_name``
+     - ``string``
+     -
+     - File to check
+
+
+Robotics
+--------
+
+The library contains elements reusable in different robotic contexts. Import it with ``import osc.robotics``. It is provided by the package :repo_link:`scenario_execution`.
+
+Actors
+^^^^^^
+
+``robot``
+"""""""""
+A general robot actor.
+
+
 ROS
 ---
 

libs/scenario_execution_kubernetes/MANIFEST.in

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

libs/scenario_execution_kubernetes/README.md

@@ -0,0 +1,7 @@
+# Scenario Execution Kubernetes
+
+This packages contains custom actions to interact with [Kubernetes](https://kubernetes.io/) cluster.
+
+It provides the following scenario execution libraries:
+
+- `kubernetes.osc`: Kubernetes specific actions such as creating or deleting pods.

libs/scenario_execution_kubernetes/deb_requirements.txt

@@ -0,0 +1 @@
+python3-kubernetes

libs/scenario_execution_kubernetes/package.xml

@@ -0,0 +1,21 @@
+<?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_kubernetes</name>
+  <version>1.1.0</version>
+  <description>Package for scenario execution kubernetes library</description>
+  <author email="scenario-execution@intel.com">Intel Labs</author>
+  <maintainer email="scenario-execution@intel.com">Intel Labs</maintainer>
+  <license file="../../LICENSE">Apache-2.0</license>
+
+  <exec_depend>scenario_execution</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_kubernetes/scenario_execution_kubernetes/__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_kubernetes/scenario_execution_kubernetes/get_osc_library.py

@@ -0,0 +1,19 @@
+# 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
+
+
+def get_kubernetes_library():
+    return 'scenario_execution_kubernetes', 'kubernetes.osc'