Skip to content

[Nexthop][fboss2-dev] Add lookup-class CLI to config/delete interface commands#1386

Open
vybhav-nexthop wants to merge 2 commits into
facebook:mainfrom
nexthop-ai:interface-lookup-class
Open

[Nexthop][fboss2-dev] Add lookup-class CLI to config/delete interface commands#1386
vybhav-nexthop wants to merge 2 commits into
facebook:mainfrom
nexthop-ai:interface-lookup-class

Conversation

@vybhav-nexthop

Copy link
Copy Markdown
Contributor

Summary

This PR adds a new attribute, lookup-class, to the existing fboss2-dev config interface and delete interface command families:

fboss2-dev config interface <interface-name> lookup-class <id>[,<id>...]   # replace the port's lookup-class list
fboss2-dev delete interface <interface-name> lookup-class                  # clear the port's lookup classes

What is a lookup class? Each front-panel port in the agent config carries a list field, Port.lookupClasses (a list<AclLookupClass> in switch_config.thrift). When this list is non-empty, the agent tags every neighbor (host) learned on that port with one of the class IDs from the list, and ACLs then match on those class IDs to steer each host's traffic into a specific egress queue. This is the mechanism behind the "queue-per-host" feature used on multi-host NICs (MH-NIC): several hosts share one physical switch port, and lookup classes let the switch give each host its own queue so one host cannot starve the others.

How the commands behave:

  • Set replaces whatever list the port currently has with the given list. Real queue-per-host deployments configure the full class pool (e.g. 10,11,12,13,14) so the agent can spread hosts across five queues; a single id is also accepted.
  • Delete resets the list to empty ([]), the field's default ("no per-host classification on this port"). Deleting individual ids from the list is intentionally not supported — clear-all covers the use case; an id-list delete form can be added later if a real need appears.
  • Validation: only the queue-per-host classes (CLASS_QUEUE_PER_HOST_QUEUE_0..9, ids 10-19) are accepted — the other AclLookupClass members (CLASS_DROP, DST_CLASS_L3_LOCAL_*, ...) are assigned by the agent itself and are rejected as reserved. Ids and enum names (case-insensitive) are both accepted. Unknown values, duplicate ids, and empty list slots (10,,11) are all rejected; the error lists every valid id and its name.
  • No traffic impact when applied (HITLESS): the change is staged in a config session and, on commit, flows through the agent's normal port-settings update path. Verified on hardware: committing reloads the config for fboss_sw_agent without restarting the agents or disrupting the port.

Changed files:

File Change
commands/config/interface/CmdConfigInterface.cpp lookup-class attribute; id-list parse/validate (enum check, duplicates, empty slots) + apply
commands/delete/interface/CmdDeleteInterface.{h,cpp} lookup-class valueless delete attribute (clears lookupClasses)
test/config/CmdConfigInterfaceTest.cpp 13 unit tests (set path: single id, lists, names, error cases)
test/config/CmdDeleteInterfaceTest.cpp 3 unit tests (delete path: clear, idempotent, multi-port)
test/integration_test/ConfigInterfaceLookupClassTest.cpp 7 end-to-end tests, all verifying the running config (4 rejection + 3 commit-path)
cmake/CliFboss2TestIntegrationTest.cmake, test/integration_test/BUCK wire the new test file into both build systems

Test Plan

  • Unit tests: set path (parse, apply single id and comma-separated lists, replacing an existing list, multiple ports, rejecting non-numeric / out-of-range / duplicate / empty-slot input) and delete path (clear all, idempotent when already empty, multiple ports); full cmd_config_test suite run to check for regressions
  • Integration tests against a real switch (an NH-4010-F lab device): every test verifies the port's lookupClasses in the agent running config — rejected inputs assert it is unchanged; happy-path tests pick an eth port with an empty lookupClasses baseline, commit the staged change and verify the port's lookupClasses in the agent running config, then delete + commit and verify it clears — the device is restored to its original state; fboss_sw_agent / fboss_hw_agent@0 stayed active through all commits (hitless)

Sample usage, including the committed result in the live agent config:

$ fboss2-dev config interface eth1/1/1 lookup-class 10,11,12,13,14
Successfully configured interface(s) eth1/1/1: lookup-class=10,11,12,13,14
$ fboss2-dev config session commit
Config session committed successfully and config reloaded for fboss_sw_agent.

# /etc/coop/agent.conf now has eth1/1/1 lookupClasses [10, 11, 12, 13, 14]

$ fboss2-dev delete interface eth1/1/1 lookup-class
Successfully reset attribute 'lookup-class' for interface(s): eth1/1/1
$ fboss2-dev config session commit

# eth1/1/1 lookupClasses now [] (back to default)

