The Deployment Configuration xml file is build of two main sections: one is the root element <cloud-config> and the second <machines> which is part of <cloud-config>.
The <cloud-config> contains the global elements that are common to all of the machines, The <machines> Element contains individual machine profiles.
The raw-machine elements can be used with gsm-machine , gsc-machine , load-balancer-machine and database-machine machine types.
The Cloud Application Deployment Configuration file supports the following elements:
Root Element - cloud-config
All the elements in the <cloud-config> are global, if for example you don't define an <ami-id> for a machine profile it will use the <ami-id> defined in the <cloud-config> element.
You can inherite elements from other file using <parent-config-filename> element, if not defined then the defaults are taken from cloud-config.xml which is located at /cloudtools/default-settings/cloud-config.xml.
The application repository location on S3. The deployment process using this folder on S3 to upload the required files listed at the deployment file into the started machines. if defined that will be the value of $CPD , which is used in transfer files
Specifies a default Availability Zone for machine instances. Since version 2.3.7.5, the zone is optional. If the zone is not specified machines would start in any zone (in the specified region).
Parent override cloud configuration file. This option allows you to share the same settings between different cloud configuration files
server-init-filename
Server init file, The Script that runs when the machine startup
boot-timeout-seconds
New in Cloud Tools 2.3.7.8. By default any machine that is reported as "running" is expected to start the cloudtools startup script within 180 seconds (3 minutes). A machine that takes longer to boot is terminated and a new machine is started in its place.
ec2-run-machines-request-max-retries
New in Cloud Tools 2.3.7.9. Sets the number of failed ec2-run-machine retry attempts. The sleep between retries is exponential and is defined by 2^RETRY_ATTEMPT. By default number of retries is set to 5. So before the first retry it would sleep 2 seconds, then 4, 8, 16 and 32
New In Cloud Tools 2.3.6. Elastic IP Address to use with this machine, the user can define multiple elastic-ip elements if number-of-machines is bigger than the number of elastic-ip's then the remaining machines will wait for the elastic-ip's to be released
script-source
name of the file that will be downloaded to the machine and executed after the machine will initialize
New In Cloud Tools 2.3.6. Used for declaring environment variables declared for the running machine. The variable name and value set using the following format:variable name=value. Example:
New in Cloud Tools 2.3.7.5. Attaches an existing volume with the specified id and mounts as /vol . The attached volume must be formated with a file system recognizable by linux (such as xfs or ext3).
New in Cloud Tools 2.3.7.5. Creates and attaches a new volume with specified size (GBs) and mountes as /vol . The new volume is formatted with the XFS file system.
New in Cloud Tools 2.3.7.5. Creates and attaches a new volume with specified size (GBs) and mountes as /vol . The new volume is formatted with the XFS file system.
New in Cloud Tools 2.3.7.9. By default the attached ebs volume is not deleted when the machine shuts down. Setting this value to true would delete the ebs volume when the machine shuts down. The data stored on the ebs volume is lost once it is deleted and cannot be recovered.
New in Cloud Tools 2.3.7.8. By default any machine that is reported as "running" is expected to start the cloudtools startup script within 3 minutes. A machine that takes longer to boot is terminated and a new machine is started in its place.
You can override this optional timeout for any machine.
You must disable this timeout for machines that do not run the cloudtools startup script.
Used for running GigaSpaces Service Manager and the DPA.
With very large deployment we suggest Large and Extra Large AMI type to be used for GSM Machine.
Element Name
Description
gsm-per-machine
number of GigaSpaces managers that will run on a machine
processing-units
definition of the processing units that will be deployed on the cloud, it is build of <processing-unit> elements which each can have:
<name> - name of the jar file containing the processing unit.
<deploy-options> - optional - contains processing unit deploy options, please refer to the gigaspaces documentation .
<command> - optional - a shell command that will replace the default puDeploy command. Any shell command is valid here, usualy we run scripts that were loaded using transfer-files.
<sla> - optional - contains the xml definition of the processing unit SLA.
example:
Used for running GigaSpaces Service Container, which provides SLA capabilities and hosts the processing units we deploy.
Element Name
Description
gsc-per-machine
number of gigaspaces containers that will run on the machine
load-balancer-machine Element
Enables the HTTP Apache Load-Balancer and its GigaSpaces Agent as part of the deployment configuration file.
This will allow incoming HTTP request to be routed from the HTTP Apache Load-Balancer into the Web servers hosted within GigaSpaces containers.
The HTTP Apache Load-Balancer configuration will be updated while the system is running allowing you to add new web servers instances (manually or automatically based on SLA).
Having additional web servers will allow you to scale to web layer of your application and provide better response time for incoming HTTP requests.
To enable the HTTP Apache Load-Balancer and its Agent have the following as part of your deployment configuration file:
Each machine can have its own properties such as AMI type , files to transfer etc.
See below example for the <machines> section you can declare as part of the cloud configuration file:
The name of the application. You can run several applications on the same repository-name using only different <cloud-name>. Don't put white spaces in the <cloud-name>.
Repository-name
The repository-name Rules should follow these rules:
No forward slash or backslash.
Only lowercase letters, numbers, periods(.) and dashes(-) .
Must start with a number or letter.
Must be between 3 and 255 characters long.
Cannot be in IP address style (e.g. "192.168.5.4").
Should not contain an underscore (_).
Should not end with a dash.
Should not have dashes appear next to periods. For example, "my-.repository" is an invalid name.
The <repository-name> is actualy an S3 bucket name which is dedicated for running applications on your AWS account, It is possible that a bucket name will already be used by another user, In that case an error will appear and you will need to choose a different name for runing your applications.
When running from the web console the <repository-name> is automatically picked from the gigaspaces license you provide.
Alternative S3 Directory and the $CPD place holder.
The <alternate-s3-source-dir> element contians the S3 path of your application files and determines the value of the $CPD place holder.
If the <alternate-s3-source-dir> element is not defined, the $CPD value will be the current deployment xml file directory.
The $CPD can be used in any path value like <transfer-files>, <processing-units>, <parent-config-filename>, <script-source>.
AMI Type and AMI ID
Determines the Amazon Image and type that will used to run our machine.
Example:
You can choose between Small,High-CPU Medium,Large,Extra Large and High-CPU Extra Large AMI types.
The AMI type and AMI ID must have matching platforms.
Instances Types
Here are the supported instances types:
Type
RAM Size
Compute Unit
Compute Unit Definition
Storage Size
Platform
Default
Small
1.7 GB
1 EC2
1 virtual core with 1 EC2 Compute Unit
160 GB
32-bit
Default
Large
7.5 GB
4 EC2
2 virtual cores with 2 EC2 Compute Units
850 GB
64-bit
Extra Large
15 GB
8 EC2
4 virtual cores with 2 EC2 Compute Units
1690 GB
64-bit
High-CPU Medium
1.7 GB
5 EC2
2 virtual cores with 2.5 EC2 Compute Units
350 GB
32-bit
High-CPU Extra Large
7 GB
20 EC2
8 virtual cores with 2.5 EC2 Compute Units
1690 GB
64-bit
The Small, Large and Extra Large are well suited for most applications.
The High-CPU Medium and the High-CPU Extra Large have proportionally more CPU resources than memory (RAM) and are well suited for compute-intensive applications.
New In Cloud Tools 2.3.7: eu-west-1a and eu-west-1b availability Zones. Since version 2.3.7.5 the zone is optional, but if specified it must match the specified region.
GigaSpaces Zone
New In Cloud Tools 2.3.7
By default the GigaSpaces zone that is assigned to any GSC machine started on the cloud is the GSC machine name provided as part of the deployment descriptor. This name can be used to provision a specific processing unit instance(s) into a specific GSC machine profile instances. You should use the zones options as part of the deployment options to instruct the GSM to provision the deployed PU into the relevant GSC associated with the relevant zone.
Security-Groups
Amazon's EC2 cloud has a built-in firewall capability that is easy to setup. It is based on the concept of security groups . A security group is simply a group of access rules that apply to any instance which is a member of that group. These rules specify what machines are allow to connect to members of that group. A typical real world example would be a "database" group that needs to allow access to the "web" group. The "web" group needs to allow access to the public internet on port 80.
The application configuration file includes the <security-groups> Element allowing you to specify the pre-defined security-groups to be used when running the machine.
Here is how you should specify the security group to be used when deploying your application:
Amazon EC2 Security Groups used for running the AMI secured, to define more than one security group seperate them by comma,
If no Security-Groups are specified, the machine instance is assigned to the default group. By default, this group allows all network traffic from other members of this group and discards traffic from other IP addresses and groups. If this does not meet your needs, you can modify the rule settings of the default group.
Every Deployment file can include the <parent-config-filename> Element which enables reuse of deployment descriptor files, by including it all of the <parent-config-filename> elements are automatically included in the current deployment.
The <parent-config-filename> is an optional Element
GigaSpaces Release Handling
The GigaSpaces EC2 AMI support multiple GigaSpaces releases. You may specify the exact version you would like to use as part of the deployment file. Use the <gigaspaces-build-location> element to include the build location to be downloaded into the AMI once started:
The <gigaspaces-version-id> should be a S3 path to a valid GiagSpaces build zip file. If you have a special build you may place it on S3 and place its location.
Cloud Tools Version
The cloud-tools-build-location specifies the GigaSpaces Cloud Tools build to use. This is the cloud tools version that will be loaded into the machines while started to perform dynamic scaling or any other cloud related activities.
If the application descriptor does not specify a cloud-tools-build-location , a default one will be used.
Each Machine can be assigned with a specific Elastic IP Addresses. See below example:
Use the Amazon command line, ElasticFox or Amazon Console to allocate a new elastic (static) IP Address.
Place the IP address as part of the <elastic-ip> as demonstrated below.
The <load-balancer-machine> Element with <elastic-ip>
Once you will deploy your application, the started machine will have the given IP address assigned.
Machine Password
To fully secure the application deployment on the cloud you may use the <machine-password> element. Once this Element is set it controls the following:
NX Server access password
gsadmin user login password
root user password
When having the Load-Balancer machine running in secured mode the Apache HTTP pass-phrase is 1234. You may change this with your deployment. When running in secured mode a client accessing the machines may use HTTPS secured protocol mode.
See below example for the <machine-password> Element:
The Name of the key-pair that will be used when launching a new instance, if it is a new name then a new key-pair will be created automatically.
All instances that are created from images that use this key pair will have access to the associated public key at boot.
You can use this key to provide secure access to an instance of an image on a per-instance basis. This feature is used to provide secure access without passwords.
Files Transfer
Used for transferring files from the local computer or from S3 to the running machines.
You may transfer a none-zipped file (use the <source> Element) or a zipped file (use the <source-zipped> Element) that will be unzipped at a specified location.
Example:
$CPD If <alternate-s3-source-dir> element is defined as part of the deployment config then the files will be downloaded from S3 into the machine started where the $CPD will be replaced by <alternate-s3-source-dir> value. Otherwise files will be copied from the local machine file system into the machine where the $CPD will be representing the deployment config current file path.
The Initialization Scripts Files
The cloud deployment process allows you to run your commands before and after running the GSC, GSM or the cloud desktop.
You may call your commands via the relevant scripts.
The initialization scripts are located by default at \cloudtools\default-settings\scripts.
These are placed into S3 as part of the deployment process, and used with the started machine.
Here are the provided scripts:
gsc-init.sh – this script is called before starting the GSC
gsm-init.sh – this script is called before starting the GSM
ui-init.sh – this script is called before starting the UI
gsc-post-init.sh – this script is called after starting the GSC
gsm-post-init.sh – this script is called after starting the GSM before waiting for GSCs
gsm-deploy-pre.sh – this script is called after starting the GSM after waiting for GSCs and before deploying PUs.
gsm-deploy-post.sh – this script is called after starting the GSM after waiting for GSCs and after deploying PUs.
server-init.sh – this script is launched when the machine is started
desktop-init.sh – this script is called when the cloud desktop is started
Use your own Initialization files
You can override those scripts and use your own scripts by naming your target file name as one of this names in transfer-files Element.
gsc-init Example
Here is an example how you can change the GSC Xmx and Xms settings when running on the cloud.
Have a file named gsc-init.sh to incldue the following:
Place the gsc-init.sh on the application repository at S3 (in out case at the myapplication bucket).
Add into the Application deployment file the following:
Prior starting the the GSC , the gsc-init.sh will be called, setting the EXT_JAVA_OPTIONS variable.
This will be used with the setenv.sh script called before starting the GSC (using the gsc.sh script).
UI Machine.
The <start-ui> element Defines if to start a machine dedicated for admin, and how to display the admin UI, Options are:
admin-application/true - Starts the GigaSpaces Management Center, running in the cloud, without displaying the cloud desktop.
false - Does not start the GigaSpaces Management Center.
admin-desktop - Starts the web-based cloud desktop. Does not start the GigaSpaces Management Center.
instance-only - Starts an AMI instance with the NX server running. Does not start the web-based cloud desktop.
Dynamic Provisioning Agent (DPA)
The DPA allows you to configure your deployment to start a new virtual machine once an SLA event triggered and scale your application dynamically or allow it to self-heal itself. SLA event could be a result of a provisioning failure event or any other type of provisioning event. The DPA getting provisioning events from the GSM and calls the cloud provider API to start new GSC machines. Once these new GSCs identified by the GSM, it provision missing application instances (web application,spaces , services) into these newly started GSCs.
How to enable the Dynamic Provisioning agent?
The DPA includes the following parameters in the root [cloud-config]:
<scaling-machine-name> - Machine name to scale - This should be a machine name you specified as part of your deployment machine names.
<number-of-machines-for-scaling> - The Scalability increment ratio - Amount of machines to start once the Dynamic scalability agent is triggered. Value 0 (ZERO) would not trigger the DPA.
The amount of GSCs that will be started on each is machine is based on the <gsc-per-machine> value.
The DPA is started on the machine running the GSM.
Here is an example for a Deployment xml file that using raw-machine to deploy a web application on Tomcat 5.5:
<cloud-config><cloud-name>my Tomcat web app</cloud-name><alternate-s3-source-dir>s3bucketname/s3application directory</alternate-s3-source-dir><machines><raw-machine><name>Web App</name><script-source>$CPD/deployScript.sh</script-source><script-target>deployScript.sh</script-target><number-of-machines>1</number-of-machines><transfer-files><file><source>$CPD/myApp.war</source><target>/home/gsadmin/apache-tomcat-5.5.27/webapps/myApp.war</target></file><file><source>$CPD/server.xml</source><target>/home/gsadmin/apache-tomcat-5.5.27/conf/server.xml</target></file></transfer-files></raw-machine></machines></cloud-config>
The deployScript.sh file should be placed at S3 under s3bucketname/s3application directory the folder. This will start the Tomcat:
echo Starting Web application deployment script
export JAVA_HOME=/usr/lib/jdk1.6.0_11/jre/
apache2ctl stop
pkill -9 apache
cd /home/gsadmin/apache-tomcat-5.5.27/bin
chmod 775 *
./startup.sh
cd ~gsadmin
echo "Deployed" > state.txt
s3 put "$bucketName""${clusterName}/state" state.txt
The server.xml fileshould be placed at S3 under {s3bucketname/s3application directory the folder.
<?xml version="1.0" encoding="UTF-8"?><Server port="8005" shutdown="SHUTDOWN"><Listener className="org.apache.catalina.core.AprLifecycleListener" /><Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" /><Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" /><Listener className="org.apache.catalina.storeconfig.StoreConfigLifecycleListener"/><!-- Global JNDI resources --><GlobalNamingResources>
<!-- Editable user database that can also be used by
UserDatabaseRealm to authenticate users -->
<Resource name="UserDatabase" auth="Container"
type="org.apache.catalina.UserDatabase"
description="User database that can be updated and saved"
factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
pathname="conf/tomcat-users.xml" />
</GlobalNamingResources><!-- Define the Tomcat Stand-Alone Service --><Service name="Catalina"><!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<Connector port="80" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true" />
<!-- Define an AJP 1.3 Connector on port 8009 -->
<Connector port="8009"
enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />
<!-- Define the top level container in our container hierarchy --><Engine name="Catalina" defaultHost="localhost">
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
resourceName="UserDatabase"/>
<Host name="localhost" appBase="webapps"
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">
</Host></Engine></Service></Server>
This example deploying a Web application into the Jetty container hosted within the GSC:
New In Cloud Tools 2.3.7.5. Specifies the Region for all machine instances. Default region is us-east-1 
See the 
Add Comment