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 configurations individually as you create it. EDA allows you 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 Log button: click to open the Transactions List
2 Configuration selectors: Check or un-check to include a configuration within, or exclude a commit from, the current transaction.
3 Commit Edit button: click to edit a single commit.
4 Transaction options:
  • Discard: discard all items in the transaction basket.
  • Dry Run: perform a dry run to evaluate the effects of the transaction once 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.

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. This 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 nodes.

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 apply the transaction again.

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.

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 checkbox beside any configuration to remove it from the overall transaction.
  • Restore the configuration: Re-check the Configuration selector checkbox beside any un-checked 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 will be 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 4. 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 2. Transaction information
Column Description
Display ID An identifier for the transaction, in the form "Transaction <number>".
Description An optional description provided at the time the transaction is committed.
Username The user who executed the transaction.
Completion Timestamp The date and time the transaction was completed.
Success Whether the transaction was successful, or failed.
State The state of the completed transaction.
Dry Run Whether a Dry Run has been performed for this transaction.

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 string in the EDA repository.
For each row in the Transaction list, a set of actions available from the Table row actions menu:
  • Summary, which opens the EDA Transaction Summary page showing detailed information for one transaction.
  • 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 all input CRs in the transaction.

Transactions summary

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

Figure 5. 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 executes 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 6. 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.

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.