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