Using the App

This document describes common use-cases and scenarios for this App.

General Usage

Home

The Home view is a portal to understand what the status of the devices are.

Some of the information described in this view, may not be immediately obvious.

• The Backup/Intended/Compliance status will always show the last time the job was successfully ran for that device, but there are several conditions it may be in.
  • Green with a date indicates that the run was successful, which was the last time the job ran.
  • Red with a date indicates the last time the job ran successfully, with the last time the job was attempted shown when you mouse over the date.
  • A red double-dashed icon indicated the job has never been successful
• The icons are provided in the following order, that largely matches the status.
  • Backups
  • Intended
  • Unix Diff
  • SoT aggregation data
  • Run job

The first four bring up a "modal" or "dialogue box" which has a detailed view for a dedicated page. The run job brings the user to a job to run all three components against all of the devices.

Jobs

There are a series of Jobs that are registered via the App. They can be viewed from the standard Jobs view.

Each Job attempts to provide sane error handling, and respects the debug flag to provide more information.

Application Settings

The golden configuration app settings can be found by navigating to Golden Config -> Settings button. Select one of the Settings, under the Golden Configuration section. Since Golden Configuration App version 1.0, the app allows for multiple settings to be configured by the User. Each of the settings, has the individual repositories and configuration details, as well as a Dynamic Group. You could use a combination of settings to customize your Configuration Compliance behavior. Settings have a name and a weight. The weight parameter indicates the priority of given Settings - the higher the weight, the device matching the Dynamic Group defined will be assigned to the scope. At the same moment, each device will be matched up to maximum of only one Settings. In case of the same weight, the sorting is performed by the name.

To create new settings click on the +Add button. To update existing settings click on one of the Settings name.

Setting	Explanation
Backup Repositories	The Git Repository where your backup configurations will be found.
Backup Path	A Jinja template which defines the path and name of backup files within the backup repository. The variable obj is available as the device instance object of a given device, as is the case for all Jinja templates. e.g. {{obj.location.name\|slugify}}/{{obj.name}}.cfg
Intended Repositories	The Git Repository where your intended configuration state files will be found.
Intended Path	A Jinja template which defines the path and name of intended configuration state files within the intended state repository. e.g. {{obj.location.name\|slugify}}/{{obj.name}}.intended_cfg
Jinja Repository	The Git Repository where your jinja templates will be found.
Jinja Path	A Jinja template which defines the path (within the repository) and name of the Jinja template file. e.g. {{obj.platform.network_driver}}/{{obj.role.name}}/main.j2
Dynamic Group	The scope of devices on which Golden Config's jobs can operate.
GraphQL Query	A query that is evaluated and used to render the config. The query must start with query ($device_id: ID!).

Note

Each of these will be further detailed in their respective sections.

Dynamic Group

Note

Starting in Golden Config v1.2 and onwards the original implementation of scope has been deprecated in favor of Dynamic Groups from Nautobot. During the migrations any Golden Config Setting scope attribute will be migrated to Dynamic Groups. All settings require a Dynamic Group, if the original scope is not set to allow ALL Devices a Dynamic Group will be created without a filter applied which will is the equivalent of all Devices.

The Dynamic Group provides a filter that will limit the list of devices in scope of a Golden Config Setting. In the Golden Config Home view the Dynamic Group is used to limit the Devices that are displayed, if a Device does not match the filter of a Dynamic Group it is considered out of scope for GoldenConfig and will not show on the Golden Config Settings view. All jobs in Golden Config also use the Dynamic Group to know which Devices are in scope. A job can optionally further refine the scope, but the outer bound would be based on what is defined in the Dynamic Group. The options are best described by leveraging the Devices list view, search features (the filtering shown on the side of the Devices.) Building a query there, will provide the exact keys expected.

Scope Of Devices

Within the Detail view of a Golden Config Setting the section to denote the scope of devices links back to the Dynamic Group that is assigned and renders the filter attribute of the Dynamic Group as JSON. All updates to the scope of Devices must be done via the Dynamic Group not directly on the Golden Config Setting.

The below configurations of scope can either be removed or specified for pre 1.2 only, the same logic applies in 1.2 and onwards but via DynamicGroups.

Filtering to specific platforms, based on their name.

{
  "platform": [
    "Cisco IOS",
    "Cisco NXOS",
    "Arista EOS",
    "Juniper Junos"
  ]
}

Adding a "has_primary_ip" check.

{
  "platform": [
    "Cisco IOS",
    "Cisco NXOS",
    "Arista EOS",
    "Juniper Junos"
  ],
  "has_primary_ip": "True"
}

When viewing the settings, the scope of devices is actually a link to the query built in the Devices view. Click that link to understand which devices are permitted by the filter.

Create Secret Groups

Info

Unless you are only using configuration compliance with backup and intended configurations in repositories that do not require credentials, you will have to go through these steps.

The Git Settings requires a Secret Group to be attached which in turn requires a Secret to be required. The Secret can use any provider, you are encouraged to read the Nautobot docs on Secret Providers, but for our purposes we will simply use the Environment Variable option, so keep in mind that detail during the coming instructions.

