Policy Administration Point (PAP) Architecture

The PAP keeps track of PDPs, supporting the deployment of PDP groups and the deployment of a policy set across those PDP groups. Policies are created using the Policy API, but are deployed via the PAP.

A PAP is stateless in a RESTful sense, using the database (persistent storage) to track PDPs and the deployment of policies to those PDPs. In short, policy management on PDPs is the responsibility of PAPs; management of policy sets or policies by any other manner is not permitted.

Because the PDP is the main unit of scalability in the Policy Framework, the framework is designed to allow PDPs in a PDP group to arbitrarily appear and disappear and for policy consistency across all PDPs in a PDP group to be easily maintained. The PAP is responsible for controlling the state across the PDPs in a PDP group. The PAP interacts with the Policy database and transfers policy sets to PDPs.

There are a number of rules for PDP group and PDP state management:

  1. Only one version of a PDP group may be ACTIVE at any time
  2. If a PDP group with a certain version is ACTIVE and a later version of the same PDP group is activated, then the system upgrades the PDP group
  3. If a PDP group with a certain version is ACTIVE and an earlier version of the same PDP group is activated, then the system downgrades the PDP group
  4. There is no restriction on the number of PASSIVE versions of a PDP group that can exist in the system

1 APIs

The APIs in the subchapters below are supported by the PAP.

1.1 REST API

The purpose of this API is to support CRUD of PDP groups and subgroups and to support the deployment and life cycles of policies on PDP sub groups and PDPs. This API is provided by the PolicyAdministration component (PAP) of the Policy Framework, see the ONAP Policy Framework Architecture page.

PDP groups and subgroups may be prefedined in the system. Predefined groups and subgroups may be modified or deleted over this API. The policies running on predefined groups or subgroups as well as the instance counts and properties may also be modified.

A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. The PDP sends this information to the PAP when it starts. If the PDP group, subgroup, or any policy is unknown to the PAP, the PAP locks the PDP in state PASSIVE.

PAP supports the operations listed in the following table, via its REST API:

Operation Description
Health check Queries the health of the PAP
Statistics Queries various statistics
PDP state change Changes the state of all PDPs in a PDP Group
PDP Group create/update Creates/updates PDP Groups
PDP Group delete Deletes a PDP Group
PDP Group query Queries all PDP Groups
Deploy policy Deploys one or more policies to the PDPs
Undeploy policy Undeploys a policy from the PDPs

1.2 DMaaP API

PAP interacts with the PDPs via the DMaaP Message Router. The messages listed in the following table are transmitted via DMaaP:

Message Direction Description
PDP status Incoming Registers a PDP with PAP; also sent as a periodic heart beat; also sent in response to requests from the PAP
PDP update Outgoing Assigns a PDP to a PDP Group and Subgroup; also deploys or undeploys policies from the PDP
PDP state change Outgoing Changes the state of a PDP or all PDPs within a PDP Group or Subgroup

2 PAP REST API Swagger

It is worth noting that we use basic authorization for access with user name and password set to healthcheck and zb!XztG34, respectively.

For every call, the client is encouraged to insert a uuid-type requestID as parameter. It is helpful for tracking each http transaction and facilitates debugging. More importantly, it complies with Logging requirements v1.2. If the client does not provide the requestID in a call, one will be randomly generated and attached to the response header, x-onap-requestid.

In accordance with ONAP API Common Versioning Strategy Guidelines, several custom headers are added in the response to each call:

Header Example value Description
x-latestversion 1.0.0 latest version of the API
x-minorversion 0 MINOR version of the API
x-patchversion 0 PATCH version of the API
x-onap-requestid e1763e61-9eef-4911-b952-1be1edd9812b described above; used for logging purposes

HealthCheck

GET /policy/pap/v1/healthcheck

Perform healthcheck

  • Produces: [u’application/json’]
  • Description: Returns healthy status of the Policy Administration component

Parameters

Name Position Description Type

Responses

200 - successful operation

403 - Authorization Error

500 - Internal Server Error

401 - Authentication Error

This operation performs a health check on the PAP.

Statistics

GET /policy/pap/v1/statistics

Fetch current statistics

  • Produces: [u’application/json’]
  • Description: Returns current statistics of the Policy Administration component

Parameters

Name Position Description Type

Responses

200 - successful operation

403 - Authorization Error

500 - Internal Server Error

401 - Authentication Error

This operation allows statistics for PDP groups, PDP subgroups, and individual PDPs to be retrieved.

Note

While this API is supported, most of the statistics are not currently updated; that work has been deferred to a later release.

PdpGroupStateChange

PUT /policy/pap/v1/pdps/groups/{name}

