Aligns with CDS 1.15
[federation.git] / docs / design-notes.rst
1 .. ===============LICENSE_START=======================================================
2 .. Acumos CC-BY-4.0
3 .. ===================================================================================
4 .. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
5 .. ===================================================================================
6 .. This Acumos documentation file is distributed by AT&T and Tech Mahindra
7 .. under the Creative Commons Attribution 4.0 International License (the "License");
8 .. you may not use this file except in compliance with the License.
9 .. You may obtain a copy of the License at
10 ..
11 .. http://creativecommons.org/licenses/by/4.0
12 ..
13 .. This file is distributed on an "AS IS" BASIS,
14 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 .. See the License for the specific language governing permissions and
16 .. limitations under the License.
17 .. ===============LICENSE_END=========================================================
18
19 ==============================
20 Federated Gateway Design Notes
21 ==============================
22
23 The federation gateway is an optional component of an Acumos system whose role
24 is to facilitate communication with other Acumos systems (i.e. with their gateways)
25 or compatible systems (through adapters). Its role is to facilitate the exchange
26 of models and their related information between Acumos instances.
27 The federation gateway occupies the borderline of an Acumos system, from a logical
28 and deployment perspective. From a logical perspective it is the point of control
29 for the flow of model information in and out of an Acumos instance. From a deployment
30 perspective (within an enterprise environment), the federation gateway will be deployed
31 at the edge of the network (DMZ) with communication interfaces towards the enterprise
32 network (where the rest of the Acumos instance components are deployed) and towards
33 the outside world (where other Acumos instances are deployed).
34 We call the external interface (towards the gateways of other Acumos instances) the
35 *federation interface* and we call the internal interface (towards the other components
36 of the same Acumos instance) the *local interface*.
37 The design of the gateway reflects this duality: the gateway defines/offers a set of
38 REST APIs on its federation interface for gateway-2-gateway (or gateway-2-adapter)
39 communication and another set on the local interface for component-2-gateway communication.
40
41 Federation concepts
42
43 The federation gateway behaviour is driven by the peer and subscription information provisioned
44 in the CDS. Through the local interface API other components can trigger gateway
45 behaviour, i.e. trigger interactions with peers. 
46 The peer information represents all other Acumos systems (or other through adapters) this system
47 has agreed to communicate/exchange information with. The 'handshake' procedure by which 2 systems
48 agreed to communicate and provision the required information can take place 'out-of-band' (email,etc
49 + provisining) or 'in-band' (a combination of federation REST API and provisioning actions).
50
51 When enabling federation an Acumos system agrees to share its public, validated models (their
52 revisions) with its peers. (a discussion on ACL driven/selective sharing control will come here later).
53 Establishing a relationship does not in itself imply that any exchange of information takes place.
54 Information exchange (models) is driven by subscriptions provisioned in the local CDS. In Acumos every
55 peer is responsible for pulling from its peers the models it is interested in (such an interaction
56 .goes through the peers' federation gateway who controls/filters access to its local models).
57 A subscription towards a peer represents a subset of that peers' model set that this Acumos is interested in.
58 The subscription information is there to drive the behaviour of the federation gateway (who does
59 the actual peer polling and local provisining of the retrieved information); there is no subscription
60 information shared between peers. An Acumos instance can have multiple subscriptions towards another
61 peer. A subscription can range from one specific model to all the models a peer exposes (with any
62 combination of model level selection criteria in between). A subscription further specifies
63 options such as the frequency with each the federation gateway should check for updates, how much
64 model information should be retrieved every time,etc.
65
66 It is important to notice that the federation gateway mechanisms for model information exchange
67 does not impose an overall peer organization/deployment architecture: tree like structures, fully or sparse
68 connected graphs, etc are all possible.
69
70
71
72 Federation mechanisms
73
74 Before any interaction with a peer can take place the peer information needs to be provisoned
75 in the local CDS. A federation gateway has a dual role, as a server when responding to requests
76 from its peers and as a client when requesting information from them. The federation gateway
77 uses mutual authentication (https,tls), i.e. when a connection is established between 2 gateways
78 both sides need to present their certificates (signed by accepred CAs and so on). The subjectName
79 entry in a certificate received from a peer serves to identify the peer against the locally (CDS)
80 provisioned peer collection (the are no passwords or other credentials provisioned/exchanged).
81
82 The gateway periodically processes the list of locally provisioned peers; where subscriptions
83 towards a peer are found they are assigned to tasks who will query the peer with the given
84 subscription selector. Each resulting model will be compared against locally available
85 model information (in CDS) and new model/new revisions+artifacts will be fetched and provisioned.
86
87 In addition to the model information exchange APIs the federation gateway offers APIs for:
88
89 - status information (ping)
90 - in-band registration
91 - peer information sharing
92
93 Other
94
95 At this point the federation gateway relies on only one Acumos component, the CDS.
96