3. Core Concepts

This section aims to provide a deeper understanding of what Cloud Discovery Service is made of, to give you the required insight to configure and use it effectively.

You will learn about:

  • Domain lists—Sets the context for Cloud Discovery Service in DDS domains.
  • Transport: Shows how the transports are modeled in Cloud Discovery Service, which is the basis for communication with DomainParticipants.
  • Forwarder: Explains the active logic of Cloud Discovery Service that is in charge of processing the participant announcements, building the system discovery state, and providing the information to all DomainParticipants.
  • Database: Describes the collection of discovered DomainParticipant
    information that Cloud Discovery Service maintains to represent the current state of the system.

3.1. Domain Lists

A single Cloud Discovery Service can forward participant announcements in multiple DDS domains. Yet Cloud Discovery Service preserves the isolation of DDS domain IDs such that a DomainParticipant only discovers other DomainParticipants with the same DDS domain ID.

Cloud Discovery Service works with Multiple Domains

Figure 3.1 Cloud Discovery Service works with Multiple Domains

By providing a domain list, you can control on which domains Cloud Discovery Service operates. A domain list is a representation of domains by their IDs. You can learn more about configuring domain lists in Section 5.5.2.

Support for multiple domain IDs can simplify system deployments, allowing a few Cloud Discovery Service instances to provide discovery services for all possible expected domain IDs, even if all these domain IDs are not known in advance.

3.1.1. Domain Tags

In large-scale systems or multi-tenant networks, such as those found in Cloud deployments, the isolation provided by the DDS domain ID may not be sufficient:

  • The maximum number of domain IDs is limited and not sufficiently large. In deployments that require many independent DDS systems in a common network, the domain ID would not be sufficient to provide isolation.
  • Managing the assignment of numeric domain IDs to independent systems or projects can be cumbersome. Numeric IDs cannot easily leverage existing organizational or project boundaries such as project name, department, organization, etc.

For these reasons, the DDS domain concept has been extended to include Domain Tags.

A domain tag is a logical sub-division within a domain. It is defined as a string. DomainParticipants associated to different domain tags will not discover each other even if they are in the same domain ID. You can think of a Domain Tag as the DDS equivalent of a network VLAN.

Figure 3.2 shows an overview of the domain tag concept.

Domain Tags

Figure 3.2 Domain Tags

A DomainParticipant can be associated with only one domain tag. In a given domain, all the DomainParticipants may exchange participant announcements in order to initiate the discovery process between them. However, only DomainParticipants that have the same domain tag will discover each other.

Domain tags allow you to divide your domain into as many logically isolated spaces as you need. A domain tag is represented by a string tag name. You can define as many tags as you need. The tag name may include any ASCII character.

Note

The absence of a domain tag is treated like a special value of the tag. DomainParticipants that do not specify a domain tag will communicate only with each other.

Characteristics of domain tags:

  • Single Tag per DomainParticipant: A DomainParticipant can be associated with a single domain tag.
  • Immutability: Domain tags are immutable. DomainParticipants specify the domain tag at creation time and it cannot be modified.

Cloud Discovery Service understands domain tags and forwards discovery information only to DomainParticipants with matching domain ID and domain tag. Figure 3.3 shows the domain tags’ effect when Cloud Discovery Service drives the discovery process.

|CDS| with Domain Tags

Figure 3.3 Cloud Discovery Service with Domain Tags

Cloud Discovery Service detects the domain tag of each DomainParticipant and remembers that association. That way it can forward the participant announcements only to those DomainParticipants that belong to the same domain ID and tag.

Note

The functionality of Domain Tags is currently only available if discovery occurs through Cloud Discovery Service. If discovery occurs directly between DomainParticipants, domain tags will be ignored.

You can specify the domain tag for a DomainParticipant at creation time via DomainParticipantQos. In particular, you need to propagate the well-known property dds.domain_participant.domain_tag, whose value contains the name of the tag associated with the DomainParticipant. You can specify this property through the PropertyQosPolicy.

3.1.1.1. Specifying the Domain Tag in XML

The following XML snippet shows how to specify the domain tag within DomainParticipantQos.

<participant_qos>
    <property>
        <element>
            <name>dds.domain_participant.domain_tag</name>
            <value>TagX</value>
            <propagate>true</propagate>
        </element>
    </property>
</participant_qos>

3.2. Transport

