com.meltmedia.jgroups.aws

Class AWS_PING

java.lang.Object

org.jgroups.stack.Protocol

org.jgroups.protocols.Discovery

com.meltmedia.jgroups.aws.AWS_PING

public class AWS_PING
extends org.jgroups.protocols.Discovery

A discovery protocol that uses the AWS EC2 API to find cluster members. Membership can be determined by a general filter and/or by nodes that have similar tags. This discovery protocol is designed to work with the TCP protocol.

Requirements

• The EC2 instances must be in the same region.
• The "ec2:Describe*" action must be accessable using either IAM credentials or an IAM instance profile.
• The security rules must allow TCP communication between the nodes that are discovered.

Tag Matching

To use the tag matching feature, use the tags attribute to specify a comma delimited list of tags. All of the nodes with matching values for these tags will be discovered.

 <com.meltmedia.jgroups.aws.AWS_PING  port_number=“7800”  tags=“Type,Environment”  access_key=“YOUR_AWS_ACCESS_KEY”  secret_key=“YOUR_AWS_SECRET_KEY”/> 

EC2 Filters

To use EC2's filtering feature to discover nodes, specify the filters attribute. The format for this attribute is:

 FILTERS ::= <FILTER> (‘;’ <FILTER>)* FILTER ::= <NAME> ‘=’ <VALUE> (‘,’ <VALUE>)* 

EC2 instances that match all of the supplied filters will be returned. For example, if you wanted to cluster with all of the running, small instances in your account, you could specify:

 <com.schibsted.publishing.jgroups.aws.AWS_PING  port_number=“7800”  filters=“instance-state-name=running;instance-type=m1.small”  access_key=“YOUR_AWS_ACCESS_KEY”  secret_key=“YOUR_AWS_SECRET_KEY”/> 

IAM Instance Profiles

Starting with version 1.1.0, instance profiles are supported by AWS_PING. To use the instance profile associated with an EC2 instance, simply omit the access_key and secret_key attributes:

 <com.schibsted.publishing.jgroups.aws.AWS_PING  port_number=“7800”  tags=“Type,Environment”/> 

References

• EC2 Using Filtering
• EC2 Describe Instances
• EC2 Instance Metadata

Author:

Christian Trimble, John McEntire

Nested Class Summary

Nested classes/interfaces inherited from class org.jgroups.protocols.Discovery

org.jgroups.protocols.Discovery.DiscoveryCacheDisseminationTask

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	access_key
protected java.lang.String	credentials_provider_class
protected java.lang.String	filters
protected int	port_number
protected int	port_range
protected java.lang.String	secret_key
protected java.lang.String	tags

Fields inherited from class org.jgroups.protocols.Discovery

async_discovery, async_discovery_use_separate_thread_per_request, break_on_coord_rsp, cluster_name, current_coord, discovery_rsp_expiry_time, is_coord, is_leaving, is_server, local_addr, max_members_in_discovery_request, max_rank_to_reply, num_discovery_requests, ping_responses, return_entire_cache, send_cache_on_join, sends_can_block, stagger_timeout, timer, transport_supports_multicasting, use_disk_cache, use_ip_addrs, view, WHITESPACE

Fields inherited from class org.jgroups.stack.Protocol

after_creation_hook, down_prot, ergonomics, id, log, stack, stats, up_prot

Constructor Summary

Constructors

Constructor and Description
AWS_PING()

Method Summary

Modifier and Type	Method and Description
protected void	findMembers(java.util.List<org.jgroups.Address> members, boolean initial_discovery, org.jgroups.util.Responses responses) Fetches all of the cluster members found on EC2.
void	init() Scans the environment for information about the AWS node that we are currently running on and parses the filters and tags.
boolean	isDynamic() Returns true.
void	stop() Stops this protocol.

Methods inherited from class org.jgroups.protocols.Discovery

addDiscoveryResponseToCaches, addResponse, addressAsString, addToCache, breakOnCoordResponse, breakOnCoordResponse, deserialize, discoveryRequestReceived, discoveryRspExpiryTime, disseminateDiscoveryInformation, down, dumpCache, findInitialMembersAsString, findMembers, getCurrentCoord, getNumberOfDiscoveryRequestsSent, getView, getViewId, handleConnect, handleDisconnect, handleDiscoveryResponse, isCoord, isMergeRunning, marshal, providedUpServices, read, readPingData, resetStats, returnEntireCache, returnEntireCache, sendCacheInformation, sendDiscoveryResponse, serializeWithoutView, staggerTimeout, staggerTimeout, start, startCacheDissemination, up, up, useDiskCache, useDiskCache, weedOutCompletedDiscoveryResponses, write

Methods inherited from class org.jgroups.stack.Protocol

accept, afterCreationHook, destroy, down, enableStats, getConfigurableObjects, getDownProtocol, getDownServices, getId, getIdsAbove, getLevel, getLog, getName, getProtocolStack, getSocketFactory, getThreadFactory, getTransport, getUpProtocol, getUpServices, getValue, isErgonomics, level, parse, providedDownServices, requiredDownServices, requiredUpServices, resetStatistics, setDownProtocol, setErgonomics, setId, setLevel, setProtocolStack, setSocketFactory, setUpProtocol, setValue, statsEnabled, up

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

credentials_provider_class

protected java.lang.String credentials_provider_class

access_key

protected java.lang.String access_key

secret_key

protected java.lang.String secret_key

filters

protected java.lang.String filters

tags

protected java.lang.String tags

port_range

protected int port_range

port_number

protected int port_number

Constructor Detail

AWS_PING

public AWS_PING()

Method Detail

init

public void init()
          throws java.lang.Exception

Scans the environment for information about the AWS node that we are currently running on and parses the filters and tags.

Overrides:

init in class org.jgroups.protocols.Discovery

Throws:

java.lang.Exception

stop

public void stop()

Stops this protocol.

Overrides:

stop in class org.jgroups.protocols.Discovery

isDynamic

public boolean isDynamic()

Returns true.

Specified by:

isDynamic in class org.jgroups.protocols.Discovery

Returns:

true

findMembers

protected void findMembers(java.util.List<org.jgroups.Address> members,
                           boolean initial_discovery,
                           org.jgroups.util.Responses responses)

Fetches all of the cluster members found on EC2. The host portion of the addresses are the private ip addresses of the matching nodes. The port numbers of the addresses are set to the port number plus all the ports in the range after that specified on this protocol.

Specified by:

findMembers in class org.jgroups.protocols.Discovery