Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Out-of-Band Agents

Introduction

Installing system agents on GPU hosts typically requires storing credentials in Apstra. Managing sudo credentials presents a challenge for organizations that don’t allow storing device credentials in external systems. Apstra 6.1 addresses this by enabling out of band (OOB) device agent installation. OOB installation changes the typical agent installation flow. In 6.1, GPU servers establish secure connectivity to Apstra without requiring credentials to be stored in Apstra. As a result, credential management overhead is reduced, and your organization’s zero trust security policies are maintained.

Out-of-Band Agents on GPU Hosts

With OOB agent installation in 6.1, the process of agent installation is handled by the administrator, not Apstra. Instead of Apstra pushing the agent to the server, the administrator copies the aos_device_agent.run file to the GPU host and executes it locally with out-of-band parameters. The device agent then uses the configuration stored in aos.conf to establish connectivity to the Apstra Server. Apstra is unaware of any credentials.

Once the device agent is installed, it operates in telemetry only mode. In this mode the agents do not change any configuration but collect various telemetry data to report it back to AOS. On the Apstra side, the system agent must be configured as onbox with the operation mode set to telemetry only. When both sides are configured correctly and the management IP on the system agent matches the IP reported by the device

Because OOB agents only collect telemetry, they have fewer capabilities than traditional system agent installations. For example in the Apstra UI, buttons like “reboot” and “install” are grayed out for because job execution is not supported in this mode. The “delete action remains available so you can delete the system agent when needed. As such, OOB agents provide visibility into your devices without having the ability to make changes to the host system, and no credentials are stored in Apstra.

Changing between installation types is supported in both directions. You can change from a traditional system agent-based installation to OOB by rerunning the device agent on compute with OOB parameters.

To change from an OOB agent to a system agent:

  1. Delete the previously installed system agent that was supporting the OOB device.

  2. Delete/purge the AOS service on the device agent.

  3. Create a new onbox system agent with credentials and configure the job that should run when the agent is created. When you use the API, this is controlled by the job_on_create field in the system agent payload.

API Changes for Out-of-Band Agents in Apstra 6.1

OOB agents reuse the existing Apstra APIs but add new fields and behaviors so Apstra can distinguish them from traditional agents.

System Agent

The system agent details response now includes:

  • config.allowed_job_types in [‘config’]: This list is empty for OOB agents.
  • device_agent_install_type in [‘status’]: Indicates how the device agent was installed. Available values are systemAgent and outOfBand.
    • Note that this is the primary field you can use when you want to show the install type in the Managed Devices page or filter agents based on installation method.

    • device_agent_install_type in [‘device_facts’]: Indicates if the device agent install type is systemAgent or outOfBand. On UI, this could be displayed in a new column against the device on device management page.

System Details

The system details response now includes:

  • facts.device_agent_install_type: Indicates whether the device attached to this system was installed as systemAgent or outOfBand.

All System agent job APIs, such as the following return status "409" when both of the following are true:

  • The system agent type is onbox

    The associated device agent install type is outOfBand

  • /api/system-agents/<agent-id>/check

  • /api/system-agents/<agent-id>/install

  • /api/system-agents/<agent-id>/reboot

This behavior prevents jobs from running for OOB agents.

Install an Out-of-Band Agent

Installing an OOB agent involves two procedures that can be completed in either order. The first step occurs on the GPU host where you run the installer. The second step occurs in Apstra when you create a system agent. You must complete Both steps before Apstra receives telemetry from the device.

To run the installer on the GPU host:

  1. Download the latest aos_device_agent.run file.

    Download the file from the Juniper Downloads page under Juniper Apstra Data Center Director.

  2. Copy this file to the GPU host where you want to install the device agent.
  3. Run the installer.

    Replace the IP address with the IP of your Apstra server and adjust the interface name accordingly.

    The installer creates and configures the aos.conf file with the parameters you provided. It also installs the device agent service on the host. The device agent starts automatically and begins attempting to connect to Apstra's metadb using the interface you specified.

    The OOB installation arguments are:

    • --install-type:

      • Maps to “device_agent_install_type” in the “device_info” section of aos.conf. The available values are “outOfBand” and “systemAgent”.

      • Default value when not specified: systemAgent.

    • --interface:

      • Maps to interface in the controller section of aos.conf.

      • Typical value: eth0 or another interface connected to Apstra controller (this must be the interface with reachability to Apstra controller).

      • Default value when not specified: empty.

    • --metadb:

      • Maps to metadb in the controller section of aos.conf.

      • Expected format: tbt://<AOS_IP>:29731.

      • Default value when not specified: tbt://aos-server:29731.

    You can provide installation parameters directly on the command line so you do not need to edit aos.conf manually. For example:

    This command creates or updates aos.conf with the correct install type, metadata backend, and interface values.

    The installer exhibits the following behavior in regards to aos.conf:

    • If no arguments are supplied and aos.conf does not exist, a new aos.conf is generated with default values.
    • If no arguments are supplied and aos.conf already exists, the file is left as is and is not overwritten or modified.
    • If any of the arguments are supplied and aos.conf exists, only the fields related to those arguments are updated.

After the device agent is running on the GPU host, you must create a system agent in Apstra so that Apstra knows to accept connections from this device. You can do this through the Apstra UI or via the API.

Create a System Agent for the Out-of-Band Agent in Apstra

After installing a device agent on the GPU host, you must create a system agent in Apstra so that Apstra accepts connections from the GPU host.

To Create a System Agent for the Out-of-Band Agent:

  1. Navigate to Devices > Managed Devices > Create Onbox Agent(s).

    The Create Onbox System Agent(s) window displays.

  2. Fill in the following information:
    Note: The credentials, Agent Profile, and Packages options should be left blank.

    • Agent Parameters:

      • Device Addresses: Enter the IP(s) of the GPU hosts

      • Operation Mode: Telemetry Only

      • Job to run after creation: None



  3. Click Create.
  4. To verify the installation:

    1. In the Apstra UI, navigate to Devices > Managed Devices.

    2. Look for the system agent you just created.

    3. In the “Job State” column it should show “INIT”.

Troubleshooting and Validation

After installing your OOB agent, you can use the following checks to validate that agents are active in Apstra and streaming telemetry.

  1. Check that the agent shows a Job Status of “INIT” in Devices > Managed Devices.

  2. Confirm that the agent shows:

    • Operation Mode in Telemetry Only.

    • Device Agent Install Type as Out of Band.

3. Check the Telemetry tab of the GPU host in Apstra and verify that telemetry like interface statistics or LLDP information is present.

4. Confirm aos.conf settings:

  • On the GPU host, open the aos.conf file and verify that:

    • `device_info.device_agent_install_type` is set to `outOfBand`.

    • `controller.metadb` points to the correct Apstra IP and port.

    • `controller.interface` matches the interface that reaches Apstra.