Introduction

This document details the experiences of new users of the Adaptive Policy EXecution Engine in the 5GENESIS H2020 project. This document breaks it into three sections. The first section covers integration and deployment, users describe their experiences integration APEX into their platforms. Section 2 covers policy configuration and authoring, primarily focused on experiences following documentation and implementation. Finally section 3 provides a bullet point summary of the main takeaways from the experience.

Integration and Deployment

APEX was deployed in a docker container using a base image available through the ONAP Nexus Repository Manager. APEX was packaged as a collection of policy, configuration and logic files accompanied by a DockerFile. The Dockerfile retrieves the base image, copies important files into the container and triggers a build of the APEX policy. Several ports are also exposed, these ports correspond with the carrier technologies listed in the config file. These carrier technologies include a REST Server and a Kafka Producer/Consumer for the input and output of event messages. On execution of the container, the APEX engine is initialized with the parameters defined in the config file and the generated policy.

A common integration issues faced by users involve a mismatch between the APEX configuration file and Docker. Declared ports in the APEX configuration file must be reflected as exposed ports in the Dockerfile. Highlighting this in the documentation may relieve a common issue experienced by new users. Another issue faced by users centers around the Docker and the accessibility of the APEX Engine when running in a container. Carrier Technologies such as the REST Server needs to set the host parameter to “0.0.0.0” for it to be accessible without investigating container network information.

When aware of these two potential issues, new users have expressed a straightforward experience integrating APEX into their platforms, referring to it as “plug and play”.

The APEX Engine

Configuration

The configuration file details the execution parameters of the APEX engine along with the input and output interfaces. These interfaces, referred to as Carrier Technologies, are detailed thoroughly in the APEX documentation. Users expressed that the inclusion of examples with tagged explanations of each field in the input and output parameters was very informative and contributed to the users understanding.

Having several different REST Carrier Technologies caused confusion regarding the roles of REST Client vs REST Server vs REST Requester. Users felt that this could have been explained in more detail. Providing detailed scenarios to show the differences between these REST Carrier Technologies would help new users understand which approach is best suited in certain situations.

Policy Construction

New users commented that their first experiences with policy authoring was to follow the HowTo: My First Policy. This example policy was detailed and provided a good understanding of the policy intention and concepts such as events, context and tasks. However, the graphics that accompanied the explanation showed examples in the APEX Policy Editor. Some users were able to find a full-client on older docker versions of APEX so that could follow along step by step with the documentation. Other users who did not find a working full-client had to match the APEX Policy Editor representation with the APEX CLI Editor code provided at the end of Step 1 and Step 2 in the documentation. Users would prefer if the graphical aids referenced the APEX CLI Editor code that is provided in the documentation as all of the learning material would be found in one location. This would also help users get more comfortable with creating policies as by the end of the project all users used the CLI Editor to create their policies.

Storing and working with Policy Context was described as straightforward and useful. Policy Context was primarily used to record the contents and rate of trigger events. Many users checked Policy Context during their policy execution and adapted decision making based on the historical information of the system. Users also used Policy Context to store templates of configurations which could be populated with values which adapted based on the current state of the system. Users liked the Policy Context concept and recognised its ability to change the resulting decision through Task Selection Logic.

Task Selection Logic is detailed in the APEX Policy Guide and users found that the information was clear and understandable. However, users struggled to incorporate Task Selection Logic in their policies. Users were unable to find descriptions of how to write Task Selection Logic into their CLI Editor policy files. As a result, it was difficult to implement. A common workaround involved copying parts of other policy examples and altering variable names to fit the policy. Users acknowledged that Task Selection Logic is covered as part of the HowTo: My First Policy, but without graphical aids referencing CLI editor code some users struggled.

Summary

This section bullet points the experiences of the new users described in this document

  • Mismatched ports between APEX configuration and Docker lead to unreachable Policy Engine
  • Host parameter requires “0.0.0.0” for it to be accessible without investigating container network information
  • Users expressed a straightforward experience integrating APEX into their platforms, referring to it as “plug and play”.
  • Several REST Carrier Technologies caused confusion, more information on what situations these carrier technologies are suited for would be welcomed.
  • Graphical aids in the HowTo: My First Policy could show the CLI Editor code examples instead of GUI Editor as the CLI code is already provided on the same page.
  • All users created their policies using the CLI Editor and after a short learning period were proficient in creating and linking the APEX Policy concepts.
  • Users liked the Policy Context concept and recognised its ability to change the resulting decision through Task Selection Logic
  • Users were unable to find descriptions of how to write Task Selection Logic into their CLI Editor policy files
  • While some users struggled with implementing Task Selection Logic many were able to piece it together from examples of other policies, the simplicity of writing policies through the CLI editor is mentioned often.
  • No labels