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.

Download

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

Startup 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.

• 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. The feature usages described later use curl for the example command line statements.
• 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.
• 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 (depending on your shell you might need to escape the semicolon character: 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. The ways to view these health endpoints will be introduced later on this page.

Features

Cloud Native Renew offers the following features.
It is assumed, that the system is up and running in a separate terminal.
To do so on your own, download Cloud Native Renew and follow the startup instructions.

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 startup 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.
Also make sure to run all commands from the extracted directoy unless stated otherwise.

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/log

Or alternatively use curl to request the logs:
curl localhost:8085/log

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 the cloud native 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. You can use the method described above to upload a shadow net system and start a simulation with it remotely, if not done already. Alternatively, the most simple way to set up a simulation, 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.
As noted earlier, this former method will not show graphical feedback, while latter will.

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 metrics and 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.

To obtain more thorough information about the state of the simulator you can also execute:
curl http://localhost:8085/actuator/health

A more complex JSON containing several pieces of information about the simulator and its environment will be returned.
However, a more convenient way to consume the information is to use an external UI, see section Connecting an external admin interface for more details.

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.

Connecting an external admin interface

The metric endpoints can be consumed by an external interface tool, such as ​Spring Boot Admin by codecentric.
To set this up, you can download our sample setup of Spring Boot Admin here.

Extract the archive and open a command shell in the extracted folder. Run:
chmod +x gradlew (Only on UNIX based systems)
./gradlew bootRun (or .\gradlew bootRun on Windows CMD)
Hint: Upon startup the Gradle task will show "80%" completion (as it assumes the run to be complete once the application exits again).

Then, close Cloud Native Renew, if it is currently running and navigate to the Cloud Native Renew directory.
Open the file application.properties and uncomment (remove the #) the line spring.boot.admin.client.url=http://localhost:8099.
Then start Cloud Native Renew as described in the startup instructions section while Spring Boot Admin is running in a different terminal.

Now open a browser and navigate to localhost:8099 and explore the application in your browser.