GS-Agent
A processing unit is deployed onto the XAP runtime environment, which is called the Service Grid. It is responsible for materializing the processing unit’s configuration, provisioning its instances to the runtime infrastructure and making sure they continue to run properly over time.
Usage
To start a Service Grid on a machine, launch the gs-agent
utility located in the $XAP_HOME/bin
folder. This will start the Grid Service Agent, which is responsible of starting and managing the other Service Grid components (GSC, GSM, etc.). Command-line arguments are used to specify which Service Grid components should be started and managed. In general, --process_type=n
will start n
instances of the specified process_type
. Use the global
keyword (e.g. --global.process_type=n
) to specify that the agent should coordinate with other running agents the hosting and management of that service. Let’s look at common use cases:
Help
Run gs-agent with --help
or -h
to see all available options:
Linux
./gs-agent.sh --help
Windows
gs-agent --help
Manager
To start a single manager on the local machine (useful for dev and testing):
Linux
# Starts a local manager:
./gs-agent.sh --manager-local
# Starts a local manager and 2 GSCs:
./gs-agent.sh --manager-local --gsc=2
Windows
REM Starts a local manager:
gs-agent --manager-local
REM Starts a local manager and 2 GSCs:
gs-agent --manager-local --gsc=2
To start a highly-available cluster of managers on several hosts, run the following on each of the designated hosts:
Linux
# Starts a manager:
./gs-agent.sh --manager
# Starts a manager and 2 GSCs:
./gs-agent.sh --manager --gsc=2
Windows
REM Starts a manager:
gs-agent --manager
REM Starts a manager and 2 GSCs:
gs-agent --manager --gsc=2
(Note that you also need to configure the XAP_MANAGER_SERVERS
to the list of designated manager servers)
Without Manager
If you cannot use the manager for some reason, but you still want high-availability, you can pick a couple of hosts to serve for management, and start a LUS and GSM on them:
Linux
# Starts a LUS and GSM:
./gs-agent.sh --lus --gsm
# Starts a LUS, GSM and 2 GSCs:
./gs-agent.sh --lus --gsm --gsc=2
Windows
REM Starts a LUS and GSM:
gs-agent --lus --gsm
REM Starts a LUS, GSM and 2 GSCs:
gs-agent --lus --gsm --gsc=2
Alternatively, if your environment supports multicast and you prefer a more dynamic approach, you can use the global
prefix to indicate that GSMs and LUSs will be automatically started and managed by the collective of gs-agents, instead of explicitly on a specific hosts. For example, to start 2 Global GSM and LUS accross a set of hosts, as well as 2 GSCs on each host:
Linux
# Starts a LUS, GSM and 2 GSCs:
./gs-agent.sh --global.lus=2 --global.gsm=2 --gsc=2
Windows
REM Starts a LUS, GSM and 2 GSCs:
gs-agent --global.lus=2 --global.gsm=2 --gsc=2
In fact, since this configuration is convenient for new users, it is also the default - running gs-agent
without any arguments would produce the same effect. If you wish to disable it and start without any components, run gs-agent with --zero-defaults
or -z
. This can be useful if you’re planning to use the manager’s RESTful API from another host to add/remove containers.
Linux
./gs-agent.sh -z
Windows
gs-agent -z
Configuration
Service Grid configuration is often composed of two layers: system-wide configuration and component-specific configuration.
The system-wide configuration specifies settings which all components share, e.g. discovery (unicast/multicast), security, zones, etc. These are set using the EXT_JAVA_OPTIONS
environment variable.
The component-specific configuration specifies settings per component type, e.g. the GSC memory limit is greater than the GSM and LUS. These are set using one or more of the environment variables: XAP_GSA_OPTIONS
, XAP_GSC_OPTIONS
, XAP_GSM_OPTIONS
, XAP_LUS_OPTIONS
.
The component-specific configuration override the system-wide configuration.
For example:
Linux
export XAP_GSA_OPTIONS=-Xmx256m
export XAP_GSC_OPTIONS=-Xms2g -Xmx2g
export XAP_GSM_OPTIONS=-Xmx1g
export XAP_LUS_OPTIONS=-Xmx1g
./gs-agent.sh
Windows
set XAP_GSA_OPTIONS=-Xmx256m
set XAP_GSC_OPTIONS=-Xms2g -Xmx2g
set XAP_GSM_OPTIONS=-Xmx1g
set XAP_LUS_OPTIONS=-Xmx1g
call gs-agent.bat
Customizing GSA Components
GSA manages different process types. Each process type is defined within the $XAP_HOME/config/gsa
directory in an xml file that identifies the process type by its name.
You can change the default location of the GSA configuration files using the com.gigaspaces.grid.gsa.config-directory
system property.
The following are the process types that come out of the box:
Processes Type | Description | XML config file name |
---|---|---|
gsc | Defines a Grid Service Container | gsc.xml |
gsm | Defines a Grid Service Manager | gsm.xml |
lus | Defines a Lookup Service | lus.xml |
gsm_lus | Defines a Grid Service Manager and Lookup Service within the same JVM | gsm_lus.xml |
esm | Defines an Elastic Service Manager which is required for deploying Elastic Processing Unit | esm.xml |
Here is an example of the gsc.xml
configuration file:
<process initial-instances="script" shutdown-class="com.gigaspaces.grid.gsa.GigaSpacesShutdownProcessHandler" restart-on-exit="always">
<script enable="true" work-dir="${com.gs.home}/bin"
windows="${com.gs.home}/bin/gs.bat" unix="${com.gs.home}/bin/gs.sh">
<argument>start</argument>
<argument>"GSC"</argument>
</script>
<vm enable="true" work-dir="${com.gs.home}/bin" main-class="com.gigaspaces.start.SystemBoot">
<input-argument></input-argument>
<argument>com.gigaspaces.start.services="GSC"</argument>
</vm>
<restart-regex>.*java\.lang\.OutOfMemoryError.*</restart-regex>
</process>
The GSA can either spawn a script based process, or a pure JVM (with its arguments) process. The GSC for example, allows for both types of process spawning.
- The
initial-instances
parameter controls what type of spawning will be performed when the GSA spawns processes by itself (and not on demand by the Admin API). - The
shutdown-class
followed by therestart-on-exit
flag, controls if the process will be restarted upon termination. There are three types of values:always
- Always restarts the process if it exits.never
- Never restarts the process if it exists.!0
- Restarts the process only if the exit code is different than 0.
- The
shutdown-class
is an implementation ofcom.gigaspaces.grid.gsa.ShutdownProcessHandler
interface and provides the default shutdown hooks before and after shutdown of a process, to make sure it is shutdown properly. Theshutdown-class
can be omitted. - The
restart-regex
(there can be more than one element) is applied to each console output line of the managed process, and if there is a match, the GSA will automatically restart the process. By default, the GSC will be restarted if there is anOutOfMemoryError
.
In addition, within the script
tag, you can add the following tags:
argument
- adds a command ling argument which will be passed to the script. In thegsc.xml
example above, there are two command line arguments.environment
-adds an environment variable. For example,<environment name="XAP_GSC_OPTIONS">-Xmx1024m</environment>
can be used to override the memory for the GSC.
Advanced Configuration
In some scenarios you’ll need to have several ‘flavours’ of components (e.g. multiple zones, or different sizes of GSCs, etc.). You can create a custom gs-agent script to manage each of those, or you can do this all within a single agent.
For example, suppose we want our agent to load 2 ‘small’ GSCs (512MB each) in a zone called Small, and 1 ‘large’ GSC (1024MB) in a zone called Large. To achieve this, we’ll duplicate the default gsc.xml
(which resides in $XAP_HOME/config/gsa
) into gsc_small.xml
and gsc_large.xml
, and modify them to include an environment
tag which sets XAP_GSC_OPTIONS
to the required settings:
<process initial-instances="script" shutdown-class="com.gigaspaces.grid.gsa.GigaSpacesShutdownProcessHandler" restart-on-exit="always">
<script enable="true" work-dir="${com.gs.home}/bin"
windows="${com.gs.home}/bin/gs.bat" unix="${com.gs.home}/bin/gs.sh">
<argument>start</argument>
<argument>"GSC"</argument>
<environment name="XAP_GSC_OPTIONS"> -Xms512m -Xmx512m -Dcom.gs.zones=Small</environment>
</script>
<vm enable="true" work-dir="${com.gs.home}/bin" main-class="com.gigaspaces.start.SystemBoot">
<input-argument></input-argument>
<argument>com.gigaspaces.start.services="GSC"</argument>
</vm>
<restart-regex>.*java\.lang\.OutOfMemoryError.*</restart-regex>
</process>
<process initial-instances="script" shutdown-class="com.gigaspaces.grid.gsa.GigaSpacesShutdownProcessHandler" restart-on-exit="always">
<script enable="true" work-dir="${com.gs.home}/bin"
windows="${com.gs.home}/bin/gs.bat" unix="${com.gs.home}/bin/gs.sh">
<argument>start</argument>
<argument>"GSC"</argument>
<environment name="XAP_GSC_OPTIONS">-Xms1024m -Xmx1024m -Dcom.gs.zones=Large</environment>
</script>
<vm enable="true" work-dir="${com.gs.home}/bin" main-class="com.gigaspaces.start.SystemBoot">
<input-argument></input-argument>
<argument>com.gigaspaces.start.services="GSC"</argument>
</vm>
<restart-regex>.*java\.lang\.OutOfMemoryError.*</restart-regex>
</process>
Now, to start the agent, we’ll use the following command:
gs-agent --gsc_small=2 --gsc_large