Capability Advertisement Messages

Capability Advertisement Messages These sections describe schema definitions for the Capability Advertisement messages. Capability Advertisement Schema, page 1 Components of CCDL, page 2 Schema Definition, page 2 CCDL Defined Types, page 2 Resource Capability, page 3 UML, page 4 XML Advertisement, page 4 XMPP Flow, page 5 XML Example for NPS, page 7 Capability Advertisement Schema The policy agents running in each data center are responsible for creating and updating capability advertisements. These advertisements include identifying information about the element along with associated resources and capabilities that help NPS to determine whether this data center can satisfy a vdc placement request. Capability advertisement messages conform to an abstract schema called the Cloud Capability Definition Language (CCDL). The CCDL provides a meta-data specification to define and advertise device capabilities. The schema definition consists of the following: Language tokens Semantics (grammar) The language of choice for CCDL schemas is XSD. The capability advertisement messages are XML document that conform to XSD. OL-25856-02 1

Components of CCDL Capability Advertisement Messages Components of CCDL Schema Definition CCDL Defined Types Device Role CCDL provides a language schema that defines resource capability for a variety of resources (load balancers, firewalls, aggregation and access switches, and computing resources) and provides powerful language constructs to support new types of resources. Resource capabilities include functional (for example, predictor algorithms) and performance capabilities (for example, throughput, CPU, and memory). CCDL provides metadata to describe resource capabilities and the set of operations (options, normalization factors, units etc). XSD provides a formal schema definition that describes the structure of an XML document. The Capability Directory receives incoming XML documents that rely on the XSD files for validation. CCDL defines a set of types that describe the attributes of an element as well as the types to describe a capability in ccn_ccdl.xsd. These attributes are broken into device-role, units, and keys. The role of an element identifies its functionality in the POD and DC domain. The allowed role definitions are as follows: <xs:simpletype name="device-role"> <xs:restriction base="string"> <xs:enumeration value="networknode"/> <xs:enumeration value="servicenode"/> <xs:enumeration value="computenode"/> <xs:enumeration value="storagenode"/> </xs:simpletype> The device role is specified as an attribute in the XML advertisement as shown in the XML Example for NPS. Units For numeric data types, optional units can be specified that represent the standard of measurement of the capability value. If a capability does not advertise its units, then it is assumed that the value has been normalized. The language allows the following types of units: <xs:simpletype name="units"> <xs:restriction base="xs:string"> <xs:enumeration value="kb"/> <xs:enumeration value="mb"/> <xs:enumeration value="gb"/> <xs:enumeration value="tb"/> <xs:enumeration value="pb"/> <xs:enumeration value="kbps"/> <xs:enumeration value="mbps"/> <xs:enumeration value="ps"/> 2 OL-25856-02

Capability Advertisement Messages Keys </xs:simpletype> Keys For capabilities that are lists of values, the resource capability or hierarchical capability is repeated multiple times. The Capability Directory needs a way to identify unique elements of the list. A key element provides the name of a resource capability that contains the key or the identifying value for each list element. <xs:element name="key"> <xs:restriction base="resource-capability"> <xs:element name="value" type="string"/> Resource Capability CCDL provides a base from where all resource capabilities are derived. The CCN-defined resource-capability in ccn_ccdl.xsd encapsulates the components of a resource capability and the predefined types. The resource-capability type consists of the following fields: value, units, normalization, and delete. These fields correspond to the following CCDL types: type, units, and normalization. In NPS, the value of the summarization field is union. The normalization field indicates to the Capability Directory how the value should be normalized if applicable. This is not important for CCN-NPS solution, and may be safely ignored. All capabilities need to be derived from the resource-capability type to ensure that the Capability Directory can parse the incoming advertisement and is unaware of any other tags within a resource capability. The value element can appear one or more times (appearing more than once supports a set or enumeration of values) for singular values, such as a capacity, only one value should be specified in order to avoid confusion. The units element is optional and if not present, you can assume that the value has been normalized or that no unit is required. The delete flag is used in incremental updates when a capability is no longer advertised by the policy agent. <xs:complextype name="resource-capability"> <xs:element name="value" type="type" maxoccurs="unbounded"/> <xs:element name="units" type="units" minoccurs="0"/> <xs:element name="summarization" type="summarization" minoccurs="0"/> <xs:element ref="normalization" minoccurs="0"/> <xs:element name="delete" type="boolean" default="false" minoccurs="0"/> Advertising a new capability requires that the capability is derived from the resource-capability and that the appropriate restrictions are placed on the element. The following is an example of deriving a new capability called throughput from the resource-capability, where the value field is restricted to be of the type integer, and the units are defaulted to MBPS if no other unit is provided. <xs:element name="throughput"> <xs:restriction base="ccn-resource-capability"> OL-25856-02 3

