Transactions

In EDA, a transaction is a set of changes that must succeed or fail together. If one item in a transaction fails, the whole transaction is deemed to have failed and any successful changes within the transaction are rolled back to their previous state.

Any resource configurations you create, change, or delete in EDA must be committed in order for those changes to be applied to the participating resources.

  • Any single configuration change can be committed immediately on its own, in which case it constitutes a transaction consisting of just that change.
  • However, you do not need to commit each configuration individually as you create it. EDA allows you to add any new, changed, or removed configuration to a growing set of configuration changes that you want to commit together as one collective transaction. When you are ready you can then commit the whole transaction, applying the entire set of configuration changes together.

    The complete transaction, including all of its constituent configuration changes, then succeeds or fails as a unit. If any part of the transaction fails, the whole transaction is rolled back. You can then resolve the blocking issue, and apply the transaction again.

Within EDA, ConfigEngine is the main service behind transactions. Its job is to compute the complete set of resources that must be modified, deleted, or created as part of the transaction; ensure all dependencies and outputs are captured; and then transact the updates, thereby generating changes for NPPs and other controllers.

After a transaction has been successfully processed, it is written to EDA's Git repo for persistence, becoming the new accepted state of the infrastructure.

Commit options for a typical resource

When you configure a resource in EDA, you are always presented with the following options to either commit the change, or add it to a transaction:

Figure 1. A sample resource ready to commit
  • Commit: clicking this button immediately commits the change to EDA to be applied to the target device.
  • Add to Transaction: clicking this button adds the current resource configuration to the transaction basket. It is not committed, or configured on the target device, until the transaction itself is committed.

Transactions drop-down panel

The Basket icon is displayed at the top of every page in the EDA GUI. It indicates when a transaction is pending, and can be used to open the Transaction drop-down.

When one or more resource changes are pending (containing at least one configuration and ready to commit), the Basket icon is highlighted and displays a count of pending resources in the transactions.
Figure 2. The basket showing one pending resource

You can open the Transactions drop-down panel by clicking the Basket icon.

The Transactions drop-down panel gives you a fast way to:
  • review the contents of any pending transactions
  • perform a dry run of any pending transaction
  • add a commit message to a pending transaction
  • commit any pending transaction
  • discard any pending transaction
  • view a list of recently completed transactions
You can also use this drop-down panel to manage individual configurations within the transaction. You can:
  • edit a single resource
  • remove a resource from the transaction
  • restore a removed resource back into the transaction

You also use this drop-down panel to view the EDA Transaction Log.

Figure 3. The transaction drop-down panel
Table 1. Elements of the Transactions drop-down
# Description
1 Clear Workspace button: click to clear all configurations from the Transactions workspace.
2 Log button: click to open the Transactions log.
3 Select All button: use to select all configurations within this transaction.
4 Configuration selectors: Check or un-check to include a configuration within, or exclude a commit from, the current transaction.

Use the main check box at the top of the list to include or exclude all configurations together.
5 Configuration Menu button: use to access the Edit or Delete actions for this configuration.
6 Delete items button: click to clear only the selected configurations from the transaction.
7 Transaction options:
  • Dry Run: perform a dry run to evaluate the effects of the transaction after it is committed.
  • Commit: proceed with applying the selected configurations as part of a single transaction.

Dry runs

In EDA, you can perform a dry run of any pending transaction. A dry run can reveal anticipated configuration issues if the transaction were to proceed normally, and allow you to troubleshoot any errors before committing the transaction on actual resources.

In a dry run, the system does not send any of the configuration changes to the managed nodes. However, it executes the transaction against EDA's stored information about each participating resource, and validates the transaction against that data. The result of the dry run is displayed within the drop-down form.

During a dry run, you cannot make changes to the commit. After the dry run is complete, transaction details and diffs are available just as with a normal commit.

