Transactions#

Introduction#

Transactions form the foundation of EDA's powerful revision control system and add sought-after reliability to infrastructure automation by applying the changes atomically, network-wide.
Every action that leads to a config change in EDA - modifying a resource, installing an EDA application, upgrading a network operating system - is processed as a transaction.

At a very high-level, EDA transactions have three main steps:

1. Generate config from abstractions
2. Deploy config changes, network-wide
3. Commit to Git for revision control

In EDA, deploy and commit are inseparable. If the change is not deployable on any of the target node, the whole transaction is pronounced failed and the changes are reverted from all nodes. This means users can't commit changes that the network can't apply — every commit to Git is a point-in-time of the network's configuration history.¹
With a single command, you can roll back the entire network from the commit history. Your maintenance window back out just got a whole lot easier!

What's in a Transaction Commit?#

Whenever you create/update/delete a resource in EDA, a number of scripts associated with this resource run. We call these scripts "intents".

Intents have strict idempotency where every intent run with the same set of inputs will result in the same set of outputs. Always. Therefore EDA has no need to persistently store anything that can be derived or computed.
EDA stores intent scripts, input resources, and pool allocations in Git - and that's it!³

Yes, that's right, EDA does not backup node configs - we simply don't need them for revision control and omitting those large repetitive files lets us scale the Git repo to very large networks.

Transaction Basket#

Multiple EDA resource changes can be applied together to fate-share a set of changes. The EDA UI uses a basket to represent this. When committing from the basket all resources are applied as a single transaction - if the transaction fails, none of the changes from the basket are committed.

For REST API and Kubernetes users, the basket concept can be used via the Transaction API and the Transaction CRD, respectively.

Transaction Results#

Summary#

EDA stores the result of a transaction for users to review. Here is some of the terminology you'll find in the results:

• Input Resources - Resources created, updated or deleted by the user.
• Intent Runs - Configuration scripts executed during the transaction.
• Output Resources - Resources derived from the intent run.
• Changed Resources - Input and Output resources that are changed, compared to the previous committed transaction.
• Nodes with Changes - Nodes which are impacted by this transaction. This includes node configuration changes, node version changes, or changes to the associated TopoNode resource in EDA.

Error Types:

• Intent Errors - Errors returned by an intent script
• Node Config Errors - Error in YANG schema validation or errors returned by the node when pushing configuration
• General Errors - Errors related to the EDA environment

Diffs#

Diff of all changed resources and changed node configurations in the transaction.

Transaction Topology#

Transaction Topology displays all input and output resources of a transaction and graphs the relationship between derived and parent resources.

Changed resources are colored yellow in the topology, and if an intent error occurred during the transaction the related resource is colored red.

Detail Level#

For all transactions committed to Git, EDA can always display the input resources and their diffs.
Data not in Git (e.g. failed transaction, dry-run transactions, output resources, node configuration diffs, etc.) are stored in-memory for a limited time. EDA uses the following rules for retaining detailed transaction results:

• Keep a guaranteed 25 transactions per user⁴
• Keep diffs for a maximum 10k resources per user — details from the oldest transactions will be purged if this limit is exceeded

Additionally, transactions from 'machine interfaces' do not contain detailed results. This includes resource changes via the /apps REST API endpoint and changes via Kubernetes.

The NodeConfig Resource#

NodeConfig is a special resource in EDA that is not published to EDB or Kubernetes but you will often see in transaction results. These function as an internal configlet which intent scripts create to contribute specific sections of node configuration. EDA combines all the nodeConfig resources into a complete node configuration. This is why you'll see both 'NodeConfig' and 'Node Configuration' in the transaction diffs.

Dry-Run#

What if you want to review the configuration changes before pushing to the network? That's where dry-run comes in. Any transaction can be executed as a dry run. This performs all config generation and YANG schema validation, but does not push any changes to the network.

Revert and Restore#

EDA exposes 'Revert' and 'Restore' actions for each committed transaction:

• Revert sets all the input resources from a specific transaction back to the previous commit. Note: If changes were made to the resource in a more recent transaction, those changes will also be reverted.
• Restore sets all EDA resources, apps, and allocations to exactly as they were at the specified commit.

Both actions are executed as a new transaction and committed with a new commit hash, i.e., the commit history always moves forward even if the transaction is a roll-back of changes.