Normalize to one trailing slash on Nexus URL
[federation.git] / docs / design.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 Federation 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
35 We call the external interface (towards the gateways of other Acumos instances) the
36 *federation interface* (or public interface) and we call the internal interface (towards
37 the other components of the same Acumos instance) the *local interface* (or private interface).
38 The design of the gateway reflects this duality: the gateway defines/offers a set of
39 REST APIs on its federation interface for gateway-to-gateway (or gateway-to-adapter)
40 communication and another set on the local interface for component-to-gateway communication.
41
42
43 The public "E5" interface
44 -------------------------
45
46 The federation (public) interface is also known in the Acumos project as the E5 interface.
47 This is a public, REST-based API specification: any system that decides to federate needs to implement it.
48 This interface assumes a pull-based mechanism. 
49 As such, only the ‘server’ side is defined by E5.
50
51 The client side is based on a set of subscriptions, where each subscription defines a set of solutions
52 the client is interested in, through a selector (see :ref:`selecting`), and employs periodic polling to detect new material.
53 This interface defines no shared state, nothing to synchronize; all responsibility resides with the interested party.
54 Requires a pre-provisioned peer on the server side, and uses both client and server authentication (CA based),
55 principal to certificate matching.
56
57
58 The private interface
59 ---------------------
60
61 The private (local) interface is system specific, because a localized mapping of information must be done.
62 In Acumos, this includes interactions with the Common Data Service and Portal components and represents
63 is a one-to-one mapping of solution information and related artifacts.
64 In ONAP, this interacts with the SDC component based on its REST API and
65 requires additional processing, for example transforming an Acumos artifact into a set of SDC Asset Artifacts.
66
67
68 Federation concepts
69 -------------------
70
71 Peer
72 ~~~~
73
74 A federation peer is another system supporting the E5 interface; i.e., another Acumos gateway or an adapter for another system.
75 Peer information is provisioned in CDS.
76
77 Handshake
78 ~~~~~~~~~
79
80 Establishment of a peer relationship (known as a handshake) is done by out-of-band information exchange
81 to obtain and share certificates.  Site administrators with adequate permissions exchange required information: 
82 the E5 REST endpoint coordinates and the expected principal info.  They then proceed with local peer provisioning
83 through the Acumos Portal federation administration page.
84
85 Subscriptions
86 ~~~~~~~~~~~~~
87
88 A federation subscription defines which models an Acumos system is interested in importing from a peer.
89 The subscription is primarily a selector over a peer’s catalog, and can support different scopes,
90 ranging from pinpointing one particular solution to all available solutions.
91 Subscriptions are subject to policies in the peer regarding which models are exposed to whom.
92 Current options on a subscription include the refresh period, 
93 and full (copy everything) vs. by reference (no artifact content is transferred).
94
95 Federating models
96 ~~~~~~~~~~~~~~~~~
97
98 The federation gateway behavior is driven by the peer and subscription information provisioned
99 in the CDS. Through the local interface API other components can trigger gateway
100 behavior, i.e. trigger interactions with peers. 
101 The peer information represents all other Acumos systems (or other through adapters) this system
102 has agreed to communicate/exchange information with. The 'handshake' procedure by which two systems
103 agree to communicate and provision the required information can take place 'out-of-band' (email etc.
104 plus provisioning) or 'in-band' (a combination of federation REST API and provisioning actions).
105
106 When enabling federation an Acumos system agrees to share its public, validated models (their
107 revisions) with its peers.
108 (A discussion on ACL driven/selective sharing control will come here later.)
109 Establishing a relationship does not in itself imply that any exchange of information takes place.
110 Information exchange of (models is driven by subscriptions provisioned in the local CDS.
111 In Acumos every peer is responsible for pulling from its peers the models it is interested in
112 (such an interaction goes through the peer's federation gateway which controls/filters access to its local models).
113 A subscription towards a peer represents a subset of that peer's model set that this Acumos is interested in.
114 The subscription information is there to drive the behavior of the federation gateway (which does
115 the actual peer polling and local provisioning of the retrieved information); no subscription
116 information is shared between peers. An Acumos instance can have multiple subscriptions towards another
117 peer. A subscription can range from one specific model to all the models a peer exposes (with any
118 combination of model level selection criteria in between). A subscription further specifies
119 options such as the frequency with each the federation gateway should check for updates, how much
120 model information should be retrieved every time,etc.
121
122 It is important to notice that the federation gateway mechanisms for model information exchange
123 does not impose an overall peer organization/deployment architecture: tree like structures, fully or sparse
124 connected graphs, etc are all possible.
125
126
127 Federation mechanisms
128 ---------------------
129
130 Before any interaction with a peer can take place the peer information needs to be provisioned
131 in the local CDS. A federation gateway has a dual role, as a server when responding to requests
132 from its peers and as a client when requesting information from them. The federation gateway
133 uses mutual authentication (https, tls), i.e. when a connection is established between two gateways
134 both sides need to present their certificates (signed by accepted CAs and so on). The subjectName
135 entry in a certificate received from a peer serves to identify the peer against the locally (CDS)
136 provisioned peer collection (the are no passwords or other credentials provisioned/exchanged).
137
138 The gateway periodically processes the list of locally provisioned peers; where subscriptions
139 towards a peer are found they are assigned to tasks who will query the peer with the given
140 subscription selector. Each resulting model will be compared against locally available
141 model information (in CDS) and new model/new revisions+artifacts will be fetched and provisioned.
142
143 In addition to the model information exchange APIs the federation gateway offers APIs for:
144
145 - status information (ping)
146 - in-band registration
147 - peer information sharing
148
149
150 Dependencies
151 ------------
152
153 At this point the federation gateway relies on only one Acumos component, the Common Data Service.