Service Grid

❗️

This is a legacy Apache Ignite documentation

The new documentation is hosted here: https://ignite.apache.org/docs/latest/

Overview

Service Grid allows for deployments of arbitrary user-defined services on the cluster. You can implement and deploy any service, such as custom counters, ID generators, hierarchical maps, etc.

For instance, Service Grid can be used as a backbone of a micro-services based solution or application. Learn more about this use case from the following series of articles:

• Microservices on Top of Apache Ignite - Part I
• Microservices on Top of Apache Ignite - Part II
• Microservices on Top of Apache Ignite - Part III

Ignite allows you to control how many instances of your service should be deployed on each cluster node and will automatically ensure proper deployment and fault tolerance of all the services .

Features

• Continuous availability of deployed services regardless of topology changes or crashes.
• Automatically deploy any number of distributed service instances in the cluster.
• Automatically deploy singletons, including cluster-singleton, node-singleton, or key-affinity-singleton.
• Automatically deploy distributed services on node start-up by specifying them in the configuration.
• Undeploy any of the deployed services.
• Get information about service deployment topology within the cluster.
• Create service proxy for accessing remotely deployed distributed services.

👍

Please refer to Service Example for information on service deployment and accessing service API.

🚧

Note, that by default it's required to have a Service class in the classpath of all the cluster nodes. Peer class loading (P2P class loading) is not supported for Service Grid. Learn more from services deployment management section on how to overcome this default requirement.

IgniteServices

All service grid functionality is available via IgniteServices interface.

Ignite ignite = Ignition.ignite();

// Get services instance spanning all nodes in the cluster.
IgniteServices svcs = ignite.services();

You can also limit the scope of service deployment to a Cluster Group. In this case, services will only span the nodes within the cluster group.

Ignite ignite = Ignitition.ignite();

ClusterGroup remoteGroup = ignite.cluster().forRemotes();

// Limit service deployment only to remote nodes (exclude the local node).
IgniteServices svcs = ignite.services(remoteGroup);

Load Balancing

In all cases, other than singleton service deployment, Ignite will automatically make sure that about an equal number of services are deployed on each node within the cluster. Whenever cluster topology changes, Ignite will re-evaluate service deployments and may re-deploy an already deployed service on another node for better load balancing.

Fault Tolerance

Ignite always guarantees that services are continuously available, and are deployed according to the specified configuration, regardless of any topology changes or node crashes.

Deployment Management

By default, an Ignite Service will be deployed on a random node (or nodes) depending on the cluster workload as it's described in the load balancing section above.

In addition to this default approach, Ignite provides an API that allows limiting an Ignite Service deployment to a specific set of nodes. There are several approaches to do that and all of them are covered below.

Node Filter Based Deployment

This approach is based on a filtering predicate that gets called on every node at the time Ignite Service engine determines a set of possible candidates for the Ignite Service deployment. If the predicate returns true then a node will be included in the set or it will be excluded otherwise.

A node filter has to implement IgnitePredicate<ClusterNode> interface like it does the exemplary filter below which will instruct the Service Grid engine to deploy an Ignite Service on non client nodes that have west.coast.attribute in their local attributes map.

// The filter implementation.
public class ServiceFilter implements IgnitePredicate<ClusterNode> {
	@Override public boolean apply(ClusterNode node) {
  	// The service will be deployed on non client nodes
    // that have the attribute 'west.coast.node'.
    return !node.isClient() &&
    node.attributes().containsKey("west.coast.node");
  }
}

After the filter is ready you can pass it to ServiceConfiguration.setNodeFilter(...) method and start the service using this configuration.

// Initiating cache configuration. 
ServiceConfiguration cfg = new ServiceConfiguration();
        
// Setting service instance to deploy.
cfg.setService(service);
        
// Setting service name.
cfg.setName("serviceName");
        
// Providing the nodes filter.
cfg.setNodeFilter(new ServiceFilter());
        
// Getting instance of Ignite Service Grid.
IgniteServices services = ignite.services();
        
// Deploying the service.
services.deploy(cfg);

🚧

Make sure that a node filter's class is located in the classpath of every Ignite node regardless of the fact whether an Ignite Service is going to be deployed there or not. Otherwise you'll get a ClassNotFoundException.

On the other hand, you're free to add the Ignite Service class implementation to the classpath of those nodes only where the service might be deployed in principle throughout the lifetime of a cluster.

Cluster Group Based Deployment

One more approach is based on the definition of a specific ClusterGroup. Once a reference to Ignite Service Grid is obtained for a specific cluster group the deployment of a new Ignite Service will happen on one or a number of the nodes from that group only.

// A service will be deployed on the server nodes only.
IgniteServices services = ignite.services(ignite.cluster().forServers());

// Deploying the service.
services.deploy(serviceCfg);

Affinity Key Based Deployment

The latest approach that allows influencing on an Ignite Service deployment is based on an affinity key definition. The service's configuration has to contain a value for the affinity key as well as a cache name to which this key belongs to and during the service startup Ignite Service Grid will deploy the service on a node that is primary for the given key. If the primary node changes throughout the time then the service will be re-deployed automatically as well.

// Initiating cache configuration.
ServiceConfiguration cfg = new ServiceConfiguration();

// Setting service instance to deploy.
cfg.setService(service);

// Setting service name.
cfg.setName("serviceName");

// Setting the cache name and key's value for the affinity based deployment.
cfg.setCacheName("orgCache");
cfg.setAffinityKey(123);

// Getting instance of Ignite Service Grid.
IgniteServices services = ignite.services();

// Deploying the service.
services.deploy(cfg);

After the service is deployed using the configuration from the example above, Ignite will make sure to deploy the service on a node that is primary for key 123 stored in cache named orgCache.

Service Updates (Redeployment)

If you have a service in a cluster and you want to update its implementation without stopping the cluster, the basic procedure is:

1. Update the JAR file(s) in the repository where the service is stored (pointed to by your UriDeploymentSpi configuration's uriList property).
2. Call the services().cancel() method to stop the service.
3. Redeploy the service.

Example Configuration

Here's an example UriDeployment configuration, note the uriList property:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
    <property name="deploymentSpi">
        <bean class="org.apache.ignite.spi.deployment.uri.UriDeploymentSpi">
            <property name="uriList">
                <list>
                    <value>file:///Users/ExampleUser/Code/gridgain/playground/service/repository/</value>
                </list>
            </property>
            <property name="temporaryDirectoryPath" value="/Users/ExampleUser/.ignite/deployments/"/>
        </bean>
    </property>
    
    <!-- Other configuration -->
</bean>

Example of how to redeploy the service:

try (Ignite ignite = Ignition.start("config/ignite.xml")) {
    String srvcName = "test-service";
    ignite.services().cancel(srvcName);
    ignite.services().deployNodeSingleton(srvcName, new TestService());
}

Service Undeployment

Ignite stores descriptors for already deployed services on all nodes in topology. In case a service is deployed on a subset of nodes as described above, stopping all these nodes will not undeploy the service. Once at least one node that satisfies the nodes filter is back up and running, the service will be restarted with the same configuration.

To redeploy a service with updated resources or implementation (updated JAR files, for example), see Service Updates.

To undeploy a service, use the IgniteServices#cancel or IgniteServices#cancelAll methods.

// Getting instance of Ignite Service Grid.
IgniteServices services = ignite.services();

services.cancel("serviceName");