[[TOC(Software/eAM/aI*, depth=3)]]


== Inventory Aggregate Manager ==


Inventory AM consist of a database with a [http://mytestbed.net/projects/omf/wiki/NewInventoryDesign database schema] that can hold information for arbitrary type of resource and a set of services that are used to manage it


=== Resources and Relationships ===

Resources are physical entities in a testbed that are assumed to be named with fully qualified domain name (fqdn) (for resources that can have one) or with arbitrary string (for resources that are not IP addressable)and can have any number of attributes. Resource can be in relation with any other resource with, so far, 2 types of relationships:

 ||= Type =||= Relationship =||= Description =||
 || 1 || belong_to    || The subject resource belongs to the object resource   ||
 || 2 || installed_in || The subject resource is installed in the object resource ||

Typically, type 1 is used to designate that the node belongs to a testbed, and type 2 for devices that are installed into a node (at the moment type of relationship is not used for any particular function by the inventory).

To facilitate better classification, inventory services are using string based '''resource type'''. So far, defined resources types are: testbed, node and device (these types are only used by other services).

''' Attributes '''

Attributes are name-value pairs of strings. Attribute names are prefixed to support globbing.

Attribute prefixes:

 * CM_ - Attributes used by the CMC AM ( CM_TYPE, CM_IP, CM_PORT, CM_USER_NAME, CM_PASSWORD )
 * INF_ - Core infrastructure attributes used by the PXE and Frisbee service ( INF_CONTROL_IP )
 * INV_ - Attributes gathered by the inventory process 



=== Inventory Service Group ===

{{{
<services>
  <serviceGroup prefix="/inventory" name="inventory">
    <info></info>
    <service name="attribute_add"></service>
    <service name="attribute_delete"></service>
    <service name="attribute_list"></service>
    <service name="attribute_listChildren"></service>
    <service name="attribute_modify">
    <service name="relation_add"></service>
    <service name="resource_add"></service>
    <service name="resource_delete"></service>
    <service name="resource_list"></service>
    <service name="topology_add"></service>
    <service name="topology_delete"></service>
    <service name="topology_list"></service>
    <service name="topology_show"></service>
  </serviceGroup>
</services>
}}}

''' resource_add - Add Resource '''

{{{
<service name="resource_add">
  <info>Add resource</info>
  <args>
     <arg name="name" isRequired="true" value="name">
        <info>name of the resource or fully qualified resource name</info>
     </arg>
     <arg name="type" isRequired="true" value="type">
         <info>type of the resource</info>
     </arg>
     <arg name="xml" isRequired="false" value="[xml]">
        <info>xml-encoded hash of resource parameters</info>
     </arg>
  </args>
</service>
}}}

''' resource_delete - Delete Resource '''
This method deletes all resource attributes, but does not delete children resources.
{{{
<service name="resource_delete">
  <info>Remove set of resources</info>
  <args>
    <arg name="set" isRequired="true" value="set">
       <info>set of resource names</info>
    </arg>
  </args>
</service>
}}}

''' resource_list - List Resources '''

{{{
<service name="resource_list">
  <info>Get all available resources of given type that belongs to given parent resource with all attributes</info>
  <args>
    <arg name="parent" isRequired="false" value="[parent]">
      <info>Fully qualified resource name</info>
    </arg>
    <arg name="type" isRequired="false" value="[type]">
      <info>Type name, currently suported testbed, node and device</info>
    </arg>
  </args>
</service>
}}}

''' relation_add - Add Relationship Between Resources '''

{{{
<service name="relation_add">
  <info>Add relation between two resources</info>
  <args>
    <arg name="parent" isRequired="true" value="rn">
      <info>parent resource name</info>
    </arg>
    <arg name="child" isRequired="true" value="rn">
      <info>child resource name</info>
    </arg>
  </args>
</service>
}}}

''' attribute_add - Add an attribute '''

{{{
<service name="attribute_add">
  <info>Add attribute to resource</info>
  <args>
    <arg name="name" value="name" isRequired="true">
      <info>Resource name</info>
    </arg>
    <arg name="attribute" value="attribute" isRequired="true">
      <info>Name of attribute</info>
    </arg>
    <arg name="value" value="value" isRequired="true">
      <info>Value of attribute </info>
    </arg>
  </args>
</service>
}}}

''' attribute_delete - Delete an attribute '''

{{{
<service name="attribute_delete">
  <info>Delete all attributes matching attribute pattern for all nodes matching node name pattern (rn)</info>
  <args>
    <arg name="name" value="[name]" isRequired="false">
      <info>Resource name or resource name pattern</info>
    </arg>
    <arg name="attribute" value="attribute" isRequired="true">
      <info>Attribute pattern</info>
    </arg>
  </args>
</service>
}}}

''' attribute_modify - Modify an attribute value '''

{{{
<service name="attribute_modify">
  <info>Modify attribute's value</info>
  <args>
    <arg name="name" value="name" isRequired="true">
      <info>Resource name</info>
    </arg>
    <arg name="attribute" value="attribute" isRequired="true">
      <info>Attribute name</info>
    </arg>
    <arg name="value" value="value" isRequired="true">
      <info>New value of attribute </info>
    </arg>
  </args>
</service>
}}}

''' attribute_list - List attributes '''

{{{
<service name="attribute_list">
  <info>Get node with names matching name pattern with attributes matching attribute name pattern and value matching attribute value pattern</info>
  <args>
    <arg name="set" value="[set]" isRequired="false">
      <info>Set of resource names or resource name pattern</info>
    </arg>
    <arg name="attribute" value="[attribute]" isRequired="false">
      <info>Attribute name pattern</info>
    </arg>
    <arg name="value" value="[value]" isRequired="false">
      <info>Attribute value pattern</info>
    </arg>
  </args>
</service>
}}}

''' attribute_listChildren - List attributes of children '''

{{{
<service name="attribute_listChildren">
  <info>Get node with names matching name pattern with child (device) attributes matching attribute name pattern and value matching attribute value pattern</info>
  <args> 
    <arg name="set" value="[set]" isRequired="false">
       <info>Set of resource names or resource name pattern</info>
    </arg>
    <arg name="attribute" value="[attribute]" isRequired="false">
      <info>Child attribute name pattern</info>
    </arg>
    <arg name="value" value="[value]" isRequired="false">
      <info>Child attribute value pattern</info>
    </arg>
  </args>
</service>
}}}


=== Usage Examples ===

''' Create testbed, add node to it and add basic attributes '''

{{{
# Define the testbed
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/resource_add?name=sb10.orbit-lab.org&type=testbed'
# Add a node
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/resource_add?name=node1-1.sb10.orbit-lab.org&type=node'
# Create the parent/child relationship between the testbed and the node
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/relation_add?parent=sb10.orbit-lab.org&child=node1-1.sb10.orbit-lab.org'
# Add basic attributes
# CM is CM3 (mandatory)
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/attribute_add?name=node1-1.sb10.orbit-lab.org&attribute=CM_type&value=3'
# IP Address for this CM (mandatory)
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/attribute_add?name=node1-1.sb10.orbit-lab.org&attribute=CM_ip&value=10.22.1.1'
# IP Port for this CM (mandatory)
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/attribute_add?name=node1-1.sb10.orbit-lab.org&attribute=CM_port&value=1'
# Disk from the node boots (for imaging)
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/attribute_add?name=node1-1.sb10.orbit-lab.org&attribute=INF_default_disk&value=/dev/sda'
  ...
}}}


''' Replace inventory information '''

{{{
# First, delete all devices that belong to the node
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/resource_delete?set=node1-1.sb10.orbit-lab.org-*'
# Then delete all node level attributes collected by the inventory process
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/attribute_delete?name=node1-1.sb10.orbit-lab.org&attribute=INV_*'
# Add node level attribute
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/attribute_add?name=node1-1.sb10.orbit-lab.org&attribute=INV_MB_ID&value=i7'
# Add first device named "node1-1.sb10.orbit-lab.org-e0" (and add it to the node)
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/resource_add?name=node1-1.sb10.orbit-lab.org-e0&type=device'
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/relation_add?parent=node1-1.sb10.orbit-lab.org&child=node1-1.sb10.orbit-lab.org-e0'
# Add attributes for the new device
  wget -qO- 'http://new.orbit-lab.org:5054/inventory/attribute_add?name=node1-1.sb10.orbit-lab.org-e0&attribute=INV_MAC_0&value=00:01:02:03:04:05'
}}}

=== Installation and Configuration ===

The Frisbee AM (tools and services) is packaged in the omf-aggmgr-frisbee-5.4 package. It can be installed form the package repository with

{{{
apt-get install omf-aggmgr-inventory-5.4
}}}

Instructions on how to add the Orbit software repository to your list of apt-sources can be found [wiki:Documentation/kPackages#UsingtheOribtPackageRepository ​here].

Once installed the service is configured by TODO.