History
Invariant keeps a history of analysis results for uploaded snapshots. The snapshot history is most useful when snapshots are organized into well-named networks - see Best Practices.
- Track Network History: Observe how your network configuration and behavior have changed over time.
- Network Health: Show when the network went out of compliance with security or connectivity requirements.
- Audit and Compliance: Maintain a verifiable history of network configurations for compliance reporting and security audits.
- Troubleshoot Incidents: Quickly compare a problematic current or proposed state against known-good historical snapshots to identify impactful changes.
- Pinpoint Issues: Determine exactly when a misconfiguration or policy violation was introduced by examining historical data.
The following sections detail best practices for organizing your snapshot history, leveraging it for network health monitoring, and accessing historical data via the Invariant CLI.
Best practices
Always upload using --network. Don't mix sites on one network.
Avoid the default network. Always create a Network resource in Invariant specific to the snapshot part of the network the snapshot captures. For example, when taking a snapshot of a specific network (e.g. "IAD-prod"), create one network (or more, see below) for snapshots of just that site.
This is important because Invariant can produce a network health chart per-network. You will also configure alerting rules and set security and connectivity requirements per-network. Invariant can also serve as a searchable archive of prior network snapshots. All of these functions work best when a network contains snapshots of a single site.
Don't mix live network snapshots with change proposal snapshots in the same network.
Similar to above, always create distinct networks for snapshots created by capturing the live state of the network vs snapshots that are manually edited and represent a planned or proposed modification to the network.
A self-documenting naming stratgy can be helpful here. We suggest the following naming scheme.
-
-synced: For Networks that are regularly synced with your live network environment, append-syncedto the network name.- Example:
IAD-prod-synced - Network monitoring, audit, and drift detection would build on your
-syncednetwork.
- Example:
-
-golden: For Networks that track the 'golden' or intended configuration of the network, append-goldento the network name.- Example:
IAD-prod-golden - Compare this network to the
-syncednetwork, if you have it, to see the total impact of your proposed change, including calculated route tables.
- Example:
-
-proposed-<identifier>: For Networks that contain proposed changes.- Example:
IAD-prod-proposed-06-25-maintenance - Example:
IAD-prod-proposed-JIRA-803 - Use these networks to explore a possible change to the network. You may wish to delete these networks after use.
- Example:
Other network roles might include root cause analysis (-rca) or exploratory (-exp).
Network Health
Invariant tracks the health of your network over time by storing key metrics from each snapshot analysis, allowing you to observe trends and identify when issues may have arisen.
Dashboard
The Invariant UI provides a visual Network Health graph for each Network on the main dashboard / map screen.
- The graph x-coordinate follows the date.
- The graph y-coordinate counts the number of rules evaluated when the snapshot was uploaded.
- The marker color can appear black (errors prevented evaluation), yellow (some rules were skipped or errors present), red (one or more rules failed), or green (all rules OK).
Health Data
Retrieve raw historical health data using the invariant snapshots CLI command.
# List snapshots for "IAD-prod-synced" in TSV format
invariant snapshots --network IAD-prod-synced --tsv
uuid created_at network_name cf_violations ap_violations status errors_count
adf11172-9f8a-4333-b7c7-f9f0ecefe8d9 2025-02-27T01:47:50.811850+00:00 IAD-prod-synced 0 0 COMPLETE 0
6c334806-126c-4b63-bafe-495b39fdf995 2025-02-27T01:47:50.811850+00:00 IAD-prod-synced 0 1 COMPLETE 0
List Network Snapshots from the CLI
Use the invariant snapshots command to list prior snapshot analysis results for your networks.
# List snapshots for network IAD-prod-synced
$ invariant snapshots --network IAD-prod-synced
+--------------------------------------+-----------------+----------------------------------+----------+----------------+----------------+--------------+
| uuid | network | created_at | status | cf_violations | ap_violations | errors_count |
+--------------------------------------+-----------------+----------------------------------+----------+----------------+----------------+--------------+
| adf11172-9f8a-4333-b7c7-f9f0ecefe8d9 | IAD-prod-synced | 2025-02-27T01:47:50.811850+00:00 | COMPLETE | 0 | 0 | 0 |
| 6c334806-126c-4b63-bafe-495b39fdf995 | IAD-prod-synced | 2025-02-27T01:47:50.811850+00:00 | COMPLETE | 0 | 1 | 0 |
+--------------------------------------+-----------------+----------------------------------+----------+----------------+----------------+--------------+
# List snapshots for the default network
$ invariant snapshots
Control the output format with --tsv or --json.
# List snapshots in TSV format
$ invariant snapshots --network IAD-prod-live --tsv
uuid created_at network_name cf_violations ap_violations status errors_count
adf11172-9f8a-4333-b7c7-f9f0ecefe8d9 2025-02-27T01:47:50.811850+00:00 IAD-prod-synced 0 0 COMPLETE 0
6c334806-126c-4b63-bafe-495b39fdf995 2025-02-27T01:47:50.811850+00:00 IAD-prod-synced 0 1 COMPLETE 0
# List snapshots in JSON format
$ invariant snapshots --network IAD-prod-synced --json
Use the snapshot ID (uuid) from the listing with invariant show to access detailed reports for a specific snapshot.
# Example: Show the 'routes' report for a specific snapshot
$ invariant show routes --snapshot adf11172-9f8a-4333-b7c7-f9f0ecefe8d9 --tsv
See API > CLI for complete CLI documentation and Output Overview for details on available reports.