As written in Introduction to automaIT execution logic is defined and imported in single components and plans or packed in a plug-in. This tutorial is about importing a predefined plug-in and installing a Java Development Kit and a Glassfish application server to run a simple HelloWorld application.
For Linux hosts only!
While automaIT itself is platform independent, the plug-in in this tutorial has been written on and for Linux respectively Unix like systems only. It won't work on a Windows agent.
If not done yet, install the automaIT agent on a Linux test host which is reachable by the automaIT server (default agent port is 9999, communicating via HTTPS). For installation instructions see Agent Installation. For a quick test the agent can be also started in the shell session using the
agent.sh script in the agent package. Doing so a Java Runtime 7 must be available in the PATH.
The plug-in only contains the executable installation routines and not the used installers / binaries. Using the default configuration these are expected as
/software/jdk-7*-linux-x64.tar.gzwhich can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html
/software/glassfish-4.0-web.zipwhich can be downloaded from https://glassfish.java.net/download-archive.html
Start your browser and open the web interface of your automaIT server which has an URL like
in the described default installation.
Login with your credentials (in a fresh installation this is user admin with password admin).
Navigate to Hosts and click on Create Physical in the top right corner.
Define a unique name for this host used within automaIT. Normally this would be the DNS name of the remote host where the automaIT agent is installed.
If you want you may also write a description of this host for example that this is only a test host or that it is located on the virtual cluster in Berlin.
Type the ip address or, if resolvable on the automaIT server, the DNS name of the remote host.
If you did a default agent installation or just started it with the
agent.sh script the default port 9999 is correct. Otherwise change it to the port you defined in the agent's configuration.
Submit your changes using the Save and Initialize button in the top right.
You will see the details of the host initialization job.
The host initialization is a first connect to the remote agent which discovers basic information like the operating system, its architecture and the delimiters for paths and the PATH variable.
Normally this should complete successfully in a few seconds. Otherwise you will see an error message and have to ensure connectivity between the automaIT server and the referenced agent.
This is the installation dialog where configuration parameters for the Java Development Kit can be modified:
At the top you may choose a Constructor which is the installation routine. Here and in most cases there is only one defined and named default.
Next section are optional execution parameters. The markOnly parameter would cause the component to be only "installed" (or better say instantiated or registered) within automaIT. There would be no physical actions but a short connect to the agent which is very useful in case of bugs in the component's routines.
More important than the execution parameters are the component variables. Unlike the parameters the variable values will be persisted = saved in automaIT after installation. This allows a later search for used configuration values and is like a small CMDB. Additionally these values can be referenced and reused automatically by other components in later installations or executions. Modified configurations (= modified component variables) are saved in so called Variable Sets to use them later for further installations of the same component.
Actually the Default variable set is selected. To modify the configuration for the JDK click on Create Variable Set.
Deselect the Use Default checkbox for the installPath variable and change the installation path from /opt/demo/jdk to a path of your choice. In our example we choose /opt/demo/java instead.
Name the Variable Set and click on Save.
Back in the installation dialog the new variable set opt.demo.java is selected for installation now so we will use a different configuration for this JDK.
In the last section select one or more hosts to install the JDK on. Here we will use the localhost which is our tutorial agent. Select the host with double click or drag'n'drop.
Click Simulate and Install to start the installation routine.
Again you see the job details. automaIT will first simulate the installation and show this under the Simulation tab. The simulation checks the installation routine for logical errors and unresolved references or dependencies and won't take longer than a very few seconds.
After the simulation completed successfully the tab will switch to Execution and you see nearly the same steps which are executed on the remote host now.
The installation shoul be completed within some seconds which is represented by all steps coloured green.
Looking at the job protocol you will see that the installation created our defined installation path /opt/demo/java and extracted the given JDK archive.
Navigate to Plans and Components, click on theGlassfish and in the following dialog on Install.
You already now the installation dialog but let's modify the configuration again so click on Create Variable Set which will create a modified configuration for the Glassfish component.
Again uncheck the Use Default checkbox for the webPort variable and give a modified value like 4040.
Also give a unique name for this variable set and click on Save.
As expected the new variable set Port4040 is selected for the installation now but something else in this dialogue is different to the JDK installation:
Our defined physical host localhost has gone and a host localhost-jdk7 is displayed instead in Available Hosts. This Virtual Host is also listed in the host list under Hosts and is an automaIT concept to ensure and represent dependencies. The virtual host has been created automatically by the JDK installation routine and has a specified Host Type. Using a logical chain of this host type, a Host Search searching all hosts of this type, a Host Set including that search and the Glassfish component which is limited to that host set it is guaranteed that there is always an installed JDK before we are able to install a Glassfish on this host.
Select the localhost-jkd7 and click on Simulate and Install.
In the following job details you can watch the installation of Glassfish which includes the creation of the installation directory, extracting the package, configuring our defined web port 4040 as well as the Java-Home of our previously installed JDK and starting the Glassfish instance. All in less than half a minute.
Have a special look at the 11th line where the Java-Home is defined and will link to your modified installation path of the JDK. This value has been discovered from the installed JDK component using the Substitution (= variable reference)
Check the installation success by opening the Glassfish instance in your browser which should be reachable on an URL like http://localhost:4040/.
Last but not least you may install the HelloWorldApp.
If you want you can change the configuration to deploy the application into another app context than demo.
Otherwise you should reach the application on http://localhost:4040/demo after installation.
Execute Control Methods
Congratulations! We just installed a full software stack with an individual configuration. Different to most configuration management tools automaIT doesn't just installs and configures but can execute lifetime operations as well.
Navigate to Plans and Components and click on the second green icon in the Glassfish component line to show all Instances of this component.
You will see a table with just one line: The instance we have just installed on the localhost-jdk7 virtual host.
Click on the first icon to Execute Control Method.
You see a dialog similar to the installation dialog. Instead of constructors we have a list of available Control Methods at the top. Choose the stop method which has no defined parameters.
At the bottom you don't see available hosts but installed instances of Glassfish. Select the only one which represents our installation on localhost-jdk7 where we just checked the running Glassfish.
Click on Simulate and Execute Control Method to start the job. After it completed check the Glassfish URL http://localhost:4040/ again which should be unreachable now. The Glassfish instance has been stopped.
These control methods can't only be executed manually but also integrated into (un)installation routines and called automatically by other components.
If you had a deeper look at the job protocol of the HelloWorldApp you just have seen the installation routine of HelloWorldApp calling the deploy control method of the Glassfish component (see mouse pointer in screenshot).
If you strictly followed this guide using a Linux similar to openSuSE everything should have passed successfully so far.
To understand the possibilities of error diagnosis and troubleshooting we will try to install Glassfish again using a wrong configuration.
Navigate to Plans and Components, click on theGlassfish and in the following dialog on Install. (Alternatively a shorter way would be to click on the first green icon in the Glassfish line in Plans and Components.)
Create a new variable set changing the value for version from 4.0 to 1.0, name the set Error and click Save.
Select the localhost-jdk7 and click Simulate and Install.
The following simulation will pass successfully because there are no logical or structural errors.
By contrast the execution will fail fast and display an error like.
The last step and its parent steps are coloured red while the error message is shown again in the last step which originally has failed.
Click on the green text link in the last step to open the details dialog for this step.
This dialog gives you deeper information about the failed execution:
- The failed command was
/software/glassfish-1.0-web.zipand it exited with a return code of 9.
- There was no specified execution user so it has been executed with the user running the agent (which should be root).
- The command has been executed in the directory
- No specific environment variables have been defined and the default login shell of the execution user hasn't been used.
All very interesting but the most important information is in the Error tab showing the original error message (StdErr):
unzip: cannot find or open /software/glassfish-1.0-web.zip, /software/glassfish-1.0-web.zip.zip or /software/glassfish-1.0-web.zip.ZIP.
So our configuration for version 1.0 lead to searching the installation file glassfish-1.0-web.zip which doesn't exist.
Plans / Remove Demo
We have a full software stack installation and used all three components in the plug-in. But the demo plug-in also contains two plans.
Plans are code files which aggregate executions (mostly installations) over several components and sometimes several hosts as well. So they can be used to easily install a huge set of components respectively to install complex topologies with different components on different hosts having dependencies among themselves.
Specifically for our demo tutorial we could have used the installation plan InstallDemo instead of installing all three components separately. This plan has a defined order to first install the JDK, switch to the virtual host ...-jdk7, install the Glassfish, switch again to the new virtual host ...-jdk7-glassfish and install the HelloWorld application. Configuration could be modified by giving plan parameters (which are persisted in the job protocol but not saved as a configuration set) which will be passed to the components.
Let's try a plan by using the uninstallation plan RemoveDemo.
Navigate to Plans and Components, click on the RemoveDemo plan in the lower table and click on the Run Plan button. Alternatively click on the first green icon in the table in the line of RemoveDemo to directly open the execution dialog.
This plan only provides one plan parameter markOnly which we don't need here because we want to clean up our remote test host.
Unfortunately this demo plan hasn't been limited to a specific host set so we theoretically we could execute it on every host. Trust me that it won't work on the virtual hosts but only on the localhost itself. So select the green host (indicating that this is a physical and initialized host) and pull it into the Hosts for Execution box.
As you already might know click on Simulate and Execute Plan to start the execution job.
This plan is designed to search through the software stack hierarchie so it will first look for an installed JDK on that host. If one exists it moves to the JDK's virtual hosts and searches for an installed Glassfish and so on.
Reaching a (virtual) host where no JDK, Glassfish or Application is installed it will remove the parent component and then their parent and then their parent...
So finally the plan should have dynamically removed all component installations in this software stack. Doesn't matter if you installed the HelloWorldApp or not.