From 18b941b5bae216c8edf17fce355569911266dfdc Mon Sep 17 00:00:00 2001 From: "Tschaen, Brendan" Date: Fri, 23 Nov 2018 16:59:43 -0500 Subject: [PATCH] Add Music architecture Change-Id: I07f7d2418d606c758b83fd5fffae289bbe930fbc Issue-ID: MUSIC-193 Signed-off-by: Tschaen, Brendan --- docs/MUSIC_USAGE.jpg | Bin 0 -> 47005 bytes docs/architecture.rst | 50 +++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 45 insertions(+), 5 deletions(-) create mode 100644 docs/MUSIC_USAGE.jpg diff --git a/docs/MUSIC_USAGE.jpg b/docs/MUSIC_USAGE.jpg new file mode 100644 index 0000000000000000000000000000000000000000..66773c6cc05f5701f08bbd41f46b0bcae5c1d375 GIT binary patch literal 47005 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ȵPl7%-V~66IQFNO3jS9Bf`n-( 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%0D=h@9LInnT&`yZ802A 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 WY$!s!Txbyh|Hw%xNtTG~`TRe5;>auj literal 0 HcmV?d00001 diff --git a/docs/architecture.rst b/docs/architecture.rst index ae29f9e0..f78db7bb 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -4,16 +4,56 @@ Architecture ============ -` See ONAP Wiki `_ +Project Description +------------------- +To achieve 5 9s of availability on 3 9s or lower software and infrastructure in a cost-effective manner, ONAP components need to work in a reliable, active-active manner across multiple sites (platform-maturity resiliency level 3). A fundamental aspect of this is state management across geo-distributed sites in a reliable, scalable, highly available and efficient manner. This is an important and challenging problem because of three fundamental reasons: -Capabilities +- Current solutions for state-management of ONAP components like MariaDB clustering, that work very effectively within a site, may not scale across geo-distributed sites (e.g., Beijing, Amsterdam and Irvine) or allow partitioned operation (thereby compromising availability). This is mainly because WAN latencies are much higher across sites and frequent network partitions can occur. + +- ONAP components often have a diverse range of requirements in terms of state replication. While some components need to synchronously manage state across replicas, others may tolerate asynchronous replication. This diversity needs to be leveraged to provide better performance and higher availability across sites. + +- ONAP components often need to partition state across different replicas, perform consistent operations on them and ensure that on failover, the new owner has access to the latest state. The distributed protocols to achieve such consistent ownership is complex and replete with corners cases, especially in the face of network partitions. Currently, each component is building its own handcrafted solution which is wasteful and worse, can be erroneous. + +In this project, we identify common state management concerns across ONAP components and provide a multi-site state coordination/management service (MUSIC) with a rich suite of recipes that each ONAP component can simply configure and use for their state-management needs. + + +Functionality +------------- + +At its core, MUSIC provides a scalable sharded eventually-consistent data-store (Cassandra) wherein the access to the keys can be protected using a locking service (built on Zookeeper) that is tightly coupled with the data-store. ONAP components can use the MUSIC API directly to store and access their state across geo-distributed sites. This API enables ONAP components to achieve fine-grained flexible consistency on their state. + +MUSIC also provides a rich set of recipes (mdbc, prom, musicCAS, musicQ) that ONAP components can use to build multi-site active-active/active-passive/federated state-management solutions: + +- mdbc: The most crucial recipe is a multi-site database cache (mdbc) that enable ONAP components that maintain state in a SQL database to avail the benefits of MUSIC without compromising their need to use transactional SQL DBs. These ONAP components can rely on existing db clustering techniques like MariaDB for transactionality and complex querying within a site. mdbc will intercept each of these read/write calls to the db cluster and mirror this state to other geo-distributed sites through MUSIC either synchronously or asynchronously (configurable at a table-level). For example, components like the ONAP Service Orchestrator that use MariaDB to maintain state can directly use this recipe with no change to their SQL code. + +- prom: MUSIC provides a recipe for policy-driven ownership management (prom) of state for ONAP components to (1) partition state across replicas during both initial placement and during failures based on their individual policies (2) ensure correct transfer of state ownership across replicas during site failures and network partitions (3) ensure that the new owner has access to the most recent version of state (if needed). + +- musicCAS: The distributed compare and set is a powerful primitive that will allow ONAP components to update shared state in an atomic manner. This is currently being used by the ONAP HAS (homing service) that is structured a job scheduler with multiple workers trying to pick up client-submitted jobs, while ensuring that only one of them actually performs the job. + +- musicQ: Implementing a geo-distributed queue is a hard problem with many performance implications when data belonging to a queue is sharded across nodes. MUSIC provides a queue API that carefully structures the data to ensure good performance. ONAP HAS (mentioned above) uses this as its job queue. + + +Scope +----- +MUSIC is a shared service with recipes that individual ONAP components and micro-service can use for state replication, consistency management and state ownership across geo-distributed sites. MUSIC will make sure that the right service data is available at the right place, and at the right time to enable federated active-active operation of ONAP. For example, we envisage the use of MUSIC for multi-site state management in SO (to store Camunda state across sites), (to store ODL related state across sites) , A&AI (to store its graph data) and most other ONAP components that need to manage state across sites. + + +Out of Scope ------------ +While MUSIC is an optional solution for state-management of ONAP components across sites, OOM will continue to manage component level and platform level deployment, scalability, redundancy, resiliency, self-healing and high availability on top of Kubernetes across sites for ONAP. -Usage Scenarios ---------------- +Usage +----- +MUSIC and its recipes export a REST API apart from mdbc which is implemented as a jdbc driver to enable seamless integration with SQL-based ONAP components. -Interactions + +Architecture ------------ +The figures below how MUSIC can be used in a general context and also provide a specific example of its potential usage in ONAP SO. + +.. image:: MUSIC_USAGE.jpg + + -- 2.16.6