Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Device Configuration Lifecycle


A good understanding of the Apstra device configuration lifecycle is essential. Before working with devices in the Apstra environment, we strongly recommend that you fully understand how devices are configured from the moment they are on-boarded to the moment they are decommissioned.


The following terminology is used to identify configuration stages:

Config Description
Pristine Config When you install a device agent, configuration is added to the pre-existing config on the device. Normally, the pristine config does not change throughout the device's lifecycle.
Discovery 1 Config When you acknowledge a device, initial basic configuration is added. This includes enabling LLDP on all interfaces.
Discovery 2 Config When you assign a device to a blueprint without deploying it (deploy mode: ready), additional basic configuration is added. This includes device hostnames, interface descriptions and port speed / breakout config.
Service Config When you deploy a device (deploy mode: deploy), configuration that's required in the Apstra environment is added. Service Config consists of Discovery 1 config, Discovery 2 config and this additional config.
Rendered Config Complete Apstra-rendered configuration for the device, per the Apstra Reference Design.
Incremental Config The configuration that will be applied when you commit changes that you've made.
Golden Config When you commit config changes, a new running config is collected. This is called the Golden Config, and serves as Intent: Running configuration is continuously matched against this Golden config. When a deployment fails, Golden Config is unset.

Configuration Stages: Overview

The following table describes the various config events and their resulting device config, Apstra-managed device state, and blueprint deployment mode:

Event Resulting Device Configuration Resulting Apstra Managed Device State Apstra Blueprint Deployment Mode
New device Factory Default Configuration N/A Not Assigned
Add pre-Apstra [mgmt] configuration to device Factory + Pre-Apstra N/A Not Assigned
Install Apstra device system agent Pristine Config: Factory + Pre-Apstra + Agent Install config OOS-QUARANTINED Not Assigned
Acknowledge device Discovery 1: Pristine, plus Interfaces Enabled OOS-READY Not Assigned
Assign device to blueprint (no deploy) Discovery 2: Discovery 1, plus various basic config IS-READY Ready
Deploy device Service Config: Discovery 2, plus full Apstra-Rendered config IS-ACTIVE Deploy
Add/Commit incremental configuration Delta of resulting config changes from blueprint modifications IS-ACTIVE Deploy
Drain device "Drain" Configuration is added IS-READY Drain
Undeploy device Apstra-rendered config is removed IS-READY Undeploy
Unassign device Discovery 1 config is re-applied OOS-READY Not Assigned

When you install an agent on a device, any configuration that was already there becomes part of the Pristine Config, which means it's included in the device's entire configuration lifecycle. Any corrections that you make will be service-impacting.

Configuration Stages: Detail

New Device (Factory Default)

The lifecycle of a device begins with the factory default configuration stage.

Add Pre-Apstra Config (User-required)

Certain minimum base configuration must be included in the entire config lifecycle, such as that required for agent installation or device connectivity. You must configure management IP connectivity between devices and the Apstra server out-of-band (OOB). Configuring it in-band is not supported and could cause connectivity issues when changes are made to the blueprint.

This User-required config can be bootstrapped with Apstra ZTP, or added with scripts (or other methods).


Only add configuration that is required for connectivity, for installing the device agent, or that is known to be required throughout the device lifecycle (for example Banners or NTP / SNMP / syslog server IP addresses). You can add required configuration that is not rendered by Apstra with configlets.

Install Agent (Pristine)

When an Apstra device agent is installed on a device (or in the case of an offbox agent, installed Apstra server-side) the device connects and registers to Apstra in the Quarantined state. A partial config is applied and any "Pre-Apstra Config" that has already been added becomes part of the Pristine configuration. This pristine configuration is the basis for all subsequent device configuration.

Acknowledge Device (Discovery 1 / Ready)

