External References for RSpecs

The purpose of external references is to allow CMs to describe their connections to other CMs and the Internet in advertisements. External references are therefore only in advertisements and not in other kinds of RSpecs.

There are two kinds of ways that CMs might be connected. They may be connected directly through a backbone which has guaranteed bandwidth. Otherwise, they will be connected through one or more third parties which are not part of the GENI infrastructure. These include the Internet, Internet 2, campus networks, etc.

Each node is managed by a single CM which provides an authoritative advertisement for that node. Links between nodes are managed by all CMs incident upon them (clouds are an exception, see below). When a link is within a CM, then that CM alone manages it. If the link connects multiple CMs, then each of those CMs will contain that link in their advertisements and those advertisements should agree on both the name and the link characteristics.

Currently, external references are used to represent interfaces, not nodes or links. External references must be declared in the top level with an 'external_ref' tag. RSpecs may not contain external references to any component which is also defined in that RSpec. These external references may then be referenced in interface tags in links in exactly the same way that other interfaces are:

<rspec type="advertisement"
       xmlns="http://www.protogeni.net/resources/rspec/0.1">
  <external_ref component_node_uuid="urn:node+internet"
                component_interface_id="interface"
                component_manager_uuid="urn:authority+internet" />
  <node component_uuid="urn:node+node-1"
        component_manager_uuid="urn:authority+cm"
        virtualization_type="emulab-vnode">
    <node_type type_name="pc" type_slots="1" />
    <interface component_id="control"/>
  </node>
  <link component_manager_uuid="urn:authority+cm"
        component_name="link-5"
        component_uuid="urn:link+link-5" >
    <interface_ref component_node_uuid="urn:node+node-1"
                   component_interface_id="control"/>
    <interface_ref component_node_uuid="urn:node+internet"
                   component_interface_id="interface"/>
  </link>
</rspec>

The 'component_node_uuid' and 'component_interface_id' attributes will be merged into a 'component_id' tag when length limits on URNs are removed.

When combining rspecs, external references must be removed if one of the two rspecs contains the component in question. Consistency must be checked and maintained between the advertisements. If a CM A has a link to an interface in CM B, then CM B must have an identical link to the corresponding interface in CM A.

There is one exception to the normal rules requiring consistency. Nodes may be marked with a '<cloud>' tag:

<rspec type="advertisement"
       xmlns="http://www.protogeni.net/resources/rspec/0.1">
  <node component_uuid="urn:node+internet"
        component_manager_uuid="urn:authority+internet"
        virtualization_type="emulab-vnode">
    <node_type type_name="internet" type_slots="1" />
    <interface component_id="interface"/>
    <cloud />
  </node>
</rspec>

In this case, that node represents an entire network (such as the commodity Internet) with just one interface. Any other CM may make an external reference to that interface, but the CM which contains that node does not need to maintain a corresponding link back to other CMs. In addition, any number of links may connect to the same interface.

In general, there will be a single well known CM (probably at Utah) which provides the canonical 'Internet' or 'Internet 2' nodes which will be referenced by other CMs to indicate connectivity.

The combination of the above two rspecs would yield the following advertisement:

<rspec type="advertisement"
       xmlns="http://www.protogeni.net/resources/rspec/0.1">
  <node component_uuid="urn:node+internet"
        component_manager_uuid="urn:authority+internet"
        virtualization_type="emulab-vnode">
    <node_type type_name="internet" type_slots="1" />
    <interface component_id="interface"/>
    <cloud />
  </node>
  <node component_uuid="urn:node+node-1"
        component_manager_uuid="urn:authority+cm"
        virtualization_type="emulab-vnode">
    <node_type type_name="pc" type_slots="1" />
    <interface component_id="control"/>
  </node>
  <link component_manager_uuid="urn:authority+cm"
        component_name="link-5"
        component_uuid="urn:link+link-5" >
    <interface_ref component_node_uuid="urn:node+node-1"
                   component_interface_id="control"/>
    <interface_ref component_node_uuid="urn:node+internet"
                   component_interface_id="interface"/>
  </link>
</rspec>