7. Remote Administration

A control client (such as RTI Admin Console) can use this interface to remotely control Cloud Discovery Service.

Note

Cloud Discovery Service remote administration is based on the RTI Remote Administration Platform described in Remote Administration Platform. Please refer to that manual for a detailed discussion on the workings of remote administration in Cloud Discovery Service.

Below you will find an API reference for all the supported operations.

7.1. Enabling Remote Administration

By default, remote administration is disabled in Cloud Discovery Service.

To enable remote administration you can use the <administration> XML tag (see Administration) or the -remoteAdministrationDomainId command-line parameter (see Command-Line Options). Both of these methods enable remote administration and set the domain ID for remote communication.

7.2. Available Service Resources

Table 7.1 lists the public resources specific to Cloud Discovery Service. Each resource identifier is expressed as a hierarchical sequence of identifiers, including parent and target resources. (See Resource Identifiers for details.)

In the table below, the element (cds) refers to the name of an entity of the corresponding class as specified in the configuration in the name attribute. For example, in the following configuration:

<cloud_discovery_service name="MyCDS">...</cloud_discovery_service>

The resource identifier is:

/cloud_discovery_services/MyCDS

In the table below, the resource identifier is written as /cloud_discovery_services/(cds), where (cds) is the service name. This nomenclature is used in the table to give you an idea of the structure of the resource identifiers. For actual example resource identifier names, see the example section that follows.

Table 7.1 Resources and their identifiers in Cloud Discovery Service

Resource

Resource Identifier

Cloud Discovery Service

/cloud_discovery_services/(cds)

Database

/cloud_discovery_services/(cds)/database/[subset_info]

where [subset_info] represents a specific smaller piece of the stored discovery information. The current available subsets are:

  • locators: List of original and resolved locators for a specified participant.

7.2.1. Example

This example shows you how to address a resource of each possible resource class in Cloud Discovery Service.

Cloud Discovery Service

Entity with name “MyCDS”:

<cloud_discovery_service name="MyCDS">...</cloud_discovery_service>

Resource identifier:

/cloud_discovery_services/MyCDS

7.3. Remote API Overview

Table 7.2 Remote Interface Overview

Resource

Operation

Description

CloudDiscoveryService

DELETE /cloud_discovery_services/(cds)

Shuts down a running Cloud Discovery Service instance.

UPDATE /cloud_discovery_services/(cds)/state

Sets a Cloud Discovery Service state.

GET /cloud_discovery_services/(cds)/state

Gets a Cloud Discovery Service state.

GET /cloud_discovery_services/(cds)/database/locators

Gets the list of original and resolved locators for a concrete participant.

7.4. Cloud Discovery Service

DELETE /cloud_discovery_services/(cds)

Operation shutdown

This operation will cause Cloud Discovery Service to shutdown.

UPDATE /cloud_discovery_services/(cds)/state

Operation set_state

Sets the state of a Cloud Discovery Service object. The action is parameterized on octet_body, which could have the following values:

See Set Resource State.

Valid requested states:

  • STARTED

  • STOPPED

  • ENABLED

  • DISABLED

GET /cloud_discovery_services/(cds)/state

Operation get_state

Gets the state of a Cloud Discovery Service object. The value is contained in the reply octet_body, which could have the following values:

See Get Resource State

Valid reply states:

  • STARTED

  • STOPPED

  • Example

    To inspect the current state of an instance of Cloud Discovery Service with the name “MyCDS”:

    Request Field

    Value

    action

    GET

    resource_identifier

    /cloud_discovery_services/MyCDS/state

    Reply Field

    Value

    octet_body

    from_cdr_buffer(RTI::Service::Admin::CommandReply::octet_body)
    

    For example code refer to Example: Controlling services remotely from a Connext DDS Application.

7.5. Database

GET /cloud_discovery_services/(cds)/database/locators

Operation get_participant_locators

Gets the list of resolved and original locators for a specified participant. The result is returned in the reply’s string body as a JSON string with the following format:

{
  "locators": {
    "original":{
       "metatraffic":[
           "original_mt_locator1",
           "original_mt_locator1",
            ...
       ],
       "default":[
           "original_def_locator1",
           "original_def_locator2",
           ...
       ]
    },
    "resolved":{
       "metatraffic":[
           "resolved_mt_locator1",
           "resolved_mt_locator2",
           ...
       ],
       "default":[
           "resolved_def_locator1",
           "resolved_def_locator2",
           ...
       ]
    }
  }
}

The original locator set represent the locators contained in the participant announcement as it is received. The resolved locator set represent the locators Cloud Discovery Service updates or extend to contain additional information necessary for the peer participants. This is for example important when using the |RTI_RWT|.

The participant is provided in the string body as the string representation of the GUID with format:

0x0101C372,0x17D4CED6,0xEA7B3DA5:0x000001C1
  • Example

    To locator information for a specific participant existing in the database of a Cloud Discovery Service instance with the name “MyCDS”:

    Request Field

    Value

    action

    GET

    resource_identifier

    /cloud_discovery_services/MyCDS/database/locators

    string_body

    0x0101C372,0x17D4CED6,0xEA7B3DA5:0x000001C1
    

    Reply Field

    Value

    string_body

    {
      "locators": {
         "original":{
            "metatraffic":[
                "udpv4_wan://f=1,u={BD,73,FC,9E,D5,00,AB,6D,40},P=10.0.2.15:0:32410"
            ],
            "default":[
                "udpv4_wan://f=1,u={BD,73,FC,9E,D5,00,AB,6D,40},P=10.0.2.15:0:32411"
            ]
        },
        "resolved":{
            "metatraffic":[
                "udpv4_wan://f=7,u={BD,73,FC,9E,D5,00,AB,6D,40},P=188.78.49.211:56532:32410"
            ],
            "default":[
                "udpv4_wan://f=7,u={BD,73,FC,9E,D5,00,AB,6D,40},P=188.78.49.211:56532:32410"
            ]
        }
      }
    }