= 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. [[Image(global_architecture.png)]] == Download == #download The latest version of the cloud native Renew plugin (shown in bold font in the figure) can be downloaded [https://fbicloud.informatik.uni-hamburg.de/index.php/s/jdGCsKrZRz9rSz5/download here]. == Startup instructions == #start ** A video tutorial on how to set up Cloud Native Renew can be found [https://fbicloud.informatik.uni-hamburg.de/index.php/s/EHbnp5RCwTkqcZF/download here]** 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 [#download 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 download] Cloud Native Renew and follow the [#start 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 [#start 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 === #upload 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 [#upload 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 [#admin 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_withPlugin&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 (using the same command as above):\\ `curl -X POST "localhost:8085/simulation/start?mainNet=primeDistributor_withPlugin&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 === #admin The metric endpoints can be consumed by an external interface tool, such as [https://github.com/codecentric/spring-boot-admin Spring Boot Admin by codecentric].\\ To set this up, you can download our sample setup of Spring Boot Admin [https://paose.informatik.uni-hamburg.de/paose/raw-attachment/wiki/CloudNativeRenew/CloudNativeRenew_SpringBootAdmin.zip 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).\\ Wait for the application to print `Started RenewSpringBootAdmin in x.xxx seconds`. 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` and save the file.\\ Then, start Cloud Native Renew as described in the [#start 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.