Create a new secret by navigating to Secrets -> Secret -> add (button).

Info

See GitHub Personal Access Token for an example method to generate a token in GitHub.

Parameters:

Field	Explanation
Name	User friendly name for secret.
Provider	The Secret Provider to the docs.
Parameter	This will be dependant based on the provider.

For our example, let's configure and create with:

Field	Value
Name	GIT-TOKEN
Provider	Environment Variable
Variable	NAUTOBOT_GOLDEN_CONFIG_GIT_TOKEN.

Depending on your provider, you may also need a username, so you would repeat the process such as:

Field	Explanation
Name	GIT-TOKEN
Provider	Environment Variable
Variable	NAUTOBOT_GOLDEN_CONFIG_GIT_USERNAME.

Now we need to create the Secret Group, navigate to Secrets -> Secret Group -> add (button).

For our example, let's configure and create with:

Field	Value
Name	Git Secret Group
Access Type	HTTP(S)
Secret Type	Token
Secret	GIT-TOKEN.

Tip

If your instance requires a username as well, please ensure to add that as well.

The steps to add the variables to your environment are outside the scope of this document and may or may not be needed depending on how you manage your Secrets in your environment, but please be mindful of ensuring the Secrets end up on your system.

Git Settings

The app makes heavy use of the Nautobot git data sources feature. There are up to three repositories used in the application. This set of instructions will walk an operator through setting up the backup repository. The steps are the same, except for the "Provides" field name chosen.

In order to setup this repository, go to Nautobot and navigate to the Data Sources Git integration. Extensibility -> Git Repositories.

From the Git Repositories page we can add the Backup repository.

Click on Add.

You will now be presented with a page to fill in the repository details.

Parameters:

Field	Explanation
Name	User friendly name for the backup repo.
Slug	Auto-generated based on the name provided.
Remote URL	The URL pointing to the Git repo that stores the backup configuration files. Current git url usage is limited to http or https.
Branch	The branch in the Git repo to use. Defaults to main.
Secrets Group	The secret group configured that will define you credential information.
Provides	Valid providers for Git Repo.

Note

When Secret Group is used for a Repository the secrets type HTTP(S) is required for this plugin, as shown previously.

Select backup configs and click on Create.

Once you click Create and the repository syncs, the main page will now show the repo along with its status.

For their respective features, the "Provides" field could be backup intended configs and jinja templates.

Apps Buttons

The apps buttons provides you with the ability to navigate to Run the script, overview report, and detailed report.

Run Script

This can be accessed via the Apps drop-down via Run Script button of the Home view, the user will be provided a form of the Job (as described above), which will allow the user to limit the scope of the request.

Device Template Content

The app makes use of template content right_page in order to use display in-line the status of that device in the traditional Nautobot view. From here you can click the link to see the detail compliance view.

Location Template Content

The app makes use of template content right_page in order to use display in-line the status of that entire location in the traditional Nautobot view. This sums the total for all locations for parent locations.

API

To run the job programmatically, reference the nautobot documentation for the proper API call. Pay special attention to the class_path definition.

Feature Enablement

Enabling features such as backup or compliance, will render those parts of the UI visible. It is worth noting that disabling features does not provide any garbage collection and it is up to the operator to remove such data.

Network Operating System Support

The version of OS's supported is documented in the FAQ and is controlled the platform network_driver. The platform network_driver must be exactly as expected or leverage a configuration option--which is described the the FAQ--for the app to work.

Use-cases and common workflows

This app enable four (4) key use cases.

1. Configuration Backups - Is a Nornir process to connect to devices, optionally parse out lines/secrets, backup the configuration, and save to a Git repository.
2. Intended Configuration - Is a Nornir process to generate configuration based on a Git repo of Jinja files to combine with a GraphQL generated data and a Git repo to store the intended configuration.
3. Source of Truth Aggregation - Is a GraphQL query per device that creates a data structure used in the generation of configuration.
4. Configuration Compliance - Is a process to run comparison of the actual (via backups) and intended (via Jinja file creation) CLI configurations upon saving the actual and intended configuration. This is started by either a Nornir process for cli-like configurations or calling the API for json-like configurations

Notice

The operators of their own Nautobot instance are welcome to use any combination of these features. Though the appearance may seem like they are tightly coupled, this isn't actually the case. For example, one can obtain backup configurations from their current RANCID/Oxidized process and simply provide a Git Repo of the location of the backup configurations, and the compliance process would work the same way. Also, another user may only want to generate configurations, but not want to use other features, which is perfectly fine to do so.

Screenshots

There are many features and capabilities the app provides into the Nautobot ecosystem. The following screenshots are intended to provide a quick visual overview of some of these features.

The golden configuration is driven by jobs that run a series of tasks and the result is captured in this overview.

The compliance report provides a high-level overview on the compliance of your network.

The compliance overview will provide a per device and feature overview on the compliance of your network devices.

Drilling into a specific device and feature, you can get an immediate detailed understanding of your device.