Federation

Corteza Federation is currently in experimental mode and disabled by default, Set the FEDERATION_ENABLED .env variable to true if you wish to enable it.

Corteza Federation enables different Corteza instances to establish a federated network to freely and securely exchange information.

A federated network consists of origin and destination nodes, where each node can fulfil both roles. Take a look at the glossary for a reference on our terminology.

The diagram provides an abstract overview of the entire Corteza Federation system. It consists of three major parts — node pairing (the nodes establish a federated network), structure syncing (the nodes agree on what will be shared), and data syncing (the destination node accesses the data on the origin node).

@startuml
skinparam ParticipantPadding 50
participant "Node A\n(Origin Node)" as NodeA
participant "Node B\n(Destination Node)" as NodeB

== Node pairing ==
NodeA <-> NodeB: Pair nodes.
note over NodeA, NodeB: The two nodes identify and exchange authentication credentials via a node handshake.
...
== Structure syncing ==
NodeA -> NodeA: Expose structures.
note over NodeA
The origin node determines what structures
it wishes to expose to the destination node.
end note
NodeA -> NodeB: Structure sync.

NodeB -> NodeB: Module mapping.
note over NodeB
The destination node determines what fields
from the origin structure it wishes to consume.
The destination node also specifies where
the data should be stored (field mapping).
end note
...
== Data syncing ==
NodeA -> NodeB: Data sync.

@enduml

Glossary

We recommend you firstly go over the glossary so you will understand our terminology. It will help you follow along and understand what we’re talking about.

Security & logging

The security & logging covers how Corteza Federation handles node authentication and protected resource access, RBAC access control facility integration and the action log logging integration.

Node pairing

Node pairing is the process of establishing a federated network between two Corteza instances (nodes).

Corteza Federation defines a node pairing handshake which enables the two nodes to exchange authentication credentials securely.

Node syncing

Node syncing is the process of determining what data the origin node wishes to share, and the actual data syncing between the two nodes.

Node syncing consists of two parts:

structure sync determines the structures that the destination node can access,
data sync syncs the data from the origin node onto the destination node.

API reference

The API reference provides a complete list of available API endpoints with working cURL examples.

Local development

Development notes walk you through how to setup an origin and a destination federated Corteza instance.