Configuring Discovery Service
The Contrail Discovery Service publishes the IP address and port of the multiple components of the configuration node. The system runs multiple instances of each process for high availability and load balancing purposes.
Contrail Discovery Service Introduction
The following ports are used by the discover service.
- API port : 5998 TCP
- Hearbeat port: 5998 TCP
To display the publishers, connect to the http://discovery-server-ip:5998/services URL.
To display the subscribers, connect to the http://discovery-server-ip:5998/clients URL.
The Contrail Discovery Service uses the following configuration file and log file:
/etc/contrail/discovery.conf /var/log/contrail/discovery.log
Discovery Service Registration and Publishing
The Discovery Service publishers send registration requests to the discovery server using a REST API.
The Discovery Service publishers send periodic heartbeat to the discovery server. The default interval for the heartbeat is 5 seconds.
If three successive heartbeats are missed, the Discovery Service is marked down.
The Discovery Service status is maintained internally. It indicates if the service is up or down based on the received heartbeat messages.
The discovery server currently supports three polices for selecting what information to return. The three polices are:
Load Balance | — | The service is returned based on the in-use count (how many subscribers are currently using the service). |
Round Robin | — | The service is assigned based on a timestamp. The earliest (oldest) pubisher is selected for the next assignment. |
Fixed | — | An ordered list of available servers is always sent. If a service goes offline and comes back again, that service moves to the bottom of the list. |
The three polices are configured in the /etc/contrail/discovery.cfg file under the service type section.
The response to a publish request is a cookie that must be sent back in the heartbeats.
Discovery Service Subscription
Clients needing a service, send requests to the discovery server using a REST API.
The client can specify how many instances of a service to be returned. The default is 1. If the requested number of instances is 0, the information about all of the publishers of that service type is returned. Use this to display all the providers of a particular service.
A client is identified by a token (uuid). The token is typically sent as part of a subscription request. The client information is removed from the discovery server database when the time to live. (TTL) expires
A response to a client includes a TTL value. When the TTL expires, the client refreshes the information by sending another subscription request. The TTL sent to the client is a random value in the range of 5 to 30 minutes.
If a service is overloaded and a new one is started, the new
clients are assigned a new service instance automatically. To spray
the new servers to the existing subscribers, use the discovery_cli.py file to reassign them on demand.
Clients find the discovery service by using the configured IP address and port
Discovery Service REST API
A REST API is available for registering and publishing the Contrail Discover Server.
The following values are defined in the Contrail Discover Server file:
- POST: /publish or POST /publish/<publisher-id>
- Content-Type: application/json or application/xml
- Body: information to be published (service type and data)
The following example shows the REST API for registering and publishing the discover service
JSON simple:
{
"control-node": {"ip_addr": "192.168.2.0", "port":1682 }
}
JSON verbose:
{
"service-type" : "foobar",
"foobar" : {"ip_addr": "192.168.2.0", "port":1682 }
}
XML simple:
<foobar2>
<ip-addr>1.1.1.1</ip-addr>
<port>4289</port>
</foobar2>
XML verbose:
<publish>
<foobar2>
<ip-addr>1.1.1.1</ip-addr>
<port>4289</port>
</foobar2>
<oper-state>down</oper-state>
<service-type>foobar2</service-type>
</publish>
JSON Response: {"cookie": c76716813f4b}
XML Response: <response><cookie>c76716813f4b</cookie></response>
The following fields are allowed in the body of the file:
service-type | — | Name of the service to publish |
admin-state | — | Up or down state |
remote-addr | — | IP address of the client |
remote-version | — | Version number of the client |
remote-name | — | Hostname of the client |
oper-state | — | Each published service can set the oper-state up or down based on its internal state. You can display the reason the oper-state is up or down using the port 5998 URL. |
A REST API is available for subscribing to the Contrail Discover Server.
The following values are defined in the Contrail Discover
Server discovery_cli.py file:
- POST http://discovery-server-ip:5998/subscribe
- Content-Type: application/json or application/xml
- Body: Service type, instance count, client ID
The following example shows the REST API for subscribing to the discover service.
JSON: {
"service": "control-node",
"instances": 1,
"client": "6c3f48bf-1098-46e8-8117-5cc745b45983",
"remote-addr" : '1.1.1.'
}
XML:
<control-node>
<instances>1</instances>
<client>UUID</client>
<remote-addr>1.1.1.1</remote-addr>
</control-node>
Response: TTL, List of <service type, Blob>
JSON: {
"Apiservice": [{"ip_addr": "10.84.13.34", "port": "8082"}],
"ttl": 357
}
XML:
<response>
<ttl>300</ttl>
<control-node>
<ip_addr>192.168.2.0</ip_addr>
<port>1682</port>
</control-node>
</response>
The following fields are allowed in the body of the file:
Service Type | — | This is a string denoting what service is being requested (Apiservice). The instance count is the number of servers needed. |
Client ID | — | This is a unique ID for the subscriber. Typically it is constructed from the UUID and the name of the subscriber. |
 | Note: The subscription response includes a list of the services. |
Discovery Service Heartbeats
A cookie is returned in response to a publish API request. It is sent in the heartbeat message to the discovery server. If three heartbeat messages are missed, the discovery server marks the service down and it is no longer assigned to the subscribers.
The heartbeat responses from the discovery server are either 200 Ok or 401. The 401 response is sent if the discovery server does not recognize the cookie. This could happen if the discovery server is restarted with the reset_config option. In this case the client should plan on republishing the information.
Discovery Service Internal Databases
The database is maintained in Cassandra. There is a persistent copy so that the discovery service can maintain state across restarts.
Discovery Service Client Library
Python and C++ client libraries are available that allow publishing and subscription of services.
Discovery Service Debugging
To see a list of Discovery Service publishers, connect to the http://discovery-server-ip:5998/services URL.
To see list of Discovery Service subscribers, connect to the http://discovery-server-ip:5998/clients URL.
To see the log messages for the Discovery Service, display the /var/log/contrail/discovery.log file.
