TechLibrary

Table of Contents

Guide That Contains This Content

[+] Expand All

[-] Collapse All

Configuring Discovery Service

Contrail Discovery Service enables you to publish services, subscribe to a service, determine the state of a service, and maintain registered clients for each service. The Contrail Discovery Service function also notifies changes in a service, maintains internal databases, and debugs issues with a service.

Getting Started with Contrail Discovery Service

The following ports are used by the discovery service:

API port: 5998 TCP
Hearbeat port: 5998 TCP

Connect to http://discovery-server-ip:5998/services to display publishers.

Connect to http://discovery-server-ip:5998/clients to display subscribers.

The Contrail Discovery Service uses the configuration file defined in /etc/contrail/discovery.conf and log file defined in /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 status indicates whether a service is up or down based on the heartbeat messages the discovery server receives from the service publishers. If the discovery server does not receive three successive heartbeats within the default interval of five seconds, the service is marked down. When a service is marked down, the subscribers are notified and a backup discovery service session is started for the service type depending on the policy configured.

The discovery server currently supports the following polices:

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) publisher 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 that need 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 automatically assigned a new service instance. 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 por

Discovery Service REST API

A REST API is available for registering and publishing the Contrail Discovery Server.

The following values are defined in the Contrail Discovery 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)

Note: A service that is marked down is not assigned to subscribers and is stored in the discovery service internal database. You can remove a service from the /service/<id> directory by using the DELETE HTTP API command.

The following example shows the REST API for registering and publishing the discovery 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 Discovery Server.

The following values are defined in the Contrail Discovery 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 discovery 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 request to publish API. The cookie 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

Connect to the http://discovery-server-ip:5998/services to see a list of discovery service publishers.

Connect to the http://discovery-server-ip:5998/clients to see a list of discovery service subscribers.

To see the log messages for the Discovery Service, display the /var/log/contrail/discovery.log file.