% This is the file installer_text.txt as a part of the RenewKube tool. This file contains information about the steps of a person to start RenewKube for a test. Please read the whole file before starting with the installation / tests. This is a special version for people who are interested in RenewKube but not working within our development ecosystem here in Hamburg. We tried to take most of our complicated installation process away from you. However, some preconditions have to be met by you. You need to have some resources and some knowledge about network configuration, as explained in the following paragraphs. == Preliminaries == RenewKube is a Tool involving multiple machines (at least three). You can set up each part individually, which is complex and very time consuming. To ease the installation we have compiled a ready to use Ubuntu 18.04 VirtualBox appliance, that comes pre-configured with everything you need / need to download the right tools. We highly recommend using it. Please download VirtulBox 6.x from: https://www.virtualbox.org/wiki/Downloads (5.2.xx should also work, but we did not test all features with it). The supplied image is an all-in-one image for all roles of RenewKube, depending on the script, that is run to set it up. One image should always play only one of the three roles! Since the base setup of RenewKube involves at least 3 machines, please import the .ova file (at least) _three times_ into VirtualBox (or clone it appropriately (see below)). You can use VirtualBoxes on different physical machines, if you like, as long as they share a local network. If you want to run everything on a single machine you will need about 15-40 GB of free disk space! (If you clone your imported renewkube appliance you can either use a real copy (costing 10GB (each(!) image)) or a dependent copy (costing 10MB - 1 GB). Furthermore you will need a CPU with at least 4 cores / 8 threads to have a reasonable speed for execution. For a simple proof of concept test e.g. a MacBookPro with 16GB is OK. Also ensure, that the VM, that is going to be the master (one of the 3 roles) can connect to the internet, as it needs to download additional libraries during the automated set up. Please make sure to tick the "Generate new MAC Adress" checkbox upon import in VirtualBox. Suggested names for the three imports are: "master_RenewKube", "worker1_RenewKube" and "workstation_RenewKube", but you may name them to your liking. Important: Whenever the VM prompts you for username and or password (sudo etc.) it is always "renewkube" (without quotes and for both username and password) If unsure, you may always run "get_ip.sh" inside a VM to get the IP address of the default interface (enp0s3). The image was designed with a local LAN with a DHCP-enabled router in mind (that assigns IPs to the VMs automatically). If you have access to this kind of infrastructural scenario no more preliminary setup is necessary. You will usually find this kind of network setup in a private environment. Note, that corporate or university networks are more complex and usually do not assign IPs to newly connected machines (VMs) automatically. In that case make sure that e.g. the VMs get enabled by their MAC addresses to get access to the network. == Advanced Network Setup (no-DHCP) == If you don't have a DHCP server running on the local LAN, you will have to set up the network manually. If you are unsure about the set-up of your local network, contact your network administrator to help you. Inside of each VM, after you booted them, click the network icon on the top left of the desktop (next to the "shut down" icon and the "speaker" icon) and click "Wired Connection" -> "Wired settings". Switch the slider to "OFF" at "wired connection" and click the cog wheel icon right next to it. If there is no wired connection, click the "+" icon to add a new one. Make sure to select the interface "enp0s3" and add an IPv4, default gateway and default routes to connect the VM to your physical LAN. Open firefox to ensure a working internet connection. Instead of a bridge network you should use a NAT-Network. You can create a NAT-Network on your Virtualbox environment using the Host-only Network Manager. With its help you can setup a DHCP server for your VMs and provide the necessary settings. Use the command ping <192.168.0.100> == Installation == The three following installations should be done sequentially: 1. Master 2. Worker 3. Workstation n. (optional Workers) == Master == Boot up the "master_RenewKube" machine. Set up the network - if necessary - like above. If you like, you may switch your keyboard layout between English and German with the top left drop down field (initially saying "en"). Open up a terminal (in the left sidebar) and launch the installer by typing: install_master.sh Several files will be downloaded for installation. Depending on your network connection and your processor this might take several minutes. Please follow the on screen instructions. == Worker == Upon completion boot the first "worker1_RenewKube" VM. Set up the network - if necessary - like above. Open a terminal and install the worker using the IP of the master: install_worker.sh so for example if your master is set up to be 192.168.0.100, call: install_worker.sh 192.168.0.100 If you wish to add additional worker VMs start and install them now. Note, that this is only beneficial if you use more than one physical machine. If you run everything on the same physical machine, we recommend to stick with one worker. However, to just test the possibility you can start two or more workers. NOW YOU HAVE TO EXECUTE install_worker.sh AGAIN. After the execution of install_worker.sh you can check on the master if the worker is registered by executing kubectl get nodes == Workstation == Finally boot the "workstation_RenewKube" VM. Set up the network - if necessary - like above. Start the RenewKube GUI with your master IP by typing: start_renew_kube.sh again, with the example: start_renew_kube.sh 192.168.0.100 A simple test of the working network is to ping the other nodes via their ip address. ping 192.168.0.100 will continuously show if the node (in this case the master) is available via this address within one second. You will be presented with the Renew interface with 2 pre-opened Nets: the nets "distributor" and "remoteStart". == Simulation == Make sure to have the "distributor" window focused and hit (in the tool window): Simulation -> Run Simulation. The simulation may take a few seconds to initialize. If everything is set up correctly, the :getWork() transition will fire occasionally. Then the work will initiate a sleep-operation in the "distributor" net (see :getWork() <- r.nextInt(20000) for the random time transferred to the "remoteStart" net. The transition with "action Thread.sleep(work);" determines the sleeping time before the "distributor" net receives the information that the work was done. You may right click the "1" (that is a token amount) at the place labelled "scale" at the bottom to view the value of the token. Right click the transition next to it labelled "scale++" to increase the number of remote Renew instances running in the cluster by one. It takes some time for the remote simulators to boot. Depending on the number of processors this will speed up the whole simulation. == some hints == If you happen to run into not responding simulations (e.g.) the "registered" place is not being filled after launch, it might be a good idea to restart the RMI registry on the master node. To do so simply call the command "restart_registry.sh" on the master. It is a known issue, that the simulation does not clean up remote instances upon termination. It is scheduled to add this feature in an upcoming version of RenewKube, but for now please resort to the "restart_registry.sh" command, as it will purge the remote instances as well. In any way, you will have to restart the GUI after restarting the registry by closing the GUI and launching it via "start_renew_kube.sh " again. If you want to have several workers, you need to generate completely separated VMs. => Do not clone a worker after install_worker.sh has been run. == own examples == If you want to model your own examples and play around with the RenewKube, keep in mind, that you will need at least one net, that is exactly named "remoteStart", which is the one every remote instance will initially start with. The remote Renew instances will know every net you have opened in the workstation Renew when starting the simulation. On information on how to use the distribute plugin, please refer to the respective publications. Also, after getting the rk object (left part of the distributor net), you may also call the methods rk.getScale() to query the cluster for real time instance count or rk.getScaleTarget() to get the number of targeted instances (these may differ while machines are still booting).