Cloud Native Renew

Cloud Native Renew aims towards incorporating aspects of observability, operability, agility, and resilience into reference net simulations based on Renew.
Its intended use is the deployment in cloud environments without direct administrative access to the system itself.
Our current implementation is based on Renew 4.0 (see ​http://www.renew.de)

Cloud Native Renew offers the following features:

• Upload of net systems
• Start and control of simulations remotely via HTTP
• Extending the functionality of a running simulator on-the-fly
• Provision of health and other metrics

The approach is in line with other related contributions, such as RenewKube and PetriNetSagas.

The following figure shows the overall architecture of a full cloud native Renew deployment.

Features

Cloud Native Renew offers the following features.
It is assumed, that the system is up and running.
To do so on your own, download Cloud Native Renew and follow the installation instructions further down the page.

For all examples it is assumed, that the service is running on localhost on port 8085. If you set it up otherwise than suggested in the installation instructions, please use the corresponding URL you've set up instead.
It is also assumed, that you have a web browser and the command line tool curl installed.

For a quick overview over the available (non-health related) endpoints navigate to http://localhost:8085/swagger-ui.html.

Examine Logs from the simulator via Web

To access all system log data from when the cloud native plugin was loaded onwards, open up the URL:
http://localhost:8085/logs

Upload nets and start a simulation

It is possible to use the Cloud Native Renew Plugin to upload net definitions to an HTTP endpoint. Renew uses so called shadow net systems to simulate reference nets. A shadow net system contains just the bare minimum to run a (non-visual) headless simulation. To create a shadow net from a regular Renew .rnw net definition file, you can use Renew user interface. To just try functionality you can also just use the supplied example primes.sns file. The example net will compute prime numbers in basic fashion and is not meant to be competetive with other prime number generators but to show an example concurrent workload.
To upload a shadow net system and start a simulation follow these steps:

• Create a shadow net system by doing either of these steps:
  • You either can use the supplied primes.sns file or
  • You can also create a shadow net system yourself: Open up a Renew instance (or use the one spawned by the startup earlier), draw a reference net (or multiple), save all of your nets with a specific name each (File -> Save Drawing As...), and hit File -> Export -> Export all drawings (merged file) -> ShadowNetSystem Close the net drawing(s), but not Renew itself.
• Assume the shadow net system file is namend primes.sns: Upload the net using:
  curl -F "snsZipFile=@primes.sns" localhost:8085/upload/sns?fileName=primes
• After uploading you can start a simulation. Assume you named the main net within primes.sns: primeDistributor.
  • Use this command: curl -X POST "localhost:8085/simulation/start?mainNet=primeDistributor&sns=primes.sns"
    Note, that shadow net systems do not hold graphical information, therefore you will not be able to see the simulation within the spawned Renew instance, but you should be able to observe the console output generated by the running simulation. Within the intended deployment, that was shown in the figure above, Renew instances are headless anyways and do not have any graphical output.

Control a running simulation

It is possible to control a running simulation over HTTP. To do you, you need to set up a simulation first. The most simple way to do so is to draw (or load) nets, like the supplied primeDistributor.rnw and primeCompute.rnw file and start a simulation from within the Renew GUI: Simulation -> Start Simulation while having selected PrimeDistributor.
You can alternatively use the method described above to upload a shadow net system and start a simulation with it remotely. As noted earlier, this method will not show graphical feedback, while starting through Renew directly does.

• The simulation can now be controlled by using the following command:
  

curl -X POST 'localhost:8085/simulation/control?command=step'
You can use these keywords instead of step:

• run (To run simulations, that have been paused or only initialized)
• step (To execute a single step in the simulation)
• stop or halt (To suspend the simulation but do not terminate it)
• term (To terminate a simulation irreversibly. Subsequent control commands will have no effects until a new simulation is started.)

Check for available Plugins

To check what plugins are available in a running simulator perform this GET request:
curl http://localhost:8085/actuator/health/pluginHealth

A JSON containing all currently loaded plugins will be returned.

Extending the simulator on-the-fly

Running a primality test within a reference net structure is not optimal, as reference nets are optimized to model complex, hierarchical structures and not simple computations. Therefore it may be desirable to move the computation to a separate plugin, that can be loaded. Cloud Native Renew supports functionality to extend the simulator code with plugins remotely during runtime.

First attempt to start the net system primeDistributor_withPlugin.sns by executing:
curl -F "snsZipFile=@primeDistributor_withPlugin.sns" localhost:8085/upload/sns?fileName=primeDistributor_withPlugin
curl -X POST "localhost:8085/simulation/start?mainNet=primeDistributor&sns=primeDistributor_withPlugin.sns"

Observe, that the simulation fails to start, because it is missing the class PrimeCompute:
No such class: PrimeCompute
Status: Cleaning up.

To upload the plugin containing the missing functionality execute the following:
curl -F "pluginJarFile=@de.renew.primecompute-0.1.jar" localhost:8085/upload/plugin?pluginName=primeCompute

After that the plugin can be loaded via:
curl -X POST localhost:8085/loadPlugin?pluginName=primeCompute.jar

To check, that the plugin indeed was loaded, you can execute:
curl http://localhost:8085/actuator/health/pluginHealth
The PrimeCompute? Plugin should be listed.

You can now start the simulation with the supplied plugin:
curl -X POST "localhost:8085/simulation/start?mainNet=primeDistributor&sns=primeDistributor_withPlugin.sns"

Use the log to observe the number computations printed to the console:
curl localhost:8085/log

Note, that the uploaded plugin is placed with the other plugins, therefore it will be loaded automatically upon subsequent starts of the simulator, without the need to upload it again.

Download

The latest version of the cloud native Renew plugin (shown in bold font in the figure) can be downloaded here.

Installation instructions

This section describes the usage in an isolated context, meaning a simple start of a Renew instance along with the cloud native plugin, but not the entire deployment outlined in the figure above. Information on the full deployment will be shown later.

• Make sure to you have Java 11+ and any HTTP enabled tool, such as curl installed on the machine, you want to run Renew on.
• Download the package above and unzip it.
• (optional) If port 8085 is in use on your machine, open the file application.properties and change the entry server.port to an unused port. For the remainder of this guide, it is assumed, that port 8085 is used. If it was changed in the application.properties, it also needs to be changed in the following command line invocations.
• Navigate to the main directory and run ./gradlew build (or .\gradlew build on Windows CMD)
• To start use the following command:
  • Linux/Unix: java -p .:libs -m de.renew.loader gui (depending on your shell you might need to escape the colon character: java -p .\:libs -m de.renew.loader gui
  • Windows: java -p .;libs -m de.renew.loader gui

• Open a command shell and execute curl localhost:8085/log (or use the port you specified earlier in the application.properties file). The log files of the simulator will be returned from the moment onward the cloud native plugin was initialized.
• Open a web browser and navigate to http://localhost:8085/swagger-ui.html to see an API documentation of the service endpoints with their required parameters. Note, that this overview does not cover the /health endpoints, that indicate state of the application and its parts.