Cloud Discovery Service allows you to select which transports to use to send and receive discovery traffic. The selection of transports defines the possible locations where the service can be reached. DomainParticipants require this information to communicate with the service.

In a Connext DDS application, DomainParticipants automatically configure the underlying transport ports based on the domain ID and the network capabilities of the host machine where the application runs. In Cloud Discovery Service, this configuration is manual and explicit.

Note

Cloud Discovery Service only works with unicast transports. In this manual, any reference to the transport will always imply unicast.

In particular, Cloud Discovery Service allows you to choose:

  • Transport class instance: A transport class is a concrete realization of a networking transport (e.g., UDP, TCP, etc.). You can instantiate this class and uniquely identify it with a transport alias. In addition, for each instantiation you can configure properties specific to the implementation (e.g., network interfaces, receive buffer sizes, etc.).
  • Transport Address: A transport address represents an interface for a specific transport class (for example, an IP address for the UDP or TCP transport).
  • Receive Port: Identifies where the service listens for incoming data. For more information about ports, see Section 3.2.2.

Each transport instance-address tuple constitutes a Transport Locator, which is a unique data-reception endpoint. Cloud Discovery Service creates send resources to put discovery traffic on the wire. Connext DDS uses ephemeral ports for outbound data, hence a send resource is specified by a transport instance only. Cloud Discovery Service creates a send resource for each transport instance specified.

Cloud Discovery Service relies on the same pluggable transport framework that is available for Connext DDS applications to create and access transport resources. This implies you can use not only RTI Connext DDS builtin transports, but also your own transport implementations. For more information, see transport plugins in RTI Connext DDS Users Manual.

DomainParticipants can communicate with Cloud Discovery Service as long as they are configured with the proper transport settings. Then they can reach a specific service instance in two ways:

  1. By addressing the service instance through an RTPS peer descriptor which allows you to identify a DDS service in a generic way by its locator. DomainParticipants can include these in their lists of initial peers.
  2. By addressing the service instance through a peer participant descriptor such that the resulting destination port, computed from the domain ID of the DomainParticipant and well-known ports configuration, matches the listening port of the service.

Cloud Discovery Service determines how to reach DomainParticipants based on the locator information they propagate as part of their participant announcements. Cloud Discovery Service sends discovery traffic to a DomainParticipant by sending data to each of its locators.

3.2.1. RTPS Peer Descriptor

A peer descriptor is a string representation of a set of locators for DDS DomainParticipants. It provides a compact way to indicate a list of locators where a DomainParticipant can find other DomainParticipants. This is known as a participant peer descriptor, or simply a peer descriptor.

RTI Connext DDS applications use the peer descriptor to bootstrap the participant discovery process with other DomainParticipants. Refer to discovery peer configuration in the RTI Connext DDS Core Libraries User’s Manual.

The RTPS peer descriptor is another kind of peer descriptor that allows addressing a service with which you communicate through the RTPS protocol, and that does not necessarily imply the existence of a DomainParticipant. Cloud Discovery Service is an example of such a service.

Note

The RTPS peer descriptor format is supported only by applications using RTI DDS Connext versions 5.3.0 and higher.

The RTPS peer descriptor format is shown below:

RTPS Peer Descriptor Format

Figure 3.4 RTPS Peer Descriptor Format

Table 3.1 describes all the elements in the RTPS peer descriptor.

Table 3.1 RTPS Peer Descriptor Elements
Element Description Required Default
rtps Keyword to indicate the RTPS descriptor kind. Yes  
@ Separator. Only when <locator> is specified.  
<locator> Specifies a transport and an address. See locator format. No udpv4://localhost
: Separator. Only when <port> is specified.  
<port> RTPS Peer receive port. See Section 3.2.2. No 7400

3.2.1.1. Example: RTPS Peer Descriptors

Table 3.2 RTPS Peer Descriptor for UDP/IP Version 4 Transport
rtps @ udpv4://192.169.1.1 : 7400
Table 3.3 RTPS Peer Descriptor for a Generic Starfabric Transport
rtps @ starfabric://FA::0#0/0/R    

3.2.1.2. Example: Transport Setup and Resulting RTPS Descriptor

Assume Cloud Discovery Service is configured with the following transport settings and running on host CdsHost:

<transport>
    <element>
        <alias>udpv4</alias>
        <receive_port>57410</receive_port>
    </element>