Acknowledging a device puts it in the Ready state and signals the intent to have Apstra manage the device. In this Discovery 1 stage minimal base configuration essential to Apstra agent operation is added to the pristine config. Discovery 1 applies a complete configuration (Full config push), overwriting all existing configuration to ensure config integrity.

  • All interfaces are rendered with interface speeds for the assigned device profile.
  • All interfaces are no shutdown to allow you to view LLDP neighbor information.
  • All interfaces are moved to L3 mode (default) to prevent the device from participating in the fabric.

Devices that have been acknowledged cannot simply be deleted. Since the device would still have an active agent installed, the devices would re-appear within seconds. If you want to remove a device from Apstra management, see Remove Device for the complete workflow. There are additional steps required before deleting a device (such as unassigning the device from the blueprint, setting the admin state, and uninstalling/deleting the agent).

Assign Device (Discovery 2 / Ready)

Assigning a device to a blueprint and setting its Deploy Mode to Ready puts it in the Discovery 2 configuration stage. The device has been staged, but not yet committed (deployed) to the active blueprint. Discovery 2 applies a complete configuration (Full config push) to ensure config integrity. Discovery 2 configuration brings up network interfaces and configures interface descriptions and validates telemetry, such as LLDP, to ensure it is properly wired and configured. This configuration is non-disruptive to other services in the fabric. Links are up, but they are configured in L3-mode to prevent STP/L2 operations.

  • Hostname is configured per blueprint intent.
  • All interface descriptions are changed per blueprint intent.
  • Interfaces are rendered with blueprint interface speeds.
  • No routing or BGP is configured.
  • No L3 information is configured on interfaces.
  • Fabric MTU is modified for spines to 9050 bytes.

Deploy Device (Rendered / Active)


The first time a device is assigned, the Deploy Mode is set to "Deployed" and the blueprint is committed (full config push is triggered for the device) effectively overwriting the complete running config with the pristine configuration then adding the full rendered Apstra configuration. Any config that is not part of the Apstra-rendered config is discarded.

When a device is committed, it becomes Active, and Apstra deploys the service configuration, moving the device into the Rendered configuration stage. Rendered config contents are derived from the pristine config, selected reference design/topology, NOS, and device model. The first rendered config applies a complete configuration (removing all existing configuration from the Apstra server per Jinja) to ensure configuration integrity. This is the full end-state of Apstra. A full configuration has been pushed, all interfaces are running, and routing within IP fabric is configured. Full configuration rendering, intent-based telemetry, and standard service operations occur here.

  • Hostname is configured per blueprint intent.
  • All interface descriptions are changed per blueprint intent.
  • Interfaces are rendered with blueprint interface speeds.
  • Interface VLANs, LAGS, MLAG, VXLAN, and so on, are managed.
  • All L3 information is rendered.
  • BGP configuration is fully rendered for all BGP peering information.
  • DHCP configuration is configured for any required DHCP relay agents.
  • The device is added to the graph database.

After the full configuration is successfully deployed to the device, Apstra takes a snapshot of the device configuration (for example show running-confg) and stores it as the Golden Configuration.


Adding extra configuration at this time results in a configuration deviation anomaly, a difference between the current device configuration and the stored Golden Configuration. Subsequent deployment tasks will fail until the deviation is resolved. Correct the anomaly to proceed.

To see the rendered config file after committing the blueprint, select the device in the Active blueprint and click Config (right-side).

A running configuration can be modified in multiple ways. To modify a config that is not part of the reference design, use configlets.

Stage Device Update (Incremental / Active)

Staging changes to a running blueprint creates an Incremental configuration.

Commit Device Again (Rendered-Updated / Active)

When a change is committed to a blueprint that affects the device's configuration, a partial config updates the rendered config.

View Device Config from Blueprint

From the blueprint, navigate to Staged > Physical to go to the topology view of the physical blueprint.

Click a node in the topology, then from the Device tab in the panel on the right, you can click links for rendered, incremental, pristine, or (new in Apstra version 4.1.0) device context in the Config section.

