docs/overview.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3
   4 Overview
   5 ========
   6
   7 The RAN Intelligent Controller (RIC) Platform's A1 Mediator component
   8 listens for policy type and policy instance requests sent via HTTP
   9 (the "northbound" interface), and publishes those requests to running
  10 xApps via RMR messages (the "southbound" interface).
  11
  12 Code
  13 ----
  14
  15 Code is managed in this Gerrit repository:
  16
  17 https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/a1
  18
  19
  20 Policy Overview
  21 ----------------
  22
  23 There are two "object types" associated with policy: policy types and
  24 policy instances.
  25
  26 Policy Types
  27 ~~~~~~~~~~~~
  28
  29 Policy types define the name, description, and most importantly the
  30 schema of all instances of that type.  Think of policy types as
  31 defining a JSON schema for the messages sent from A1 to xapps.  Xapps
  32 do not receive policy types from A1; types are used only by A1 to
  33 validate instance creation requests.  However, xapps must register to
  34 receive instances of type ids in their xapp descriptor.  Xapp
  35 developers can also create new policy types, though the exact process
  36 of where these are stored is still TBD.  For practical purposes, when
  37 the RIC is running, A1s API needs to be invoked to load the policy
  38 types before instances can be created.  Xapps can "sign up" for
  39 multiple policy types using their xapp descriptor.
  40
  41 Policy Instances
  42 ~~~~~~~~~~~~~~~~
  43
  44 Policy instances are concrete instantiations of a policy type. They
  45 give concrete values of a policy.  There may be many instances of a
  46 single type. Whenever a policy instance is created in A1, messages are
  47 sent over RMR to all xapps registered for that policy type; see below.
  48 Xapps are expected to handle multiple simultaneous instances of each
  49 type that they are registered for.
  50
  51
  52 Known differences from A1 1.0.0 spec
  53 ------------------------------------
  54
  55 This is a list of some of the known differences between the API here
  56 and the a1 spec dated 2019.09.30.  In some cases, the spec is
  57 deficient and RIC is "ahead", in other cases this does not yet conform
  58 to recent spec changes.
  59
  60 #. [RIC is ahead] There is no notion of policy types in the spec,
  61    however this aspect is quite critical for the intended use of the
  62    RIC, where many Xapps may implement the same policy, and new Xapps
  63    may be created often that define new types. Moreover, policy types
  64    define the schema for policy instances, and without types, A1
  65    cannot validate whether instances are valid, which the RIC A1m
  66    does. The RIC A1 Mediator view of things is that, there are a set
  67    of schemas, called policy types, and one or more instances of each
  68    schema can be created. Instances are validated against types. The
  69    spec currently provides no mechanism for the implementation of A1
  70    to know whether policy [instances] are correct since there is no
  71    schema for them. This difference has the rather large consequence
  72    that none of the RIC A1m URLs match the spec.
  73 #. [RIC is ahead] There is a rich status URL in the RIC A1m for policy
  74    instances, but this is not in the spec.
  75 #. [RIC is ahead] There is a state machine for when instances are
  76    actually deleted from the RIC (at which point all URLs referencing
  77    it are a 404); this is a configurable option when deploying the RIC
  78    A1m.
  79 #. [CR coming to spec] The spec contains a PATCH for partially
  80    updating a policy instance, and creating/deleting multiple
  81    instances, however the team agreed to remove this from a later
  82    version of the Spec. The RIC A1m does not have this operation.
  83 #. [Spec is ahead] The RIC A1 PUT bodies for policy instances do not
  84    exactly conform to the "scope" and "statements" block that the spec
  85    defines. They are very close otherwise, however.   (I would argue
  86    some of the spec is redundant; for example "policy [instance] id"
  87    is a key inside the PUT body to create an instance, but it is
  88    already in the URL.)
  89 #. [Spec is ahead] The RIC A1m does not yet notify external clients
  90    when instance statuses change.
  91 #. [Spec is ahead] The spec defines that a query of all policy
  92    instances should return the full bodies, however right now the RIC
  93    A1m returns a list of IDs (assuming subsequent queries can fetch
  94    the bodies).
  95 #. [?] The spec document details some very specific "types", but the
  96    RIC A1m allows these to be loaded in (see #1). For example, spec
  97    section 4.2.6.2. We believe this should be removed from the spec
  98    and rather defined as a type. Xapps can be created that define new
  99    types, so the spec will quickly become "stale" if "types" are
 100    defined in the spec.
 101
 102
 103 Resiliency
 104 ----------
 105
 106 A1 is resilient to the majority of failures, but not all currently
 107 (though a solution is known).
 108
 109 A1 uses the RIC SDL library to persist all policy state information:
 110 this includes the policy types, policy instances, and policy statuses.
 111 If state is built up in A1, and A1 fails (where Kubernetes will then
 112 restart it), none of this state is lost.
 113
 114 The tiny bit of state that *is currently* in A1 (volatile) is its
 115 "next second" job queue.  Specifically, when policy instances are
 116 created or deleted, A1 creates jobs in a job queue (in memory).  An
 117 rmr thread polls that thread every second, dequeues the jobs, and
 118 performs them.
 119
 120 If A1 were killed at *exactly* the right time, you could have jobs
 121 lost, meaning the PUT or DELETE of an instance wouldn't actually take.
 122 This isn't drastic, as the operations are idempotent and could always
 123 be re-performed.
 124
 125 In order for A1 to be considered completely resilient, this job queue
 126 would need to be moved to SDL.  SDL uses Redis as a backend, and Redis
 127 natively supports queues via LIST, LPUSH, RPOP.  I've asked the SDL
 128 team to consider an extension to SDL to support these Redis
 129 operations.