1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3 .. Copyright (C) 2020 Nordix
5 .. |nbsp| unicode:: 0xA0
8 .. |nbh| unicode:: 0x2011
13 ############################
14 A1 Policy Management Service
15 ############################
18 *******************************************
19 A1 Policy Management Service - Introduction
20 *******************************************
22 The A1 Policy Management Service ("Policy Agent") is an SMO/NONRTRIC service above the NONRTRIC A1 Adaptor/Controller
25 * Unified REST & DMAAP APIs for managing A1 Policies in all Near |nbh| RT |nbsp| RICs
26 * Synchronized view of registered "services" (e.g. R-APP, GUI, etc)
27 * Synchronized view of policy instances for each "service"
28 * Synchronized view of policy instances in all Near |nbh| RT |nbsp| RICs
29 * Synchronized view of policy types in all Near |nbh| RT |nbsp| RICs
30 * Policy Query API (e.g. per Near |nbh| RT |nbsp| RIC, per "service", per policy type)
31 * An initial interface for unified Near |nbh| RT |nbsp| RIC ID to Near |nbh| RT |nbsp| RIC address mapping.
32 (Note: may also later act as adaptor to A&AI, CMDBs etc. to "find" Near |nbh| RT |nbsp| RICs - TBC)
33 * An Initial "O1 ManagedElement" mapping database & interface to find appropriate Near |nbh| RT |nbsp| RIC for RAN elements.
34 (Note: may also later act as adaptor to A&AI, RuntimeDB, other CMDBs etc. - TBC)
35 * Monitors all Near |nbh| RT |nbsp| RICs and recovers from inconsistencies (Note: e.g. Near |nbh| RT |nbsp| RIC restarts)
36 * Support for different Southbound connectors on a per Near |nbh| RT |nbsp| RIC basis. (Note: e.g. different A1
37 versions, different Near |nbh| RT |nbsp| RIC versions, different A1 adapters, different or proprietary A1
40 ***************************************
41 A1 Policy Management Service - REST NBI
42 ***************************************
44 This is the north bound API of the A1 Policy Management Service ("Policy Agent"). This API allows *services* to interact
45 with the Policy Agent using REST.
47 By registering with the Policy Agent, the Policy Agent takes responsibility for synchronizing the policies created by
48 the service in the Near |nbh| RT |nbsp| RICs. This means that if a Near |nbh| RT |nbsp| RIC restarts, the Policy Agent
49 will try to recreate all the policies residing in the Near |nbh| RT |nbsp| RIC once it is started again. If this is not
50 possible, it will remove all policies belonging to the Near |nbh| RT |nbsp| RIC.
52 The Policy Agent also keeps an updated view of the policy types available, and which Near |nbh| RT |nbsp| RICs that
53 support which types. Also, the Policy Agent can tell if a Managed Element is managed by a certain
54 Near |nbh| RT |nbsp| RIC.
56 The Policy Agent NBI has four distinct parts, described in the sections below:
60 * Near-RT RIC Repository
63 .. contents:: Operations
71 A service can register itself in the Policy Agent.
73 By providing a callback URL the service can get notifications from the Policy Agent.
75 A service can also register a "*Keep Alive Interval*", in seconds. By doing this the service promises to call the
76 Policy Agent's "*Keep Alive*" method, or else create or delete policies, more often than the "*Keep Alive Interval*"
77 measured in seconds. If the service, for some reason, is not able to do this, the Policy Agent will consider that the
78 service has died or vanished and will then delete all its policies, both in the internal repository and in the
79 Near |nbh| RT |nbsp| RICs where they were earlier created. **Note!** |nbsp| If the service does not provide a value for
80 "*Keep Alive Interval*", then the service maintains full responsibility to delete all of its policies when they are no
83 Service Management Operations
84 -----------------------------
101 **Body:** (*Required*)
102 A JSON object (ServiceRegistrationInfo): ::
105 "callbackUrl": "string", (An empty string means the service will never get any callbacks.)
106 "keepAliveIntervalSeconds": 0, (0 means the service will always be considered alive.)
107 "serviceName": "string" (Required, must be unique.)
119 The ServiceRegistrationInfo is not accepted.
125 curl -X PUT "http://localhost:8081/service" -H "Content-Type: application/json" -d "{
126 \"callbackUrl\": \"URL\",
127 \"keepAliveIntervalSeconds\": 0,
128 \"serviceName\": \"existing\"
138 curl -X PUT "http://localhost:8081/service" -H "Content-Type: application/json" -d "{}"
143 Missing mandatory parameter 'serviceName'
151 Query service information.
154 /services?name=<service-name>
159 The name of the service.
164 Array of JSON objects (ServiceStatus). ::
167 "callbackUrl": "string", (Callback URL)
168 "keepAliveIntervalSeconds": 0, (Policy keep alive interval)
169 "serviceName": "string", (Identity of the service)
170 "timeSinceLastActivitySeconds": 0 (Time since last invocation by the service)
174 Service is not found.
180 curl -X GET "http://localhost:8081/services?name=existing"
187 "serviceName":"existing",
188 "keepAliveIntervalSeconds":0,
189 "timeSinceLastActivitySeconds":7224,
196 curl -X GET "http://localhost:8081/services?name=nonexistent"
209 /services?name=<service-name>
214 The name of the service.
228 curl -X DELETE "http://localhost:8081/services?name=existing"
237 curl -X DELETE "http://localhost:8081/services?name=nonexistent"
242 Could not find service: nonexistent
250 Heart beat from a service.
253 /services/keepalive?name=<service-name>
258 The name of the service.
266 Service is not found.
272 curl -X PUT "http://localhost:8081/services/keepalive?name=existing"
281 curl -X PUT "http://localhost:8081/services/keepalive?name=nonexistent"
286 Could not find service: nonexistent
288 .. _policy-management:
293 Policies are based on types. The set of available policy types is determined by the set of policy types supported by
294 Near |nbh| RT |nbsp| RICs. At startup, the Policy Agent queries all Near |nbh| RT |nbsp| RICs for their supported types
295 and stores them in its internal repository. It then checks this at regular intervals to keep the repository of types up
296 to date. Policy types cannot be created, updated or deleted using this interface since this must be done via the
297 Near |nbh| RT |nbsp| RICs.
299 Policies can be queried, created, updated, and deleted. A policy is always created in a specific
300 Near |nbh| RT |nbsp| RIC.
302 When a policy is created, the Policy Agent stores information about it in its internal repository. At regular intervals,
303 it then checks with all Near |nbh| RT |nbsp| RICs that this repository is synchronized. If, for some reason, there is an
304 inconsistency, the Policy Agent will start a synchronization job and try to reflect the status of the
305 Near |nbh| RT |nbsp| RIC. If this fails, the Policy Agent will delete all policies for the specific
306 Near |nbh| RT |nbsp| RIC in the internal repository and set its state to *UNKNOWN*. This means that no interaction with
307 the Near |nbh| RT |nbsp| RIC is possible until the Policy Agent has been able to contact it again and re-synchronize its
308 state in the repository.
313 A policy type defines a name and a JSON schema that constrains the content of a policy of that type.
321 Query policy type names.
324 /policy_types?ric=<name-of-ric>
329 The name of the Near |nbh| RT |nbsp| RIC to get types for.
334 Array of policy type names.
337 Near |nbh| RT |nbsp| RIC is not found.
343 curl -X GET "http://localhost:8081/policy_types"
349 "STD_PolicyModelUnconstrained_0.2.0",
350 "Example_QoETarget_1.0.0",
351 "ERIC_QoSNudging_0.2.0"
356 curl -X GET "http://localhost:8081/policy_types?ric=nonexistent"
361 org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
369 Returns one policy type schema definition.
372 /policy_schema?id=<name-of-type>
377 The ID of the policy type to get the definition for.
382 Policy schema as JSON schema.
385 Policy type is not found.
391 curl -X GET "http://localhost:8081/policy_schema?id=STD_PolicyModelUnconstrained_0.2.0"
397 "$schema": "http://json-schema.org/draft-07/schema#",
398 "title": "STD_PolicyModelUnconstrained_0.2.0",
399 "description": "Standard model of a policy with unconstrained scope id combinations",
405 "ueId": {"type": "string"},
406 "groupId": {"type": "string"}
409 "additionalProperties": false
414 "gfbr": {"type": "number"},
415 "mfbr": {"type": "number"}
417 "additionalProperties": false
432 "additionalProperties": false,
433 "required": ["cellIdList"]
438 "additionalProperties": false,
439 "required": ["scope"]
444 curl -X GET "http://localhost:8081/policy_schema?id=nonexistent"
449 org.oransc.policyagent.exceptions.ServiceException: Could not find type: nonexistent
457 Returns policy type schema definitions.
460 /policy_schemas?ric=<name-of-ric>
465 The name of the Near |nbh| RT |nbsp| RIC to get the definitions for.
470 An array of policy schemas as JSON schemas.
473 Near |nbh| RT |nbsp| RIC is not found.
479 curl -X GET "http://localhost:8081/policy_schemas"
485 "$schema": "http://json-schema.org/draft-07/schema#",
486 "title": "STD_PolicyModelUnconstrained_0.2.0",
487 "description": "Standard model of a policy with unconstrained scope id combinations",
495 "additionalProperties": false,
496 "required": ["scope"]
502 "$schema": "http://json-schema.org/draft-07/schema#",
503 "title": "Example_QoETarget_1.0.0",
504 "description": "Example QoE Target policy type",
512 "additionalProperties": false,
513 "required": ["scope"]
517 curl -X GET "http://localhost:8081/policy_schemas?ric=nonexistent"
522 org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
527 A policy is defined by its type schema.
529 Once a service has created a policy, it is the service's responsibility to maintain its life cycle. Since policies are
530 transient, they will not survive a restart of a Near |nbh| RT |nbsp| RIC. But this is handled by the Policy Agent. When
531 a Near |nbh| RT |nbsp| RIC has been restarted, the Policy Agent will try to recreate the policies in the
532 Near |nbh| RT |nbsp| RIC that are stored in its local repository. This means that the service always must delete any
533 policy it has created. There are only two exceptions, see below:
535 - The service has registered a "*Keep Alive Interval*", then its policies will be deleted if it fails to notify the
536 Policy Agent in due time.
537 - The Policy Agent completely fails to synchronize with a Near |nbh| RT |nbsp| RIC.
548 /policies?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-type>
553 The name of the Near |nbh| RT |nbsp| RIC to get policies for.
555 service: (*Optional*)
556 The name of the service to get policies for.
559 The name of the policy type to get policies for.
564 Array of JSON objects (PolicyInfo). ::
567 "id": "string", (Identity of the policy)
568 "json": "object", (The configuration of the policy)
569 "lastModified": "string", (Timestamp, last modification time)
570 "ric": "string", (Identity of the target Near |nbh| RT |nbsp| RIC)
571 "service": "string", (The name of the service owning the policy)
572 "type": "string" (Name of the policy type)
576 Near |nbh| RT |nbsp| RIC or policy type not found.
582 curl -X GET "http://localhost:8081/policies?ric=existing"
601 "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
603 "service": "Service 1",
604 "type": "STD_PolicyModelUnconstrained_0.2.0"
613 "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
615 "service": "Service 2",
616 "type": "Example_QoETarget_1.0.0"
622 curl -X GET "http://localhost:8081/policies?type=nonexistent"
627 Policy type not found
635 Returns a policy configuration.
638 /policy?id=<policy-id>
643 The ID of the policy instance.
648 JSON object containing policy information. ::
651 "id": "string", (ID of policy)
652 "json": "object", (JSON with policy data speified by the type)
653 "ownerServiceName": "string", (Name of the service that created the policy)
654 "ric": "string", (Name of the Near |nbh| RT |nbsp| RIC where the policy resides)
655 "type": "string", (Name of the policy type of the policy)
656 "lastModified" (Timestamp, last modification time)
666 curl -X GET "http://localhost:8081/policy?id=Policy 1"
681 "priorityLevel": 268.5,
686 "initialBuffering": 27.75,
692 "ownerServiceName": "Service 1",
694 "type": "STD_PolicyModelUnconstrained_0.2.0",
695 "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT"
700 curl -X GET "http://localhost:8081/policy?id=nonexistent"
710 Create/Update a policy. **Note!** Calls to this method will also trigger "*Keep Alive*" for a service which has a
711 "*Keep Alive Interval*" registered.
714 /policy?id=<policy-id>&ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
719 The ID of the policy instance.
722 The name of the Near |nbh| RT |nbsp| RIC where the policy will be created.
724 service: (*Required*)
725 The name of the service creating the policy.
728 The name of the policy type.
730 **Body:** (*Required*)
731 A JSON object containing the data specified by the type.
742 Near |nbh| RT |nbsp| RIC or policy type is not found.
745 Near |nbh| RT |nbsp| RIC is not operational.
751 curl -X PUT "http://localhost:8081/policy?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
752 -H "Content-Type: application/json"
756 \"cellId\": \"Cell 1\"
761 \"priorityLevel\": 268.5,
766 \"initialBuffering\": 27.75,
767 \"reBuffFreq\": 539.0,
768 \"stallRatio\": 343.0
779 Deletes a policy. **Note!** Calls to this method will also trigger "*Keep Alive*" for a service which has a
780 "*Keep Alive Interval*" registered.
783 /policy?id=<policy-id>
788 The ID of the policy instance.
799 Near |nbh| RT |nbsp| RIC is not operational.
805 curl -X DELETE "http://localhost:8081/policy?id=Policy 1"
816 Query policy type IDs.
819 /policy_ids?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
824 The name of the Near |nbh| RT |nbsp| RIC to get policies for.
826 service: (*Optional*)
827 The name of the service to get policies for.
830 The name of the policy type to get policies for.
835 Array of policy type names.
838 RIC or policy type not found.
844 curl -X GET "http://localhost:8081/policy_ids"
857 curl -X GET "http://localhost:8081/policy_ids?ric=nonexistent"
870 Returns the status of a policy.
873 /policy_status?id=<policy-id>
878 The ID of the policy.
883 JSON object with policy status.
888 Near-RT RIC Repository
889 ======================
891 The Policy Agent keeps an updated view of the Near |nbh| RT |nbsp| RICs that are available in the system. A service can
892 find out which Near |nbh| RT |nbsp| RIC that manages a specific element in the network or which
893 Near |nbh| RT |nbsp| RICs that support a specific policy type.
904 Returns the name of a Near |nbh| RT |nbsp| RIC managing a specific Mananged Element.
907 /ric?managedElementId=<id-of-managed-element>
911 managedElementId: (*Required*)
912 The ID of the Managed Element.
917 Name of the Near |nbh| RT |nbsp| RIC managing the Managed Element.
920 No Near |nbh| RT |nbsp| RIC manages the given Managed Element.
926 curl -X GET "http://localhost:8081/ric?managedElementId=Node 1"
935 curl -X GET "http://localhost:8081/ric?managedElementId=notmanaged"
946 Query Near |nbh| RT |nbsp| RIC information.
949 /rics?policyType=<name-of-policy-type>
953 policyType: (*Optional*)
954 The name of the policy type.
959 Array of JSON objects containing Near |nbh| RT |nbsp| RIC information. ::
963 "managedElementIds": [
975 Policy type is not found.
981 curl -X GET "http://localhost:8081/rics?policyType=STD_PolicyModelUnconstrained_0.2.0"
988 "managedElementIds": [
993 "STD_PolicyModelUnconstrained_0.2.0",
994 "Example_QoETarget_1.0.0",
995 "ERIC_QoSNudging_0.2.0"
1004 "managedElementIds": [
1008 "STD_PolicyModelUnconstrained_0.2.0"
1011 "state": "UNAVAILABLE"
1017 curl -X GET "http://localhost:8081/rics?policyType=nonexistent"
1022 Policy type not found
1027 The status of the Policy Agent.
1038 Returns the status of the Policy Agent.
1056 curl -X GET "http://localhost:8081/status"
1065 The Policy Agent also provides the possibility to use DMaap to handle policies according to the A1 specification. The
1066 Policy Agent polls the DMaaP Message Router regularly and processes any messages targeted to it. The response is then
1067 published back to the DMaaP Message Router with the result of the call.
1072 The message to send is a JSON like the one below. The "*url*" is one of the URLs described under
1073 :ref:`policy-management`. The "*target*" must always be "*policy-agent*" for the message to be processed by the Policy
1074 Agent. The "*operation*" can be one of the following: "*GET | PUT | POST | DELETE*". ::
1078 "correlationId": "string",
1080 "timestamp": "timestamp",
1081 "apiVersion": "string",
1082 "originatorId": "string",
1083 "requestId": "string",
1084 "operation": "string",
1091 To get all policy types for a specific Near |nbh| RT |nbsp| RIC the following message should be sent to DMaaP Message
1096 "correlationId":"c09ac7d1-de62-0016-2000-e63701125557-201",
1097 "target":"policy-agent",
1098 "timestamp":"2019-05-14T11:44:51.36Z",
1100 "originatorId":"849e6c6b420",
1101 "requestId":"23343221",
1103 "url":"/policy_schemas?ric=ric_ric-simulator_1"
1109 The message the Policy Agent sends back to the DMaaP Message Router is a JSON like the one below. The "*requestId*"
1110 "*correlationId*", and "*originatorId*" are the same as in the message sent to DMaaP MR. ::
1113 "requestId": "string",
1114 "correlationId": "string",
1115 "originatorId": "string",
1117 "message": "string",
1119 "timestamp": "string",
1126 The response containing all policy types for a specific Near |nbh| RT |nbsp| RIC sent to the DMaaP Message Router from
1127 the Policy Agent: ::
1130 \"requestId\":\"23343221\",
1131 \"correlationId\":\"c09ac7d1-de62-0016-2000-e63701125557-201\",
1132 \"originatorId\":\"849e6c6b420\",
1133 \"type\":\"response\",
1136 \\\"$schema\\\":\\\"http://json-schema.org/draft-07/schema#\\\",
1137 \\\"description\\\":\\\"QoS policy type\\\",
1138 \\\"title\\\":\\\"STD_QoSNudging_0.2.0\\\",
1139 \\\"type\\\":\\\"object\\\",
1140 \\\"properties\\\":{\\\"scope\\\":{\\\"additionalProperties\\\":true,
1141 \\\"type\\\":\\\"object\\\",
1142 \\\"properties\\\":{\\\"qosId\\\":{\\\"type\\\":\\\"string\\\"},
1143 \\\"ueId\\\":{\\\"type\\\":\\\"string\\\"}},
1144 \\\"required\\\":[\\\"ueId\\\",
1146 \\\"statement\\\":{\\\"additionalProperties\\\":false,
1147 \\\"type\\\":\\\"object\\\",
1148 \\\"properties\\\":{\\\"priorityLevel\\\":{\\\"type\\\":\\\"number\\\"}},
1149 \\\"required\\\":[\\\"priorityLevel\\\"]}}
1152 \"timestamp\":\"2019-05-14T11:44:51.36Z\",
1153 \"status\":\"200 OK\"