UML Capability Advertisement Messages <xs:element name="value" type="xs:int" maxoccurs="unbounded"/> <xs:element name="units" type="ccn-units" default="mbps" minoccurs="0"/> <xs:element name="summarize" minoccurs="0"> <xs:simpletype> <xs:restriction base="ccn-summarize"> <xs:enumeration value="maximize"/> <xs:enumeration value="aggregate"/> </xs:simpletype> The corresponding advertisement for the above resource capability take this form (with the values being populated by the CPA): <throughput> <value>2048</value> <units>mbps</units> <summarize>maximize</summarize> </throughput> UML The Unified Modeling Language (UML) model captures the abstract capabilities model. Ensure that model descriptions from devices conform to this model hierarchy. Devices can build up their capability advertisement hierarchically by using language constructs. The UML model imposes these restrictions on capability advertisements: The entire capability advertisement needs to be encapsulated in a valid XML document representing the capabilities of the devices. For NPS, devices can contain the certain resource-capability, tenant-service, and infrastructure. Devices can contain zero or more hierarchical capabilities. Hierarchical capabilities can contain zero or more resource capabilities and zero or more hierarchical capabilities. Hierarchical capabilities can be nested arbitrarily deep. No other classes or structures are allowed or understood by the Capability Directory. XML Advertisement The sequence number for the advertisement is specified in the XML root node as an attribute. The role of the device (NetworkNode) is also specified as an attribute. The sub-role must be dce. The deviceid tag needs to be a unique string identifying this particular service role hosted by this device. The full-update attribute is set to true indicating that this is a full update as opposed to an incremental update. The nonamespaceschemalocation attribute must be nps_dce_010001.xsd. <dce ccn_ccdl:role="networknode" ccn_ccdl:sub-role="dce" ccn_ccdl:seq="1" ccn_ccdl:deviceid="dev1" ccn_ccdl:count="1" ccn_ccdl:hostname="ccn1" ccn_ccdl:full-update="true" xmlns:ccn_ccdl="uri:ccn_ccdl" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" 4 OL-25856-02

Capability Advertisement Messages XMPP Flow xsi:nonamespaceschemalocation="nps_cd_dce_010001.xsd"> <dce> <tenant_service> <value>gold</value> <value>silver</value> <value>bronze</value> <summarization>union</summarization> </tenant_service> <infrastructure> <dc_id> <value>dc1</value> <summarization>union</summarization> </dc_id> <pe_list> <value>198.51.100.2</value> <value>198.51.100.3</value> <value>198.51.100.4</value> <summarization>union</summarization> </pe_list> </infrastructure> </dce> XMPP Flow This section describes the XMPP message flow required by a control point agent (CPA) to initialize an XMPP connection and to publish a capability advertisement to the Capabilities Directory. Note A bare Jabber ID (JID) consists of the username and domain (username@domain) without the resource. 1 CPA opens a long-lived TCP connection to the XMPP server. 2 CPA opens an XMPP stream to the XMPP server by sending a stream header (known as the initial stream header): <?xml version='1.0'?> <stream:stream from='cpa-bare-jid' to='xmpp-server' version='1.0' xml:lang='en' xmlns='jabber:client' xmlns:stream='http://etherx.jabber.org/streams'> 3 The XMPP server replies by sending a stream header of its own (known as the response stream header): <?xml version='1.0'?> <stream:stream from='xmpp-server' id='++tr84sm6a3hnt3q065snabbk3y=' to='cpa-bare-jid' version='1.0' xml:lang='en' xmlns='jabber:client' xmlns:stream='http://etherx.jabber.org/streams'> 4 CPA requests to authenticate with the XMPP server. <iq type="get" id="auth1"> <query xmlns="jabber:iq:auth"/> 5 XMPP server responds by requesting authentication fields: <iq id='auth1' type='result'> OL-25856-02 5