Closing the transaction basket dismisses the Transactions form, but retains information about the most recent dry run. If changes occur to the basket contents while the form is closed, dry run information is cleared and it is restored to the normal list view.

Figure 4. A sample result of a dry run
Table 2. Elements of the dry run results display
# Description
1 Details button: click to open the Details view for this transaction.
2 Diffs button: click to open the Diffs view for this transaction.
3 Actions menu for each row: use to edit or remove resource configurations within the transaction.

Commit

Clicking Commit commits the entire transaction. The complete transaction, including all of its constituent configuration changes, then succeed or fail as a unit. If any part of the transaction fails, the whole transaction is rolled back. You can then resolve the blocking issue, and commit the transaction again.

Whether the transaction succeeds or fails, you can view the details for the transaction, and the diffs that resulted from it. For a failed transaction, you can edit each row within the transaction to revise the configuration changes in support of another attempt.

Closing the transaction basket dismisses the Transactions form, but retains information about the most recent commit. If changes occur to the basket contents while the form is closed, commit information is cleared and it is restored to the normal list view.

Figure 5. A sample of a failed transaction with one error
Table 3. Elements of the transaction results display
# Description
1 Details button: click to open the Details view for this transaction.
2 Diffs button: click to open the Diffs view for this transaction.

Recent

Click on the Recent tab to view a list of the most recent transactions from the current user. A more complete list of transactions is available from the Transactions log.

From the Recent view, you can view the details or diffs view for any listed transaction.

Configuration actions

The following actions are available for each configuration within the transaction:

  • Edit the configuration: Click the Edit icon to open the original resource configuration page so that you can modify the configuration details.
  • Remove the configuration: Un-check the Configuration selector check box beside any configuration to remove it from the overall transaction.
  • Restore the configuration: Re-check the Configuration selector check box beside any unchecked configuration to restore it to the overall transaction.

Additional actions

From the Actions menu of the Transactions drop-down, you can perform any of the following:
  • Discard Transaction: empties the basket. This can be done before any commit/dry run, in which case nothing is in the transaction log.
  • Transaction log: select this action to open the Transactions page, showing a list of recent transactions.

Transactions page

The Transactions log displays all of the transactions recorded in the Transactions log, providing an overview of transactions performed in the EDA system.

From this page you can:
  • View the list of transactions
  • View a detailed summary of individual transactions
  • View the precise configuration changes ("Diffs") that were included in any transaction
  • revert a successful transaction
  • restore configurations to a specific transaction
Figure 6. The Transactions log

The Transactions log does not include the entire EDA transaction history. It is limited to results cached in the EDA Config Engine.

Note: The Transaction log is visible to all authenticated users.

The following information displayed in the transactions log:

Table 4. Transaction information
Column Description
Transaction ID An identifier for the transaction, in the form "Transaction <number>".
Description An optional description provided at the time the transaction is committed.
Created by The user who executed the transaction.
Completion Timestamp The date and time the transaction was completed.
Status Whether the transaction was successful, or failed.
State The state of the completed transaction.
Transaction type Whether the transaction was a Dry Run or commit.

In a Dry Run, the system does not send any of the configuration changes to the managed nodes. However, it executes the transaction against EDA's stored information about each participating node, and validates the transaction against that data.

Commit Hash A unique string that identifies this transaction in the EDA repository.
For each row in the Transaction list, a set of actions available from the Table row actions menu:
  • Details, which opens the EDA Transaction Summary page showing detailed information for one transaction.
  • Diffs, which opens the EDA Transactions Diffs page
  • Revert, which creates a new transaction that effectively undoes the selected transaction. The result is to set the resources affected by the commits in this transaction to their state before the transaction took place.
    Note: Executing a Revert operation requires readWrite permission for all input CRs in the transaction.
  • Restore, a powerful command that restores all resources to their state at the completion of the selected transaction.
    Note: Executing a Restore operation requires readWrite permission for the transaction restore API endpoint.