</transport>

DomainParticipants can send discovery traffic to this service by adding the following peer to their initial peer lists:

rtps@udpv4://CdsHost:57410

3.2.2. About Ports

Discovery traffic through RTPS relies on well-known ports to establish communication between peers. These ports are a logical concept that allow multiplexing communications at the middleware layer.

It is up to the underlying transport implementation to decide how to map these logical port numbers into the physical transport address scheme. For instance, the RTI builtin UDP transport directly maps the logical port number into the physical UDP port.

The port mapping is especially important in Cloud environments where UDP and TCP dominate the transport layer. The presence of these protocols often requires knowing details about the communication ports to properly set up application services.

In a DomainParticipant, unless explicitly configured, ports are determined automatically based on the domain ID and participant ID. Also, the port mapping is fully controlled by the underlying transport. In Cloud Discovery Service, the ports must be configured explicitly. Moreover, for the direct known RTI transport implementations that rely on UDP and TCP, Cloud Discovery Service maps the (logical) receive port directly to the transport physical port.

See Ports Used for Discovery to learn more about RTPS ports.

3.3. Forwarder

The forwarder is the Cloud Discovery Service component where all the discovery logic resides. Its responsibility is to build the discovery state and forward participant announcements to the peer DomainParticipants so that they can discover each other.

Figure 3.5 shows a representation of the forwarder element of Cloud Discovery Service.

Participant Announcement Forwarder

Figure 3.5 Participant Announcement Forwarder

The forwarder is composed of three main blocks:

  • Receiver: The element in charge of retrieving incoming participant announcements. This element interfaces with the receive resources, which provide the participant announcements received from all the peer DomainParticipants.

  • Announcement queues: The received participant announcements are placed in queues so they can be forwarded to their proper destinations. Participant announcements can be categorized in three classes:

    • New: Announcements from DomainParticipants that are considered new from the service perspective.
    • Update: Announcements from DomainParticipants that the service has already seen but that contain content changes relative to the previous announcement from the same DomainParticipant. For example, QoS changes in the DomainParticipant.
    • Refresh: Announcements from DomainParticipants that the service has already seen and that do not contain any content changes from the previously received announcement.

    This classification allows the forwarder to process the different categories differently, allowing you to prioritize and regulate the bandwidth used by each traffic class.

  • Flow Controller: The entity that removes announcements from the queue and forwards them to the proper destinations. The flow controller regulates the output announcement traffic. The flow controller uses the send resources to direct the announcements to the proper DomainParticipants.

3.3.1. Flow Controller

Cloud Discovery Service incorporates a configurable flow controller, which allows shaping the generated output traffic as a result of forwarding participant announcements. The parameters that configure a flow controller are:

  • Output capacity: The maximum amount of announcements forwarded in a period of time. It is measured in jobs-per-time units (e.g., announcements per second). Each received announcement represents a job to forward the announcement to all discovered DomainParticipants. This parameter allows setting an upper bound to the output traffic to avoid network congestion.
  • Maximum job burst: The maximum amount of consecutive jobs that can be forwarded in a period of time. This parameter allows setting an upper limit to the output traffic peak.
  • Flush period: The period at which the flow controller attempts to forward pending announcements.

Note

Because forwarding an announcement requires sending each announcement to multiple discovered participants, the actual output bandwidth depends on the number of participants.

3.3.1.1. Operation Mode

The flow controller generates job tokens at the rate specified by the output capacity. Forwarding an announcement takes exactly one job token. The forwarder queues announcements upon reception and attempts to forward them as soon as tokens are available.

If tokens are not available, the announcement jobs will remain in the queue in a pending state. The forwarder wakes up at every flush period to check for available tokens to forward the pending announcements.

If tokens are generated faster than jobs are received, the flow controller accumulates the tokens for future jobs. The flow controller will accumulate no more than the maximum job burst tokens.

3.4. Database

Cloud Discovery Service uses an internal database to keep information about remote entities. This is the information that represents the discovery state of the system.

This state is maintained upon reception of discovery information. Remote entries in the database are added or removed based on the received information. The database will release the resources for each removed entry as needed.

Cloud Discovery Service relies on a dedicated thread, which periodically cleans up any removed state from the database. This model enhances concurrency while maintaining thread safety.

This element is equivalent to the Database Thread of a DomainParticipant.