Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


SONiC Device Profile


Devices are recognized in the Apstra environment with device profiles. They capture device-specific semantics, which are required for the Apstra software to discover them and to run network configs that work well for the datapath once inside the blueprint.

Device profiles are REST entities, which enable you to create, edit, delete, and list during the design phase. Device profiles are used to create interface maps, which get directly used inside the Apstra config rendering engine when blueprints are deployed.

This document covers the knowledge required to create (and edit) a semantically correct Sonic DP, so that not only does it pass the validations in place in Apstra which ensure the right DP is created in the database, but also honors the vendor semantic requirement applicable to the device so that it does not result in deploy failure when the generated configuration is pushed to the network device.

Problem Statement

Device profiles are vendor semantics-aware data structures. To create a device profile, you need the device specification from the vendor. To create a valid and config-friendly JSON, you'll need to translate these specifications into the Apstra device profile data model.


The high level data model is the same for all DPs. The same keys are used for every device profile. The way we get the values might differ, or might be loaded with a vendor constraint. The document enlists the following:

  • The schema of the DP and the nested elements inside the DP.
  • The meaning of each key value pair in the schema.
  • The vendor specific recipe the values are populated.
  • List any constraints, corner cases to consider, especially for port configurations for certain (group of) models.
  • Any lessons learnt along the way creating those DPs already in production useful in creating future ones.

User Interface

When you create device profiles from the Apstra GUI, some of your entries are semantically validated. It's not completely capable of ensuring deep vendor-specific constraints and requirements though. With the exact vendor specification, the GUI assists you with creating a semantically valid DP which becomes part of the Apstra database data model.

Alternatively, you can write your own Python code that contains the vendor specifications, normalize it as per Apstra DP data model and generate the json to then import with the GUI.

Selector information

Entering the correct information in all four of the selector fields is critical for the device to get matched to the device profile.

Selector Field Value Command to get the information on device
model 0x21 show platform syseeprom
manufacturer If 0x2D in syseeprom, 0x2D else 0x2B show platform syseeprom
OS family SONiC Show version
version .* Show version


If you have the device specification, you can obtain its hardware and software capabilities for entry into the device profile.

The table below contains commonly found values in SONiC devices (based on qualified devices).

Selector Field Value Command to get the information on device
userland 64 (int) Does not affect config
form_factor ‘1RU’ (string) Does not affect config
ecmp_limit 64 (int) Does not affect config
asic ‘T2’ (string) Does not affect config
cpu ‘x86’ (string) Does not affect config
ram 16 (int) (Note, the unit is in GB) Does not affect config
onie True (bool) (default) Does not affect config
lxc True (bool) (default) Does not affect config

Interface naming conventions

Sonic follows the naming conventions per the sonic port name file as found Azure SONIC on the github master.

To create a SONIC device profile, you must read through the device specific port_config.ini (for example, sonic-buildimage/device/mellanox/x86_64-mlnx_msn2100-r0/ACS-MSN2100/port_config.ini) file and follow the instructions in the above link to come up with the right interface names.

The port_congi.ini specifies interface names that SONiC uses. The device profile must match interface names which will generate the PORT configs in the configuration file (config_db.json) . For this document purposes, port_config.ini and config_db.json should have the same interface naming standard. Use those interface names in your DP along with the lane numbers provided in the port_cfg.ini file. Once a device profile has been generated based on the aforementioned steps, Apstra will use that along with the LD to generate the Interface Map (IM). Apstra as part of its validation will make sure that the IM (which describes the port and its speeds) are indeed available and supported under “/usr/share/sonic/device/ x86_64-mlnx_msn2100-r0/ACS-MSN2100/port_config.ini” . This validation is performed to make sure SONiC NOS stack does not fail due to unsupported port configuration (in config_db.json) getting wrongly generated in Apstra due to wrong DP. So it is important that the end user makes sure the DP that is generated for a SONiC platform has the correct interface names and lane maps as reflected in port_config.ini file for that particular platform. A platform may have a few different port_config.ini files part of different HWSKUs for that platform. Apstra will try to validate the generated port configs with any of the available options for that platform. Apstra currently does not use the Dynamic Port breakout feature which is on-going in the SONiC project.


Device mismatch usually occurs at the beginning of a device’s lifecycle. If the device is not selecting the device profile, check the four selector fields in the device profile.

If ports are configured with incorrect speeds or if the OS-specific port constraints were not handled in the device profile or interface map, then deploy errors could be raised.

A possible flow for root cause would be:

  • Check the DP for obvious port capabilities errors. Is the port really capable of the speeds the DP has configured. The device specific port_config.ini Sonic open source project is a good resource to parse for ERROR messages.
  • Check if the DP has configured autoneg or disabled interfaces correctly. Autoneg and disabled can both be expressed in the interface setting field.
  • When debugging the interface names and lane mapping, please take a look at the corresponding port_config.ini. As an example for AS5712-54X edgecore/accton box we can get the port_config.ini file that has the details like lane/name/alias at
  • You can find the naming constraints in the official SONiC documentation. For example if you want to generate the interface names for Accton 5712 54X running SONIC, the port_config.ini is the authority. Sometimes the device might have inter-port constraints. For SONiC, it's generally laid out in the port_config.ini file. A specific platform could have multiple port_config.ini files, and a specific manufacturer with each port_config.ini file residing in their on HWSKU folders in the sonic image (like the one referenced above). The ability to try out different port speeds on (outside of what is listed in the port_config.ini) will need knowledge of the chipset and also the physical switch manufacturer to see what can be achieved. This information may not be available in any white papers unless requested of vendors.

Example: DP and port_config.ini

Port_config.ini from sonic-buildimage is below for Dell_Z9100 (x86_64-dell_z9100_c2538-r0/Force10-Z9100-C32

Translate port_config to a port-to-lane_map data structure using script:

The output from above will become a dictionary entry in sonic_device_info in the sonic device_profile generator python file.

Corresponding Device Profile generated in Apstra: