1. The most basic use is for services installed and configured by Chef or
    Cluster-Init to report the Configuration Data required by a CycleCloud
    component to monitor or control that services.
  2. The other primary use is to heartbeat the service they represent. The
    messages will be sent periodically as long as the instance is up and the
    system is reporting.

How Does it Work?

To send configuration data back to CycleCloud, simply write a script that outputs the data in json format to stdout to the service.d directory at:


CycleCloud clusters periodically iterate over the json files in the service.d directory and send the content back to CycleCloud via jetpack send.

CycleCloud listens for registration messages from any node in the clusters it manages. When a status message is received, CycleCloud inspects the message for a system attribute, it then looks for plugins which register themselves as handlers for that system and passes the message to their handleService method.

Message Schema

Each message must be a valid JSON object. To register and heartbeat a service, simply create a file with extension .json in the status.d directory. The content of those files will be sent without modification as long as they are valid JSON. The JSON messages will be parsed and passed to the plugins as a python dictionary.

Attribute Description
system Identifies the service being registered. Used to lookup handler
plugins for the messages, so if system is not set, the message
will simply be dropped.
hostname The hostname as known locally by the system being registered.
ports A map of (name => port) pairs required by the service.


  • The only required Attribute is system.
  • Services may include any additional attributes they require for configuration.
  • The defined attributes may be automatically translated by CycleCloud from
    internal values to values meaningful external to the cloud provider (for
    example, internal/private hostnames may be translated to external/public

For example, a basic ganglia status update (for configuration only) might look like this:

   "system": "ganglia",
   "cluster_name": "test_cluster",
   "hostname": "",
   "ports": {"ganglia": 8652,
             "ssh": 22}

Handler Plugins

Jython System Status Handler plugins must implement following interface:

def handleService(service_status_list)

where service_status_list is a list of the most recent service_status events. Each service_status is a python dictionary including node details and the parsed JSON object representation of the specific service message.

The service_status includes at least the following attributes:

Attribute Description
data The parsed JSON object received from the service. The only
modification to the data is to apply internal-to-external
attribute translations if needed.
node (If available) The node representation for the node that sent
the status message.
cluster_name The name of the cluster containing the node that sent the
status message.
state Heartbeat status. One of [‘active’, ‘inactive’, ‘deleted’] (see below for details).

To register as a handler for a service, the plugin’s .cfg file should contain the following attributes:

Implements = ServiceStatus.Listener
Systems = ={SYSTEM_NAMES}

For example, the Ganglia system status listener has the following .cfg file:

Implements = ServiceStatus.Listener
Systems = ganglia

Service States

The state attribute on the service object represents the availability of the service for monitoring.

State Meaning
active The node is up and the service is available for monitoring.
inactive The service is unavailable for monitoring (usually because the
cluster has been terminated)
deleted The node hosting the service has been permanently removed
(usually because the cluster has been deleted)