X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Foverview.rst;h=450e92f8930b09a26b28f39a2543fb59cb54163c;hb=refs%2Fchanges%2F47%2F7547%2F1;hp=45d98ba3c9d243732be02580d8bed83facfbde46;hpb=4249398baf8e9607f4e2a88d214410affc818666;p=ric-plt%2Fa1.git diff --git a/docs/overview.rst b/docs/overview.rst index 45d98ba..450e92f 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -1,12 +1,133 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. SPDX-License-Identifier: CC-BY-4.0 -A1 Mediator -=========== +Overview +======== -API ---- +.. contents:: + :depth: 3 + :local: -You can see the API (OpenAPI3 spec) at ``a1/openapi.yml``. You can also -see the “pretty” version if you run the container at -``http://localhost:10000/ui/``. +The RAN Intelligent Controller (RIC) Platform's A1 Mediator component +listens for policy type and policy instance requests sent via HTTP +(the "northbound" interface), and publishes those requests to running +xApps via RMR messages (the "southbound" interface). + +Code +---- + +Code is managed in this Gerrit repository: + +https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/a1 + + +Policy Overview +---------------- + +There are two "object types" associated with policy: policy types and +policy instances. + +Policy Types +~~~~~~~~~~~~ + +Policy types define the name, description, and most importantly the +schema of all instances of that type. Think of policy types as +defining a JSON schema for the messages sent from A1 to xapps. Xapps +do not receive policy types from A1; types are used only by A1 to +validate instance creation requests. However, xapps must register to +receive instances of type ids in their xapp descriptor. Xapp +developers can also create new policy types, though the exact process +of where these are stored is still TBD. For practical purposes, when +the RIC is running, A1s API needs to be invoked to load the policy +types before instances can be created. Xapps can "sign up" for +multiple policy types using their xapp descriptor. + +Policy Instances +~~~~~~~~~~~~~~~~ + +Policy instances are concrete instantiations of a policy type. They +give concrete values of a policy. There may be many instances of a +single type. Whenever a policy instance is created in A1, messages are +sent over RMR to all xapps registered for that policy type; see below. +Xapps are expected to handle multiple simultaneous instances of each +type that they are registered for. + + +Known differences from A1 1.0.0 spec +------------------------------------ + +This is a list of some of the known differences between the API here +and the a1 spec dated 2019.09.30. In some cases, the spec is +deficient and RIC is "ahead", in other cases this does not yet conform +to recent spec changes. + +#. [RIC is ahead] There is no notion of policy types in the spec, + however this aspect is quite critical for the intended use of the + RIC, where many Xapps may implement the same policy, and new Xapps + may be created often that define new types. Moreover, policy types + define the schema for policy instances, and without types, A1 + cannot validate whether instances are valid, which the RIC A1m + does. The RIC A1 Mediator view of things is that, there are a set + of schemas, called policy types, and one or more instances of each + schema can be created. Instances are validated against types. The + spec currently provides no mechanism for the implementation of A1 + to know whether policy [instances] are correct since there is no + schema for them. This difference has the rather large consequence + that none of the RIC A1m URLs match the spec. +#. [RIC is ahead] There is a rich status URL in the RIC A1m for policy + instances, but this is not in the spec. +#. [RIC is ahead] There is a state machine for when instances are + actually deleted from the RIC (at which point all URLs referencing + it are a 404); this is a configurable option when deploying the RIC + A1m. +#. [CR coming to spec] The spec contains a PATCH for partially + updating a policy instance, and creating/deleting multiple + instances, however the team agreed to remove this from a later + version of the Spec. The RIC A1m does not have this operation. +#. [Spec is ahead] The RIC A1 PUT bodies for policy instances do not + exactly conform to the "scope" and "statements" block that the spec + defines. They are very close otherwise, however. (I would argue + some of the spec is redundant; for example "policy [instance] id" + is a key inside the PUT body to create an instance, but it is + already in the URL.) +#. [Spec is ahead] The RIC A1m does not yet notify external clients + when instance statuses change. +#. [Spec is ahead] The spec defines that a query of all policy + instances should return the full bodies, however right now the RIC + A1m returns a list of IDs (assuming subsequent queries can fetch + the bodies). +#. [?] The spec document details some very specific "types", but the + RIC A1m allows these to be loaded in (see #1). For example, spec + section 4.2.6.2. We believe this should be removed from the spec + and rather defined as a type. Xapps can be created that define new + types, so the spec will quickly become "stale" if "types" are + defined in the spec. + + +Resiliency +---------- + +A1 is resilient to the majority of failures, but not all currently +(though a solution is known). + +A1 uses the RIC SDL library to persist all policy state information: +this includes the policy types, policy instances, and policy statuses. +If state is built up in A1, and A1 fails (where Kubernetes will then +restart it), none of this state is lost. + +The tiny bit of state that *is currently* in A1 (volatile) is its +"next second" job queue. Specifically, when policy instances are +created or deleted, A1 creates jobs in a job queue (in memory). An +rmr thread polls that thread every second, dequeues the jobs, and +performs them. + +If A1 were killed at *exactly* the right time, you could have jobs +lost, meaning the PUT or DELETE of an instance wouldn't actually take. +This isn't drastic, as the operations are idempotent and could always +be re-performed. + +In order for A1 to be considered completely resilient, this job queue +would need to be moved to SDL. SDL uses Redis as a backend, and Redis +natively supports queues via LIST, LPUSH, RPOP. I've asked the SDL +team to consider an extension to SDL to support these Redis +operations.