The device model is a nested dictionary of variables that you can leverage when creating configlets.

The query tab provides dynamic search capabilities to quickly search through keys or values and identify the variables of interest. Syntax is case-sensitive. For example, a search of the keyword bgp provides information on the BGP configuration of the switch as well as the BGP sessions (protocol sessions), while a search on the key word BGP provides the list of BGP route maps such as "BGP-AOS-Policy". The use of these variables as built-in property-sets inside a configlet must also respect the case-sensitive attribute of the device model.


Device models are an internal data model used in the Apstra environment. They are subject to change without notice or documentation of schema changes.

Configuration Deviations

After each successful config deploy the running config is collected and stored internally as the Golden configuration. Intent is the cornerstone of the Apstra product. As such, any difference between the actual running config and this golden config results in a config deviation anomaly on the blueprint's dashboard. The golden config is updated every time config is successfully applied to a device.

Some important points to know:

  • Each successful configuration deployment results in an updated Golden Config.
  • If configuration deployment fails, Golden Config is not set. This means both a config deviation and deployment failure anomaly are raised.
  • Running configuration telemetry is continuously collected and matched against the Golden Config. Any difference result in a deviation anomaly.
  • Configuration anomalies can be 'suppressed' using the "Accept Changes feature". This does NOT mean the change is added to golden config or Intent.

See Anomalies (Service) for details.

Device Offline (Unavailable)

A managed device (one that has been acknowledged) that is not connected to the Apstra server is in the unavailable state. A device could be offline if the device agent interface is offline, if the service is not running, or if a network connectivity error occurs.

Manually Apply Full Config

The Discovery 1 and Deploy Device configuration stages initiate full config pushes. In rare cases, you may need to manually apply a full config push. For example, if the required config is not in place for a blueprint with NX-OS devices that require TCAM carving, the device config will fail. The TCAM config error must be corrected, followed by manually pushing a full config.


Perform a full configuration push with the utmost caution, as it is very likely to impact all services running on the box. Exact impact depends on changes being pushed. Also note all Out of Band changes are overwritten upon a full push.

Deploy Modes

Managed devices in blueprints can be in one of several modes. See Devices (Staged) for steps for changing deploy modes.

Deploy Mode Description
Not Set Initial device state. The device is not active in the fabric.
Deploy Device is active in the fabric.
Ready When a device is assigned to a blueprint it is in ready mode; discovery 2 configuration is added (hostnames, interface descriptions, port speed / breakout configuration). It is not yet active in the fabric. Changing from deploy to ready removes Apstra-rendered configuration.

Draining a device for physical maintenance enables it to be taken out of service gracefully without impacting existing TCP flows. Depending on the device being drained, Apstra uses one of two methods:

For L2 Servers

  • MLAG peer-links port channels and bond interfaces on any NOS are not changed.
  • For Arista EOS, Cisco NX-OS, all interfaces towards L2 servers in the blueprint are shutdown.

For Network L3 Switches

Use Inbound/Outbound route-maps 'deny' statements to block any advertisements to le 32.

This allows existing L3 TCP flows to continue without interruption. After a second or two, the TCP sessions should be re-established by the src/dst devices, or they should negotiate a new TCP port. The new TCP port forces the devices to be hashed onto a new ECMP path from the list of available links. Since no ECMP routes to the destination are available in the presence of a route map, the traffic does not flow through the device that is in maintenance mode. The device is effectively drained of traffic and can be removed from the fabric (by changing Deploy mode to Undeploy).

While TCP sessions drain (which could take some time, especially for EVPN blueprints) BGP anomalies are expected. When configuration deployment is complete, the temporary anomalies are resolved. For more information, see Drain Device Traffic.

Undeploy Undeploying a device removes the complete service configuration. If a device is carrying traffic it is best to put it in drain mode first (and commit the change) before undeploying the device.