Change state of a PDP Group

  • Produces: [u’application/json’]
  • Description: Changes state of PDP Group, returning optional error details

Parameters

Name Position Description Type
X-ONAP-RequestID header RequestID for http transaction string
name path PDP Group Name string
state query PDP Group State string

Responses

200 - successful operation

403 - Authorization Error

500 - Internal Server Error

401 - Authentication Error

The state of PDP groups is managed by this operation. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full description of PDP group states, see the ONAP Policy Framework Architecture page.

PdpGroupDeploy

POST /policy/pap/v1/pdps

Deploy or update PDP Groups

  • Produces: [u’application/json’]
  • Description: Deploys or updates a PDP Group, returning optional error details

Parameters

Name Position Description Type
X-ONAP-RequestID header RequestID for http transaction string
body body List of PDP Group Configuration

Responses

200 - successful operation

403 - Authorization Error

500 - Internal Server Error

401 - Authentication Error

This operation allows the PDP groups and subgroups to be created and updated. Many PDP groups can be created or updated in a single POST operation by specifying more than one PDP group in the POST operation body.

Note

Due to current limitations, if a subgroup is to be deleted from a PDP Group, then the policies must be removed from the subgroup in one request, and then the subgroup deleted in a subsequent request.

PdpGroupDelete

DELETE /policy/pap/v1/pdps/groups/{name}

Delete PDP Group

  • Produces: [u’application/json’]
  • Description: Deletes a PDP Group, returning optional error details

Parameters

Name Position Description Type
X-ONAP-RequestID header RequestID for http transaction string
name path PDP Group Name string

Responses

200 - successful operation

403 - Authorization Error

500 - Internal Server Error

401 - Authentication Error

The API also allows PDP groups to be deleted. DELETE operations are only permitted on PDP groups in PASSIVE state.

PdpGroupQuery

GET /policy/pap/v1/pdps

Query details of all PDP groups

  • Produces: [u’application/json’]
  • Description: Queries details of all PDP groups, returning all group details

Parameters

Name Position Description Type
X-ONAP-RequestID header RequestID for http transaction string

Responses

200 - successful operation

403 - Authorization Error

500 - Internal Server Error

401 - Authentication Error

This operation allows the PDP groups and subgroups to be listed as well as the policies that are deployed on each PDP group and subgroup.

PdpPolicyDeploy

POST /policy/pap/v1/pdps/policies

Deploy or update PDP Policies

  • Produces: [u’application/json’]
  • Description: Deploys or updates PDP Policies, returning optional error details

Parameters

Name Position Description Type
X-ONAP-RequestID header RequestID for http transaction string
body body PDP Policies; only the name is required

Responses

200 - successful operation

403 - Authorization Error

500 - Internal Server Error

401 - Authentication Error

This operation allows policies to be deployed on PDP groups.

Note

The policy version is optional. If left unspecified, then the latest version of the policy is deployed. On the other hand, if it is specified, it may be an integer, or it may be a fully qualified version (e.g., “3.0.2”).

PdpPolicyUndeploy

DELETE /policy/pap/v1/pdps/policies/{name}/versions/{version}

Undeploy version of a PDP Policy from PDPs

  • Produces: [u’application/json’]
  • Description: Undeploys a specific version of a policy from the PDPs, returning optional error details

Parameters

Name Position Description Type
X-ONAP-RequestID header RequestID for http transaction string
name path PDP Policy Name string
version path PDP Policy Version string

Responses

200 - successful operation

403 - Authorization Error

500 - Internal Server Error

401 - Authentication Error

DELETE /policy/pap/v1/pdps/policies/{name}

Undeploy a PDP Policy from PDPs

  • Produces: [u’application/json’]
  • Description: Undeploys the latest version of a policy from the PDPs, returning optional error details

Parameters

Name Position Description Type
X-ONAP-RequestID header RequestID for http transaction string
name path PDP Policy Name string

Responses

200 - successful operation

403 - Authorization Error

500 - Internal Server Error

401 - Authentication Error

This operation allows policies to be undeployed from PDP groups.

Note

If the policy version is specified, then it may be an integer, or it may be a fully qualified version (e.g., “3.0.2”). On the other hand, if left unspecified, then the latest deployed version will be undeployed.

Note

Due to current limitations, a fully qualified policy version must always be specified.

3.1 Order Health Check on PDPs

This operation will allow a PDP group health check to be ordered on PDP groups and on individual PDPs. The operation will return a HTTP status code of 202: Accepted if the health check request has been accepted by the PAP. The PAP will then order execution of the health check on the PDPs.

As health checks may be long lived operations, Health checks will be scheduled for execution by this operation. Users will check the result of a health check test by issuing a PDP Group Query operation and checking the healthy field of PDPs.

End of Document