Skip to content

Model

Formal Model - Infrastructure As A Graph

The formal model specification can be found on GitHub under Infrastructure organization. The model has been defined as a protobuf message because Protocol Buffers provide a highly efficient, compact, and language-neutral way to serialize structured data. This binary serialization format results in significantly smaller message sizes compared to text-based formats like JSON or YAML, which reduces network bandwidth usage and storage requirements

Building Blocks

The infra.proto provides multiple building blocks to define the infrastructure. These blocks include:

  • Inventory
  • Device
  • Components
  • Links
  • Device Instances
  • Connections

Devices

message Device {
  optional string name = 1;
  map<string, Component> components = 3;
  map<string, Link> links = 4;
  repeated string connections = 5;
}

The Device message specifies a device that is part of the infrastructure. It includes a set of components, the links between those components, and their connections. The primary fields are: * name: An optional field for defining the device's name. * components: An optional field for defining the device's name. * links: A dictionary that holds link messages, each keyed by the link name. * connections: A list describing how components within a single device are connected. Each entry is a string formatted as follows: 

source_component_name "." source_component_index "." link_name "." destination_component_name "." destination_component_index
example: 
nic.0.pcie.cpu.0
npu.0.pcie.nvswitch.0
asic.0.mii.nic.0
The source_component_name and destination_component_name correspond to the name field in the component message and also match the keys in the components dictionary. Each component message includes a count field to specify the number of components present in the device. Further details on these fields are provided in the components section.

Components

message Component {
  optional string name = 1;
  optional uint32 count = 2;
  oneof type {
    CustomComponent custom = 10;
    Cpu cpu = 11;
    Npu npu = 12;
    Nic nic = 13;
    Switch switch = 14;
  }
}

The component message includes three main fields: * name: An optional identifier, also used as a key in the components dictionary field of the device message. * count: Specifies how many instances of the component exist. For example, a nic with count 8 creates eight identical instances, indexed from zero—similar to creating multiple objects from a class blueprint. * type: Indicates the type of component described by the data model. The type can be: * CPU * NPU * NIC * Switch * Custom

Each type is defined as a separate message. The section below explains the component type message format

CPU Component

message Cpu {
  MemoryType memory = 1;
}
This message defines the CPU type component, enabling users to assign a memory type to the CPU. MemoryType will be discussed later.

NPU Component

message Npu {
  MemoryType memory = 1;
}

This message specifies the NPU type component, enabling assignment of a particular memory type to the NPU. Details regarding MemoryType are provided in a subsequent section.

Custom Component

message CustomComponent {
  MemoryType memory = 1;
}

This message specifies the CustomComponent type component. It enables the user to assign a particular memory type to the Custom Component. The MemoryType will be discussed in a subsequent section.

Memory Type

enum MemoryType {
  MEM_UNSPECIFIED = 0;

  // random access memory
  MEM_RAM = 1;

  // high bandwidth memory interface for 3D stacked sync dynamic random-access memory
  MEM_HBM = 2;

  // memory that uses compute express link interconnect to the cpu
  MEM_CXL = 3;
}
The user may assign the memory type to the CPU, NPU, or a CustomComponent. Available memory types include: * Unspecified * Random Access Memory * High Bandwidth Memory Interface * Compute Express Link The enumeration can be expanded to accommodate additional memory types for use by custom components.

NIC Component

message Nic {
  oneof type {
    Ethernet ethernet = 10;
    Infiniband infinband = 11;
  }
}

message Infiniband {
}

message Ethernet {
}

This describes the NIC Component. Each nic component can be of the following type: * Ethernet * Infiniband These types are defined as a message.

Switch Component

message Switch {
  oneof type {
    Pcie pcie = 1;
    NvLink nvswitch = 2;
    Custom custom = 3;
  }
}

message Pcie {
}

message NvLink {
}

message Custom {
}

This section defines the Switch Component type, which can be one of: * pcie * nvlink * custom These types are specified as a message.

message Link {
  optional string name = 1;
  optional string description = 2;
  Bandwidth bandwidth = 10;
}

message Bandwidth {
  oneof type {
    uint32 gbps = 1;
    uint32 gBs = 2;
    uint32 gts = 3;
  }
}

The Link message defines a connection between a device and its components using three fields: * name * description * bandwidth

Bandwidth is specified as a message with these options: * gbps (gigabits per second) * gBs (gigabytes per second) * gts (giga transfers per second) Each takes an unsigned integer. Links use the Bandwidth model to state link speed.

Inventory

message Inventory {
  map<string, Device> devices = 1;
  map<string, Link> links = 2;
}

Inventory lists all unique Device and Link types in the infrastructure: * devices: Unique device types based on Device.name. * links: Unique link types identified by Link.name, which can be reused for connecting devices and prevents duplicates.

Device Instances

message DeviceInstances {
  optional string name = 1;
  optional string device = 2;
  optional uint32 count = 3;
}
The Device Instances message instantiates devices in the infrastructure and includes three fields: * name: Identifies and categorizes each device instance (e.g., Rack Switch, POD Switch). This ensures unique naming for device groups. * device: References the actual device from the inventory - devices list to link the intended hardware. * count: Specifies how many instances of this device are needed under the given name (minimum 1), starting with an index of 0 for unique identification.

Infrastructure

message Infrastructure {
  Inventory inventory = 1;
  map<string, DeviceInstances> device_instances = 2;
  repeated string connections = 3;
}

The Infrastructure message records an inventory of devices and links, their instances, connectivity, and optional user data about devices, components, links, and instances. It maintains the inventory, device_instances map, and a list of connections. Each connection is formatted as a string with elements separated by “.“

source_device_instance_name
source_device_index 
source_device_component_name
source_device_component_index
link_name
destination_device_instance_name
destination_device_index
destination_device_component_name
destination_device_component_index

This uses the device instances naming convention with a count, which internally references the device message that specifies the component, its name, and the count. It also connects two separate device instances using the link name defined in the inventory.

Building Infrastructure

The model represents devices and their internal components as nodes, with links as edges to form a graph. For step-by-step infrastructure setup, see Building A Cluster.