GigaSpaces Agent

A Processing Unit This is the unit of packaging and deployment in the GigaSpaces Data Grid, and is essentially the main GigaSpaces service. The Processing Unit (PU) itself is typically deployed onto the Service Grid. When a Processing Unit is deployed, a Processing Unit instance is the actual runtime entity. is deployed to the GigaSpaces runtime environment, which is called the service grid. The service grid 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 GigaSpaces Agent utility located in the $GS_HOME/bin folder. This will start the Grid Service Agent, which is responsible for starting and managing the other service grid components (GSC Grid Service Container. This provides an isolated runtime for one (or more) processing unit (PU) instance and exposes its state to the GSM., GSM Grid Service Manager. This is is a service grid component that manages a set of Grid Service Containers (GSCs). A GSM has an API for deploying/undeploying Processing Units. When a GSM is instructed to deploy a Processing Unit, it finds an appropriate, available GSC and tells that GSC to run an instance of that Processing Unit. It then continuously monitors that Processing Unit instance to verify that it is alive, and that the SLA is not breached., 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.

Help

Run the --help or -h command to see all available options:

./gs.sh host run-agent --help

gs.bat host run-agent --help

Starting the Data Grid with a Manager

Use the following command to start a single Manager on your local machine (useful for development and testing):

# Starts a local manager:
./gs.sh host run-agent --auto
# Starts a local manager and 2 GSCs:
./gs.sh host run-agent --auto --gsc=2

# REM Starts a local manager:
gs.bat host run-agent --auto
# REM Starts a local manager and 2 GSCs:
gs.bat host run-agent --auto --gsc=2

To start a highly available cluster of Managers on several hosts, run the following command on each designated host:

# Starts a manager:
./gs.sh host run-agent --manager
# Starts a manager and 2 GSCs:
./gs.sh host run-agent --manager --gsc=2

# REM Starts a manager:
gs.bat host run-agent --manager
# REM Starts a manager and 2 GSCs:
gs.bat host run-agent --manager --gsc=2

Starting a Data Grid Without a Manager

If you can't start the Manager for some reason, but you still want high availability, you can select specific host machines as management servers, and start a LUS Lookup Service. This service provides a mechanism for services to discover each other. Each service can query the lookup service for other services, and register itself in the lookup service so other services may find it. and GSM on each one:

# Starts a LUS and GSM:
./gs.sh host run-agent --custom=lus=1 --custom=gsm=1
# Starts a LUS, GSM and 2 GSCs:
./gs.sh host run-agent --custom=lus=1 --custom=gsm=1 --custom=gcs=2

# REM Starts a LUS and GSM:
gs.bat host run-agent --custom=lus=1 --custom=gsm=1
# REM Starts a LUS, GSM and 2 GSCs:
gs.bat host run-agent --custom=lus=1 --custom=gsm=1 --custom=gcs=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 two global GSM and LUS components across a set of hosts, as well as 2 GSCs on each host, you can use the following command:

# Starts a LUS, GSM and 2 GSCs:
./gs.sh host run-agent --custom=global.lus=2 --custom=global.gsm=2 --custom=global.gsc=2

# REM Starts a LUS, GSM and 2 GSCs: 
gs.bat host run-agent --custom=global.lus=2 --custom=global.gsm=2 --custom=global.gsc=2

This configuration is convenient for new users, so it is also the default - running GigaSpaces Agent without any arguments creates the same environment. If you want to start a data grid without any components, run the GigaSpaces Agent with no arguments. This can be useful if you're planning to use the REST REpresentational State Transfer. Application Programming Interface An API, or application programming interface, is a set of rules that define how applications or devices can connect to and communicate with each other. A REST API is an API that conforms to the design principles of the REST, or representational state transfer architectural style. Manager API from another host to add or remove containers.

# Run the command below if you intend to use the agent to start other service grid components later:
./gs.sh host run-agent (no arguments) 

# Run the command below if you intend to use the agent to start other service grid components later:
gs.bat host run-agent (no arguments) 

Configuring the Service Grid

Service grid configuration is often comprised of two layers, namely the system-wide configuration and component-specific configuration.

The system-wide configuration specifies the settings that all components share, such as discovery (unicast/multicast), security, zones, etc. These are set using the GS_OPTIONS_EXT environment variable.

The component-specific configuration specifies settings per component type, for example that the GSC memory limit should be greater than the GSM and LUS limits. These are set using one or more of the following environment variables: GS_GSA Grid Service Agent. This is a process manager that can spawn and manage Service Grid processes (Operating System level processes) such as The Grid Service Manager, The Grid Service Container, and The Lookup Service. Typically, the GSA is started with the hosting machine's startup. Using the agent, you can bootstrap the entire cluster very easily, and start and stop additional GSCs, GSMs and lookup services at will._OPTIONS, GS_GSC_OPTIONS, GS_GSM_OPTIONS, GS_LUS_OPTIONS.

For example:

export GS_GSA_OPTIONS=-Xmx256m
export GS_GSC_OPTIONS=-Xms2g -Xmx2g
export GS_MANAGER_OPTIONS=-Xmx1g

./gs.sh host run-agent --manager --gsc=4

set GS_GSA_OPTIONS=-Xmx256m
set GS_GSC_OPTIONS=-Xms2g -Xmx2g
set GS_MANAGER_OPTIONS=-Xmx1g

call gs.bat host run-agent --manager --gsc=4

Customizing the GSA Components

The GSA manages different process types. Each process type is defined within the $GS_HOME/config/gsa directory in an XML file that identifies the process type by name.

The following process types have default configurations:

Process Type	Description	File Name
manager	Defines a GigaSpaces Manager	manager.xml
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 Java Virtual Machine. A virtual machine that enables a computer to run Java programs as well as programs written in other languages that are also compiled to Java bytecode.	gsm_lus.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="pid-handshake">
    <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 spawn either a script-based process, or a pure JVM (with its arguments) process. The GSC, for example, allows 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 the restart-on-exit flag, controls whether the process will be restarted upon termination. The restart-on-exit flag has these types of values:
  • Default and recommended value pid-handshake - Restart the process on any exit value if the process started successfully, as indicated by a successful PID handshake.
  • always - Always restart the process if it exits.

  • !0 - Restart the process only if the exit code is different than 0.

  • never - Never restart the process if it exits.
• The shutdown-class is an implementation of com.gigaspaces.grid.gsa.ShutdownProcessHandler interface and provides the default shutdown hooks before and after shutdown of a process, to make sure it is shut down properly. The shutdown-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 an OutOfMemoryError.

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 the gsc.xml example above, there are two command line arguments.
• environment -adds an environment variable. For example, <environment name="GS_GSC_OPTIONS">-Xmx1024m</environment> can be used to override the memory for the GSC.

Advanced Configuration

In some scenarios you may need several "flavors' 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, you may want your GigaSpaces 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, duplicate the default gsc.xml (which resides in $GS_HOME/config/gsa) into gsc_small.xml and gsc_large.xml, and modify them to include an environment tag that defines the GS_GSC_OPTIONSenvironment variable with the required settings:

<process initial-instances="script" shutdown-class="com.gigaspaces.grid.gsa.GigaSpacesShutdownProcessHandler" restart-on-exit="pid-handshake">
    <script enable="true" work-dir="${com.gs.home}/bin"
            windows="${com.gs.home}\bin\gs.bat" unix="${com.gs.home}/bin/gs.sh">
        <argument>services=GSC</argument>
        <environment name="GS_COMPONENT_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>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="pid-handshake">
    <script enable="true" work-dir="${com.gs.home}/bin"
            windows="${com.gs.home}\bin\gs.bat" unix="${com.gs.home}/bin/gs.sh">
        <argument>services=GSC</argument>
        <environment name="GS_COMPONENT_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>services=GSC</argument>
    </vm>
    <restart-regex>.*java\.lang\.OutOfMemoryError.*</restart-regex>
</process>

Now to start the GigaSpaces Agent, use the following command:

./gs.sh host run-agent --custom=gsc_small=2 --custom=gsc_large

gs.bat host run-agent --custom=gsc_small=2 --custom=gsc_large