$ fboss2-dev config interface eth1/1/1 lookup-class 999
Invalid lookup-class value '999'. Valid values: 10 (CLASS_QUEUE_PER_HOST_QUEUE_0),
11 (CLASS_QUEUE_PER_HOST_QUEUE_1), ... 19 (CLASS_QUEUE_PER_HOST_QUEUE_9)

$ fboss2-dev config interface eth1/1/1 lookup-class 9
Invalid lookup-class value '9': CLASS_DROP is reserved for agent use. Valid values: 10 (CLASS_QUEUE_PER_HOST_QUEUE_0), ...

$ fboss2-dev delete interface eth1/1/1 lookup-class 11,13
Unknown delete attribute '11,13'. Valid attributes are: loopback-mode, lookup-class, ...

Adds a new attribute, lookup-class, to the existing `fboss2-dev config
interface` and `delete interface` command families:

  fboss2-dev config interface <name> lookup-class <id>[,<id>...]
  fboss2-dev delete interface <name> lookup-class

Each front-panel port carries Port.lookupClasses (a list<AclLookupClass>
in switch_config.thrift). When non-empty, the agent tags every neighbor
learned on that port with one of the class IDs, and ACLs match on those
IDs to steer each host's traffic into a specific egress queue — the
queue-per-host mechanism used on multi-host NICs (MH-NIC).

Behavior:

- Set replaces the port's current list with the given list. Real
  queue-per-host deployments configure the full class pool
  (e.g. 10,11,12,13,14); a single id is also accepted.
- Delete resets the list to empty, the field's default. Deleting
  individual ids is intentionally not supported — clear-all covers the
  use case; an id-list delete form can be added later if needed.
- Every id must be an integer matching a value of the AclLookupClass
  thrift enum. Non-numeric input, out-of-range ids, duplicate ids, and
  empty list slots (10,,11) are all rejected; the enum error lists every
  valid ID and its name.
- The change is staged in a config session and, on commit, flows through
  the agent's normal port-settings update path (HITLESS). Verified on
  hardware: committing reloads the config without restarting the agents
  or disrupting the port.

Test Plan:

- Unit tests: set path (parse, apply single id and comma-separated
  lists, replacing an existing list, multiple ports, rejecting
  non-numeric / out-of-range / duplicate / empty-slot input) and delete
  path (clear all, idempotent when already empty, multiple ports); full
  cmd_config_test suite run to check for regressions.
- Integration tests against a real switch (an NH-4010-F lab device):
  every test verifies the port's lookupClasses in the agent running
  config — rejected inputs assert it is unchanged; happy-path tests pick
  an eth port with an empty lookupClasses baseline, commit the staged
  change and verify, then delete + commit and verify it clears, leaving
  the device in its original state. fboss_sw_agent / fboss_hw_agent@0
  stayed active through all commits (hitless).
@vybhav-nexthop
vybhav-nexthop requested review from a team as code owners July 15, 2026 12:30
@meta-cla meta-cla Bot added the CLA Signed label Jul 15, 2026
@vybhav-nexthop
vybhav-nexthop force-pushed the interface-lookup-class branch from edf1c5e to 1887962 Compare July 15, 2026 14:18
- Restrict lookup-class to the queue-per-host classes
  (CLASS_QUEUE_PER_HOST_QUEUE_0..9, ids 10-19). The other
  AclLookupClass members (CLASS_DROP, DST_CLASS_L3_LOCAL_*, deprecated
  values) are assigned by the agent itself; configuring one on a port
  would make LookupClassUpdater tag neighbors with an agent-reserved
  class.
- Accept enum names (case-insensitive) in addition to numeric ids. The
  error message already displayed the names, but typing one back was
  rejected.
- Stop leaking folly's exception text into the non-numeric error
  message, matching the mtu handler's style.
- Use apache::thrift::util::enumNameSafe instead of the nullable
  TEnumTraits::findName when formatting the valid-values list.
- List lookup-class as a bare attribute name in kValidConfigAttrs like
  every other valued attribute.
- Drop the redundant `seen` set in parseLookupClassList; duplicate
  detection scans the (enum-bounded) result vector instead.
- Integration tests: reuse portLookupClasses() in
  findEthPortWithEmptyLookupClasses instead of duplicating the ports
  walk, and clear a committed lookup-class list in TearDown so a test
  that fails mid-cycle cannot leave the device modified.
- Unit tests: cover name input and reserved-class rejection; the
  multi-port test now uses a queue-per-host class instead of a
  reserved one.
@vybhav-nexthop
vybhav-nexthop force-pushed the interface-lookup-class branch from 1887962 to d93b138 Compare July 15, 2026 14:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant