From: Murali Parthasarathy K Date: Wed, 11 Jun 2025 07:00:46 +0000 (+0200) Subject: Updates to ONAP Documentation including scalability and security aspect X-Git-Url: https://gerrit.onap.org/r/gitweb?a=commitdiff_plain;h=a6bdbb220195502bfd6c250a5a03e93cf6f0d49d;p=policy%2Fparent.git Updates to ONAP Documentation including scalability and security aspect Issue-ID: POLICY-5382 Change-Id: I01a9e09a2ba1414163a7e8053796f5a54977417e Signed-off-by: Murali Parthasarathy K --- diff --git a/docs/development/prometheus-metrics.rst b/docs/development/prometheus-metrics.rst index e7d4d3a6..44d15830 100644 --- a/docs/development/prometheus-metrics.rst +++ b/docs/development/prometheus-metrics.rst @@ -183,6 +183,32 @@ Key metrics for Policy Distribution | download_failure_count | Total number of download failures | +------------------------------------+-------------------------------------------------------+ +Key metrics for OPA PDP +----------------------------------- + ++------------------------------------------+-----------------------------------------------------------+ +| Metric name | Metric description | ++==========================================+===========================================================+ +| opa_decision_response_time_seconds | Response time of OPA decision handler | ++------------------------------------------+-----------------------------------------------------------+ +| opa_data_response_time_seconds | Response time of OPA data handler | ++------------------------------------------+-----------------------------------------------------------+ +| pdpo_policy_decisions_total | Total Number of Decision Handler hits for OPA | ++------------------------------------------+-----------------------------------------------------------+ +| pdpo_policy_deployments_total | Total Number of Successful Deployment for OPA | ++------------------------------------------+-----------------------------------------------------------+ +| pdpo_policy_failures_total | Total Number of Deployment Failures for OPA | ++------------------------------------------+-----------------------------------------------------------+ +| pdpo_dynamic_data_success_total | Total Number of Successful Dynamic Data Updates for OPA | ++------------------------------------------+-----------------------------------------------------------+ +| pdpo_dynamic_data_failures_total | Total Number of Failed Dynamic Data Updates for OPA | ++------------------------------------------+-----------------------------------------------------------+ +| pdpo_policy_undeployments_success_total | Total Number of Successful Deployment for OPA | ++------------------------------------------+-----------------------------------------------------------+ +| pdpo_policy_undeployments_failures_total | Total Number of Deployment Failures for OPA | ++------------------------------------------+-----------------------------------------------------------+ + + 3. OOM changes to enable prometheus monitoring for Policy Framework =================================================================== diff --git a/docs/opa/OPA-architecture.rst b/docs/opa/OPA-architecture.rst index a6ea42aa..636f6411 100644 --- a/docs/opa/OPA-architecture.rst +++ b/docs/opa/OPA-architecture.rst @@ -23,12 +23,13 @@ Software Architecture .. container:: ulist - - **KafkaListener/Producer**: This component listens for incoming PDP_UPDATE and PDP_STATE_CHANGE messages from PAP. OPA PDP sends PDP_STATUS messages to PAP via Producer. + - **KafkaListener/Producer**: for topic:policy-pdp-pap, OPA PDP listens for incoming PDP_UPDATE and PDP_STATE_CHANGE messages from PAP. OPA PDP sends PDP_STATUS messages to PAP via Producer. + for topic:opa-pdp-data, OPA PDP when scaled up during deployment, every opa instance will produce and listen to OPA_PDP_DATA_PATCH_SYNC messages. - **OPA PDP Engine**: The Go application that decodes base64 TOSCA policies and handles the deployment and undeployment of policies into the OPA SDK. .. container:: ulist - - Msg Processor: Handles incoming PDP_UPDATE and PDP_STATE_CHANGE messages from PAP. + - Msg Processor: Process incoming messages PDP_UPDATE, PDP_STATE_CHANGE, OPA_PDP_DATA_PATCH_SYNC for validation. - PDP STATE: Maintains PDP State Active or Passive. - Policy Map: In Memory Cache that holds the Map of names of policies,policy keys and data keys deployed. - Metrics: Handles statistics of number of policies deployed,success and failure counts and other metrics. @@ -140,6 +141,6 @@ UnDeploy OPA policy 1.0.0-SNAPSHOT Last updated 2025-03-27 16:04:24 IST -.. |OPA PDP Architecture| image:: images/OPA-PDP.drawio.svg +.. |OPA PDP Architecture| image:: images/OPAPDPArchitecture.png :width: 700px - :height: 300px \ No newline at end of file + :height: 300px diff --git a/docs/opa/OPA-dynamic-dataupdate.rst b/docs/opa/OPA-dynamic-dataupdate.rst index 738ee5ae..852cbb27 100644 --- a/docs/opa/OPA-dynamic-dataupdate.rst +++ b/docs/opa/OPA-dynamic-dataupdate.rst @@ -45,7 +45,7 @@ Patch a Document Update a document. OPA_PDP accepts updates encoded as JSON Patch operations. The message body of the request should contain a JSON encoded array containing one or more JSON Patch operations. - Each operation specifies the operation type, path, and an optional value. For more information on JSON Patch, see RFC 6902. + Each operation specifies the operation type, path, and an optional value. For more information on JSON Patch, see `RFC 6902 `__. The effective path of the JSON Patch operation is obtained by joining the path portion of the URL with the path value from the operation(s) contained in the message body. In all cases, the parent of the effective path MUST refer to an existing document, otherwise the server returns 404. In the case of **remove** and **replace** operations, the effective path MUST refer to an existing document, otherwise the server returns 404. @@ -71,6 +71,37 @@ Patch a Document :language: JSON :caption: **add** test json element to data in cell.consistency policy +Dynamic Data Patch Conditions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Rules and Constraints applied when performing dynamic data patch operations in the `policy-opa-pdp` system. These conditions ensure data integrity and policy consistency during runtime updates. + + +Patch Preconditions +^^^^^^^^^^^^^^^^^^^ + +1. **Deployment Requirement** + - The `policyName` provided in the dynamic data patch payload must correspond to a policy that has already been deployed. + - Patching is not permitted for non-existent or undeployed policies. + +2. **Scoped Data Modification** + - If the specified `policyName` exists, the patch operation is restricted to the `data.node` associated with that policy. + - Modifications outside the scope of the associated `data.node` are not allowed. + +3. **Data Type Compatibility** + - If the existing `data.node` is a JSON object: + * New keys of any valid JSON type (object, array, string, boolean, number) may be added. + * These keys will be inserted under the existing JSON object structure. + - If the existing `data.node` is a JSON array: + * The array must be replaced in its entirety. + * Partial additions or modifications are not supported, as they may render the policy non-functional. + +4. **Operation Constraints** + - Patch operations such as `replace` and `remove` are only valid if the target key already exists within the current `data.node`. + - Attempting to modify or remove non-existent keys will result in rejection of the patch request. + + These rules are enforced to maintain the operational stability and correctness of policy evaluations during dynamic updates. + .. warning:: .. container:: paragraph @@ -90,4 +121,4 @@ Patch a Document :name: footer-text 1.0.0-SNAPSHOT - Last updated 2025-03-27 16:04:24 IST \ No newline at end of file + Last updated 2025-03-27 16:04:24 IST diff --git a/docs/opa/OPA-metrics.rst b/docs/opa/OPA-metrics.rst new file mode 100644 index 00000000..e874abf3 --- /dev/null +++ b/docs/opa/OPA-metrics.rst @@ -0,0 +1,66 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +OPA PDP Metrics Overview +************************ + +This document provides a high-level overview of the metrics and statistics functionality implemented in the `policy-opa-pdp` service. The purpose of this module is to collect, manage, and expose operational metrics related to policy decisions and data handling within the OPA PDP (Policy Decision Point) system. + +.. contents:: + :depth: 3 + +Purpose +^^^^^^^ + + .. container:: sectionbody + + .. container:: paragraph + + The metrics module is designed to: + + - Track the success and failure of policy decisions. + - Monitor deployment and undeployment operations. + - Record dynamic data update outcomes. + - Provide real-time statistics for observability and monitoring. + - Integrate with Prometheus for metric collection and visualization. + +Key Features +^^^^^^^^^^^^ + + .. container:: sectionbody + + .. container:: paragraph + + 1. **Metric Counters** + + - The system maintains internal counters for: + - Decision successes and failures + - Deployment and undeployment outcomes + - Dynamic data update results + - Total number of policies + - General error occurrences + + .. csv-table:: + :header: "/statistics" + :widths: 10 + + `Statistics Swagger <./local-swagger.html#tag/OPAPDPDecisionControllerv1>`_ + + 2. **Prometheus Integration** + + - The `policy-opa-pdp` service exposes several Prometheus-compatible metrics to support observability and performance monitoring. These metrics are automatically registered and can be scraped by Prometheus for visualization and alerting. + - Below are some example metrics exposed by the service: + .. csv-table:: + :header: "/metrics" + :widths: 10 + + `Prometheus Metrics `__. + +.. container:: + :name: footer + + .. container:: + :name: footer-text + + 1.0.0-SNAPSHOT + Last updated 2025-03-27 16:04:24 IST diff --git a/docs/opa/OPA-pdp-security.rst b/docs/opa/OPA-pdp-security.rst new file mode 100644 index 00000000..5fa69399 --- /dev/null +++ b/docs/opa/OPA-pdp-security.rst @@ -0,0 +1,76 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +ONAP Policy OPA PDP - OpenSSF Compliance and Security +***************************************************** + +.. contents:: + :depth: 3 + +Overview +^^^^^^^^ + +The `policy-opa-pdp` component is part of the ONAP Policy Framework and plays a critical role in making policy decisions using the Open Policy Agent (OPA). As part of ONAP's commitment to secure and reliable open-source software, this component aligns with the OpenSSF (Open Source Security Foundation) best practices. It is designed with security and compliance in mind, aligning with ONAP's broader goals of secure, policy-driven automation. Its OpenSSF Gold alignment ensures that it meets industry standards for open-source software security and reliability. + +OpenSSF Compliance +^^^^^^^^^^^^^^^^^^ + +The ONAP Policy Framework, including the `policy-opa-pdp`, has achieved **OpenSSF Gold Standard** compliance. This reflects adherence to secure development practices, vulnerability management, and continuous integration standards. + +OPA Policy and Istio Security Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +Service Mesh Security Model +########################### + +Module: ``policy-opa-pdp`` + +External Communication +---------------------- + + - All external requests entering the mesh are secured using **HTTPS**. + - These requests are typically routed through an **Istio Ingress Gateway**, which handles TLS termination and enforces external security policies. + +Internal Service-to-Service Communication +----------------------------------------- + + - Within the mesh, services communicate over **HTTP**. + - **Mutual TLS (mTLS)** is enforced by Istio for all internal traffic, ensuring encryption in transit and service identity verification. + +Authentication && Authorization +------------------------------- + + - Currently, there is **no Role-Based Authorization** implemented within the mesh. + - Access control is limited to basic authentication and mTLS-based identity verification. + + .. container:: imageblock + + .. container:: content + + |OOM SERVICE MESH| + +Security Documentation +^^^^^^^^^^^^^^^^^^^^^^ + +As part of the ONAP **Paris release (May 2025)**, the following security improvements have been implemented: + - All internal communication is secured using **Istio Service Mesh**. + - **Hard-coded credentials** have been removed. + - Kubernetes pods now run with **non-root privileges**. + - Authentication is handled locally using secure secrets. + - Secrets are stored and accessed in a secure manner, avoiding hard-coded values. + - These credentials are strictly local to the pod and have **no external reachability**. + - The entire component is encapsulated within a **secure Istio mesh architecture**, ensuring that all inter-service communication is encrypted and authenticated between microservices. + +.. container:: + :name: footer + + .. container:: + :name: footer-text + + 1.0.0-SNAPSHOT + Last updated 2025-03-27 16:04:24 IST + +.. |OOM SERVICE MESH| image:: images/OPAServiceMesh.png + :width: 500px + :height: 100px diff --git a/docs/opa/OPA-scalability.rst b/docs/opa/OPA-scalability.rst new file mode 100644 index 00000000..eb75d82f --- /dev/null +++ b/docs/opa/OPA-scalability.rst @@ -0,0 +1,81 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +OPA-PDP Scalability Overview +############################ + +This document outlines the scalability mechanisms used by OPA-PDP for both policy and dynamic data synchronization across multiple pods in a distributed environment. + +.. contents:: + :depth: 3 + +OPA-PDP Policy Scalability +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + .. container:: sectionbody + + .. container:: paragraph + + OPA-PDP achieves policy scalability and consistency using Kafka-based synchronization: + - Each OPA-PDP pod subscribes to the Kafka topic ``policy-pdp-pap`` using a **unique consumer group ID**. + - This ensures that **every pod receives all policy messages** independently. + - Policy data remains **synchronized and consistent** across all OPA-PDP replicas. + - This architecture supports **horizontal scaling** using Kubernetes Horizontal Pod Autoscaler (HPA). + + .. container:: imageblock + + .. container:: content + + |OPA PDP SCALABILITY| + + 1. The Policy Administration Point (PAP) publishes policy updates to the Kafka topic ``policy-pdp-pap``. + 2. Multiple OPA-PDP pods, each with a unique Kafka consumer group ID, subscribe to this topic. + 3. Each pod receives and processes the full stream of policy updates independently. + +OPA-PDP Dynamic Data Scalability +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + .. container:: sectionbody + + .. container:: paragraph + + OPA-PDP supports dynamic data updates via REST API and Kafka-based synchronization: + - The REST API allows dynamic data updates at endpoint ``/policy/pdp0/v1/data/node/{path:.+}``. + - Depending on the Helm chart configuration parameter ``useKafkaForPatch``: + + - If **enabled**, the pod: + - Forwards the patch to Kafka topic ``opa-pdp-data``. + - Responds with HTTP status **202**. + - All OPA-PDP pods (with unique consumer group IDs) receive and apply the update. + + - If **disabled**, the pod: + - Applies the update **only locally**. + - Responds with HTTP status **204**. + + .. container:: imageblock + + .. container:: content + + |OPA PDP DYNAMICDATA SCALABILITY| + + 1. An actor sends a PATCH request to an OPA-PDP pod. + 2. If Kafka sync is enabled, the pod forwards the patch to Kafka topic ``opa-pdp-data``. + 3. All OPA-PDP pods subscribed to this topic (e.g., with consumer group IDs ``consGid#2``, ``consGid#3``) receive and apply the update independently. + + This mechanism ensures **eventual consistency** of dynamic data across all replicas when synchronization is enabled. + +.. container:: + :name: footer + + .. container:: + :name: footer-text + + 1.0.0-SNAPSHOT + Last updated 2025-03-27 16:04:24 IST + +.. |OPA PDP SCALABILITY| image:: images/OPAScalability.png + :width: 500px + :height: 100px +.. |OPA PDP DYNAMICDATA SCALABILITY| image:: images/OPADynDataScalability.png + :width: 500px + :height: 100px diff --git a/docs/opa/images/OPADynDataScalability.png b/docs/opa/images/OPADynDataScalability.png new file mode 100755 index 00000000..87f5f651 Binary files /dev/null and b/docs/opa/images/OPADynDataScalability.png differ diff --git a/docs/opa/images/OPAPDPArchitecture.png b/docs/opa/images/OPAPDPArchitecture.png index 850e627d..00ad02c8 100644 Binary files a/docs/opa/images/OPAPDPArchitecture.png and b/docs/opa/images/OPAPDPArchitecture.png differ diff --git a/docs/opa/images/OPAScalability.png b/docs/opa/images/OPAScalability.png new file mode 100755 index 00000000..9f3cd322 Binary files /dev/null and b/docs/opa/images/OPAScalability.png differ diff --git a/docs/opa/images/OPAServiceMesh.png b/docs/opa/images/OPAServiceMesh.png new file mode 100755 index 00000000..220069f6 Binary files /dev/null and b/docs/opa/images/OPAServiceMesh.png differ diff --git a/docs/opa/images/PFHighestLevel.png b/docs/opa/images/PFHighestLevel.png new file mode 100644 index 00000000..92c271f9 Binary files /dev/null and b/docs/opa/images/PFHighestLevel.png differ diff --git a/docs/opa/opa.rst b/docs/opa/opa.rst index cae59dc1..805e4f96 100644 --- a/docs/opa/opa.rst +++ b/docs/opa/opa.rst @@ -12,4 +12,7 @@ Policy OPA PDP Engine OPA-architecture.rst OPA-policy-guide.rst OPA-decision-example.rst - OPA-dynamic-dataupdate.rst \ No newline at end of file + OPA-dynamic-dataupdate.rst + OPA-scalability.rst + OPA-metrics.rst + OPA-pdp-security.rst diff --git a/docs/opa/resources/response_to_pdp_state_change.json b/docs/opa/resources/response_to_pdp_state_change.json index f08cea6b..36e27008 100644 --- a/docs/opa/resources/response_to_pdp_state_change.json +++ b/docs/opa/resources/response_to_pdp_state_change.json @@ -12,7 +12,7 @@ "policies": null, "name": "opa-949018d3-cc9b-429b-96ae-46ca9c314e42", "requestId": "02b186a6-485d-4392-90fa-d4cac34be97a", - "pdpGroup": "defaultGroup", + "pdpGroup": "opaGroup", "pdpSubgroup": "opa", "timestampMs": "1731335550069" -} \ No newline at end of file +} diff --git a/docs/opa/resources/response_to_pdp_update.json b/docs/opa/resources/response_to_pdp_update.json index b1b65702..f73b3239 100644 --- a/docs/opa/resources/response_to_pdp_update.json +++ b/docs/opa/resources/response_to_pdp_update.json @@ -12,8 +12,8 @@ "policies": null, "name": "opa-949018d3-cc9b-429b-96ae-46ca9c314e42", "requestId": "e6a0607f-5fc8-4d62-afca-3cb984d827a3", - "pdpGroup": "defaultGroup", + "pdpGroup": "opaGroup", "pdpSubgroup": "opa", "timestampMs": "1731335550030", "deploymentInstanceInfo":"" -} \ No newline at end of file +}