Transactions summary

The Transaction Summary page shows detailed information about a single transaction.

Figure 7. The Transactions summary page
This includes:
  • The completion status, the name of the transaction, any description provided, and a timestamp for its completion.
  • An Error Summary showing the number of:
    • General errors
    • Intent errors
    • Node configuration errors
  • A Custom Resource (CR) Summary, showing the number of:
    • Input CRs (resource creation, updates, and deletes included in the transaction))
    • Intents Run (configuration scripts executed as part of the transaction)
    • Changed CRs (resource creation, updates, and deletes, including input CRs and changes derived from the intent runs)
    • Nodes with Changes
Note: The Input CR list includes only resources for which the user has read access.
Note: Intent runs, Changed CR, Nodes with Changes, and Errors are only visible to the user if they have read access to all Input CRs for the transaction.

Transaction details

The Errors and CRs that are summarized at the top of the Summary page can be viewed in detail in the Transaction Details panel. Different tabs display lists of input CRs, changed CRs, intents run, nodes with changes, and errors.

Transaction diffs

From the breadcrumb at the top of the Transactions page you can select Diffs to view the precise details of the configurations changed as part of this transaction.

Figure 8. The Transaction Diffs view

Each changed CR and resulting node configuration change as part of this transaction is displayed, along with a diff view representing the new or changed lines in the respective configuration data.

Note: Resource diffs are only visible to the user if they have read access to all Input CRs for the transaction.
Note: Node Configuration diffs are only visible to the user if they have read access to the transaction nodeconfig diff API endpoint.

Transaction topology

The Transaction Topology displays all of the input resources and output resources that are involved in a transaction. It graphs the relationship between derived and parent resources.

Resources and node configurations are displayed as nodes within the topology.

Links in the Transaction Topology represent resource relationships established by the intent runs where:
  • endpoint A represents the resource which triggered the intent script
  • endpoint B represents the resource that was updated or created by the intent script

Changed resources are shaded yellow in the topology.

If an intent error occurred during the transaction, the resource that triggered the intent script is shaded red.

Figure 9. The Transactions Topology view
Note:

The Transaction Topology only graphs createUpdate relationships. For example, when a fabric intent creates ISL resources, this is represented as links between the fabric resource and those ISL resources.

The Transaction Topology does not graph Read relationships. So, for example, when a fabric intent reads information from allocation pool resources, the links between the fabric resource and allocation pool resources are not illustrated in the Transaction Topology.

Some elements in the illustration represent a group of resources. Click the + at the upper right of such elements to expand the group and see the complete set of individual resources.

Additional information about any selected element or connection within the transaction topology is available from the Information panel.

Adding a resource configuration to a transaction

  1. Create any resource in the EDA GUI.
  2. Click Add to Transaction at the bottom of the configuration page.
The configuration for this resource is added as an item in the current transaction. It is not committed until you commit the entire transaction.

Committing a transaction

  1. Click the Basket icon at the top of any page in the EDA GUI.
    Note: When at least one resource is in the basket, the basket icon is highlighted and displays a count of the pending resource changes available to commit.
  2. Optionally, select Dry Run to perform a dry run of this transaction.
    Note: In a Dry Run, the system does not send any of the configuration changes to the managed nodes. However, it executes the transaction against EDA's stored information about each participating node, and validates the transaction against that data.
  3. Optionally, edit any resource configuration that is part of the current transaction by clicking the Edit icon to the right of the transaction. This opens the original resource configuration page so that you can modify the configuration details.
  4. Optionally, remove any resource configurations that are currently part of the transaction that you do not want to commit at this time. Remove a resource by clicking the Minus icon to the right of the transaction.
  5. Click Commit.
EDA commits all of the resource configurations included in the transaction. If any configuration fails, the transaction is halted and rolled back. See the Transactions page for details about transaction success, configurations and nodes affected and any errors that may have occurred.