XMPP Flow Capability Advertisement Messages <query xmlns='jabber:iq:auth'> <username/> <password/> <digest/> <resource/> </query> 6 CPA provides the required information: <iq id='auth2' type='set'> <query xmlns='jabber:iq:auth'> <username>cpa-username</username> <digest>e0193405926e1388fdc1bd00e7008dd8bcd7f4ea</digest> <resource>cpa-resource</resource> </query> 7 XMPP server informs client of successful authentication: <iq id='auth2' type='result'/> 8 CPA sends initial presence: <presence/> 9 After the CPA connects to the XMPP server and sends out its initial presence notification, it must accept and participate in a roster subscription request (initiated by Capabilities Directory) at any time moving forward. The subscription request is a four-way roster handshake agreement where each party includes one another in their rosters. The Capabilities Directory (CD) sends the initial subscribe request: <presence from="cd-full-jid" to="cpa-bare-jid" type="subscribe"/> The CPA must accept the CD's request by sending: <presence from=" CPA-Full-JID " to="cd-bare-jid" type="subscribed"/> The CPA must send its own subscription request to CD: <presence from=" CPA-Full-JID " to="cd-bare-jid" type="subscribe"/> The CD must accept the CPA's request by sending: <presence from="cd-full-jid" to=" CPA-Bare-JID " type="subscribed"/> The CD and CPA are automatically notified of the other's availability on status changes. 10 The CPA must join the multi-user chat (MUC). As described in the XMPP Pub-Sub Interface section, CPAs must join a specific MUC (PEP-node@conference.domain). There is not a restriction on whether the CD or a CPA must be the first to join an MUC, therefore, each party attempts to create the chat room in the event that it does not exist yet. Note The PEP-node must be the node to which the CD is subscribing. The domain must be the XMPP domain with which the CD and the CPAs are participating. <iq type="set" to="pep-node@conference.domain"> <query xmlns="http://jabber.org/protocol/muc#owner"> <x type="submit" xmlns="jabber:x:data"> <field var="form_type" type="hidden"> <value>http://jabber.org/protocol/muc#roomconfig</value> <field var="muc#roomconfig_openmembership"> 6 OL-25856-02

Capability Advertisement Messages XML Example for NPS <value>true</value> <field var="muc#roomconfig_membership"> <value>false</value> <field var="http://protocols.cisco.com/jodc/anonymous"> <value>false</value> <field var="http://protocols.cisco.com/jodc/show-unavailable"> <value>false</value> <field var="http://protocols.cisco.com/jodc/password"> <value>false</value> <field var="muc#roomconfig_moderatedroom"> <value>true</value> <field var="http://www.jabber.com/schemas/muc#persistent"> <value>true</value> </x> </query> 11 The CPA must send presence to the chat room: <presence to="pep-node@conference.domain/cpa-full-jid"/> 12 The CPA completes the initialization portion and can subsequently publish capability advertisements: <iq type="set"> <pubsub xmlns="http://jabber.org/protocol/pubsub"> <publish node="http://jabber.org/protocol/pep-node"> <item> <PEP-node xmlns="http://jabber.org/protocol/pep-node"> <!-capability advertisement conforming to CCDL --> </PEP-node> </item> </publish> </pubsub> XML Example for NPS An example of a valid XML capability advertisement for a complete data center in CCN-NPS is shown, along with its associated schema. <?xml version="1.0" encoding="utf-8"?> <xs:import namespace="uri:ccn_ccdl" schemalocation="ccn_ccdl.xsd"/> <xs:element name="dce"> <!-- Cloud Element role type is DCE --> <xs:element name="tenant_service"> <!-- The <tenant_service> element can be extended by another schema --> <xs:restriction base="ccn_ccdl:resource-capability"> <!-- The value contains the service model string which is --> <!-- application driven --> <xs:element name="value" type="ccn_ccdl:string" maxoccurs="unbounded"/> <xs:element name="summarization" type="ccn_ccdl:summarization" fixed="union"/> <xs:element name="delete" type="ccn_ccdl:boolean" default="false" minoccurs="0"/> OL-25856-02 7

XML Example for NPS Capability Advertisement Messages <xs:element name="infrastructure"> <!--Cloud Element external network topology info --> <xs:element name="dc_id"> <!--DC ID which is the global unique Data Center ID --> <xs:restriction base="ccn_ccdl:resource-capability"> <!-- value contains the dce ID --> <xs:element name="value" type="ccn_ccdl:string"/> <xs:element name="summarization" type="ccn_ccdl:summarization" maxoccurs="1"/> <xs:element name="delete" type="ccn_ccdl:boolean" default="false" minoccurs="0"/> <xs:element name="pe_list" minoccurs="0"> <!-- DCE facing PE list --> <xs:restriction base="ccn_ccdl:resource-capability"> <!-- value contains the IP address string --> <xs:element name="value" type="ccn_ccdl:ipv4-address-type" maxoccurs="unbounded"/> <xs:element name="summarization" type="ccn_ccdl:summarization" fixed="union"/> <xs:element name="delete" type="ccn_ccdl:boolean" default="false" minoccurs="0"/> <xs:attribute ref="ccn_ccdl:full-update" use="required"/> <xs:attribute ref="ccn_ccdl:seq" use="required"/> <xs:attribute ref="ccn_ccdl:deviceid" use="required"/> <xs:attribute ref="ccn_ccdl:role" use="required"/> <xs:attribute ref="ccn_ccdl:type" use="optional"/> <xs:attribute ref="ccn_ccdl:sub-role" use="optional"/> <xs:attribute ref="ccn_ccdl:count" use="required"/> <xs:attribute ref="ccn_ccdl:hostname" use="required"/> </xs:schema> 8 OL-25856-02