Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation
Guide That Contains This Content
[+] Expand All
[-] Collapse All

    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.

    Modified: 2015-09-10