Discovery

Corus supports different mechanisms for so-called "intra-cluster" discovery. It also supports external discovery, through Consul (other mechanisms are envisioned).

Intra-Cluster Discovery

Intra-cluster discovery designates the ability for Corus servers within a cluster to discover each other. Corus supports different middleware to enable this central functionality.

IP Multicast

By default, Corus uses IP multicast for intra-cluster discovery. Depending on how the network has been set up, IP multicast can be erratic, and is furthermore not supported in most cloud environments. Therefore, we recommend using it only for non-production setup (for example, when developping on a laptop).

Avis

If your network does not support IP multicast, then you may use Avis as a discovery mechanism. This means you must setup an Avis router (or multiple federated ones), and configure your Corus instances as clients of this router (here, "message broker" can be used as a synonym for "router").

The properties you have to configure to enable Avis-based discovery are the following (in $CORUS_HOME/config/corus.properties):

ubik.rmi.naming.broadcast.provider=ubik.rmi.naming.broadcast.avis
ubik.rmi.naming.broadcast.avis.url=elvin://<host>:<port>

As indicated, in the last property, you must provide the host and port of the Avis router to which to connect.

Please consult the Avis documentation for more details about setting up Avis and the URL format it mandates.

RabbitMQ

As an alternative to Avis, you may use RabbitMQ for intra-cluster discovery. In order to enable connection to RabbitMQ, edit Corus' configuration, and uncomment the following entries, replacing the placeholders for the RabbitMQ host and port. Also edit the file to set the proper username and password to use when connecting to RabbitMQ:

ubik.rmi.naming.broadcast.camel.endpoint.uri=rabbitmq://<host>:<port>/corus_cluster_channel
ubik.rmi.naming.broadcast.camel.rabbitmq.option.username=<username>
ubik.rmi.naming.broadcast.camel.rabbitmq.option.password=<password>

In addition, you will see that the file holds a not mentioning to uncomment the following properties (but to NOT modify them):

ubik.rmi.naming.broadcast.provider=camel
ubik.rmi.naming.broadcast.camel.rabbitmq.option.exchangeType=topic
ubik.rmi.naming.broadcast.camel.rabbitmq.option.autoDelete=true
ubik.rmi.naming.broadcast.camel.rabbitmq.option.durable=false
ubik.rmi.naming.broadcast.camel.rabbitmq.option.routingKey=corus.cluster.${corus.server.domain}
ubik.rmi.naming.broadcast.camel.rabbitmq.option.autoAck=true
ubik.rmi.naming.broadcast.camel.rabbitmq.header.rabbitmq.ROUTING_KEY=corus.cluster.${corus.server.domain}

As can be inferred from the configuration, Apache Camel is used behind the scenes to enable integration with RabbitMQm and each ubik.rmi.naming.broadcast.camel.rabbitmq.option entry found in Corus' configuration corresponds to a configuration option supported by Camel's RabbitMQ component (see that component's documentation for the details).

You should not have to bother with Came's configuration intricacies: the above instructions should be enough to get you going.

External Corus Discovery

External discovery is about third-party party applications being able to discover Corus instances present on the network, and potentially act remotely on them - through the REST API for example. This becomes handy in the context of large scale deployments: statically hard-coding the address of Corus nodes in configuration files for some monitoring application to consume (for example) is simply not practical.

Consul

As of release 4.6, Corus supports publishing its presence to Consul as a service, using Consul's REST API. The topology typically goes as follows: a Consul agent (a separate process) runs on each machine, and receives service registrations from processes on that machine. The agent is hooked to a set of centralized Consul servers, which in turn makes service information available to applications.

Service Definition

Given the above, a Consul agent would run on each machine where Corus itself runs, and each Corus instance would publish its service description to its "local" Consul agent . The service definition registered with Consul for a Corus instance has the following format:

{
  "ID": "corus-<corus_host_name>:<corus_port>",
  "Name": "Corus",
  "Tags": [
    "<corus_domain>"
  ],
  "Address": "<corus_ip_address>",
  "Port": "<corus_port>",
  "Checks": [
    {
      "id": "check-corus-<corus_host_name>:<corus_port>",
      "name": "Health check for Corus node at: <corus_host_name>:<corus_port>",
      "ttl": <ttl_seconds>
    }
  ]
}

The placeholders between angled brackets correspond to values that are set contextually. They are described below:

  • corus_host_name: the host name of the Corus instance.
  • corus_port: the port of the Corus instance.
  • corus_domain: the domain to which the Corus instance corresponds.
  • corus_ip_address: the IP address of the Corus instance.
  • ttl_seconds: the number of seconds for which to keep the service definition before it is discarded (this value is configured in corus.properties, as explained in the next subsection)
  • .

Configuration

There are different configuration properties to define in $CORUS_HOME/config/corus.properties for activating the integration with Consul. It is important to note that a Corus instance is responsible for refreshing its service definition periodically, since that definition must be assigned a time-to-live - Consul will remove all definitions that have not been refreshed within that given time-to-live.

The following properties are used to define how Corus interacts with Consul:

PropertyDescription
corus.server.pub.consul.enabled Enables or disables Consul integration (false by default).
corus.server.pub.consul.agent-url The URL of the Consul agent to connect to (in a standard setup, on the same machine as the Corus instance (defaults to: http://localhost:8500).
corus.server.pub.consul.interval The interval at which the Corus instance republishes its service definition to Consul (defaults to 30 seconds).
corus.server.pub.consul.ttl The time-to-live assigned to the service definition (defaults to 45 seconds). That value should be greater than the publication interval (set by the above property).