Merge pull request #80764 from aireilly/TELCODOCS-1862-O-RAN-API

TELCODOCS-1862 - Adding docs for O-RAN v3 compliant PTP fast events REST API v2

Author: aireilly

_topic_maps/_topic_map.yml

@@ -1376,10 +1376,14 @@ Topics:
     File: about-ptp
   - Name: Configuring PTP hardware
     File: configuring-ptp
-  - Name: Using PTP events
-    File: using-ptp-events
-  - Name: Developing PTP events consumer applications
+  - Name: Developing PTP events consumer applications with the REST API v2
+    File: ptp-cloud-events-consumer-dev-reference-v2
+  - Name: PTP events REST API v2 reference
+    File: ptp-events-rest-api-reference-v2
+  - Name: Developing PTP events consumer applications with the REST API v1
     File: ptp-cloud-events-consumer-dev-reference
+  - Name: PTP events REST API v1 reference
+    File: ptp-events-rest-api-reference
 - Name: External DNS Operator
   Dir: external_dns_operator
   Topics:

images/319_OpenShift_PTP_bare-metal_OCP_nodes_0323_4.17.png

@@ -1,14 +1,21 @@
 // Module included in the following assemblies:
 //
-// * networking/ptp/using-ptp-events.adoc
+// * networking/ptp/about-ptp.adoc
 
 :_mod-docs-content-type: CONCEPT
 [id="cnf-about-ptp-and-clock-synchronization_{context}"]
 = About PTP and clock synchronization error events
 
-Loss of PTP synchronization is a critical error for a RAN network. If synchronization is lost on a node, the radio might be shut down and the network Over the Air (OTA) traffic might be shifted to another node in the wireless network. Fast event notifications mitigate against workload errors by allowing cluster nodes to communicate PTP clock sync status to the vRAN application running in the DU.
+Cloud native applications such as virtual RAN (vRAN) require access to notifications about hardware timing events that are critical to the functioning of the overall network.
+PTP clock synchronization errors can negatively affect the performance and reliability of your low-latency application, for example, a vRAN application running in a distributed unit (DU).
 
-Event notifications are available to vRAN applications running on the same DU node. A publish/subscribe REST API passes events notifications to the messaging bus. Publish/subscribe messaging, or pub-sub messaging, is an asynchronous service-to-service communication architecture where any message published to a topic is immediately received by all of the subscribers to the topic.
+Loss of PTP synchronization is a critical error for a RAN network.
+If synchronization is lost on a node, the radio might be shut down and the network Over the Air (OTA) traffic might be shifted to another node in the wireless network.
+Fast event notifications mitigate against workload errors by allowing cluster nodes to communicate PTP clock sync status to the vRAN application running in the DU.
+
+Event notifications are available to vRAN applications running on the same DU node.
+A publish/subscribe REST API passes events notifications to the messaging bus.
+Publish/subscribe messaging, or pub-sub messaging, is an asynchronous service-to-service communication architecture where any message published to a topic is immediately received by all of the subscribers to the topic.
 
 The PTP Operator generates fast event notifications for every PTP-capable network interface. You can access the events by using a `cloud-event-proxy` sidecar container over an HTTP message bus.
 

modules/cnf-about-ptp-and-clock-synchronization.adoc

@@ -0,0 +1,37 @@
+// Module included in the following assemblies:
+//
+// * networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="cnf-about-ptp-events-consumer-sidecar-and-http-transport_{context}"]
+= Retrieving PTP events with the PTP events REST API v1
+
+Applications run the `cloud-event-proxy` container in a sidecar pattern to subscribe to PTP events.
+The `cloud-event-proxy` sidecar container can access the same resources as the primary application container without using any of the resources of the primary application and with no significant latency.
+
+.Overview of PTP fast events with consumer sidecar and HTTP message transport
+image::319_OpenShift_PTP_bare-metal_OCP_nodes_0323_4.13.png[Overview of PTP fast events with consumer sidecar and HTTP message transport]
+
+image:darkcircle-1.png[20,20] Event is generated on the cluster host::
+`linuxptp-daemon` in the PTP Operator-managed pod runs as a Kubernetes `DaemonSet` and manages the various `linuxptp` processes (`ptp4l`, `phc2sys`, and optionally for grandmaster clocks, `ts2phc`).
+The `linuxptp-daemon` passes the event to the UNIX domain socket.
+
+image:darkcircle-2.png[20,20] Event is passed to the cloud-event-proxy sidecar::
+The PTP plugin reads the event from the UNIX domain socket and passes it to the `cloud-event-proxy` sidecar in the PTP Operator-managed pod.
+`cloud-event-proxy` delivers the event from the Kubernetes infrastructure to Cloud-Native Network Functions (CNFs) with low latency.
+
+image:darkcircle-3.png[20,20] Event is persisted::
+The `cloud-event-proxy` sidecar in the PTP Operator-managed pod processes the event and publishes the cloud-native event by using a REST API.
+
+image:darkcircle-4.png[20,20] Message is transported::
+The message transporter transports the event to the `cloud-event-proxy` sidecar in the application pod over HTTP.
+
+image:darkcircle-5.png[20,20] Event is available from the REST API::
+The `cloud-event-proxy` sidecar in the Application pod processes the event and makes it available by using the REST API.
+
+image:darkcircle-6.png[20,20] Consumer application requests a subscription and receives the subscribed event::
+The consumer application sends an API request to the `cloud-event-proxy` sidecar in the application pod to create a PTP events subscription.
+The `cloud-event-proxy` sidecar creates an HTTP messaging listener protocol for the resource specified in the subscription.
+
+The `cloud-event-proxy` sidecar in the application pod receives the event from the PTP Operator-managed pod, unwraps the cloud events object to retrieve the data, and posts the event to the consumer application.
+The consumer application listens to the address specified in the resource qualifier and receives and processes the PTP event.

modules/cnf-about-ptp-events-consumer-sidecar-and-http-transport.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * networking/ptp/ptp-cloud-events-consumer-dev-reference-v2.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="cnf-about-ptp-events-using-ptp-event-producer-with-o-ran-api_{context}"]
+= Retrieving PTP events with the PTP events REST API v2
+
+Applications subscribe to PTP events by using an O-RAN v3 compatible REST API in the producer-side cloud event proxy sidecar.
+The `cloud-event-proxy` sidecar container can access the same resources as the primary application container without using any of the resources of the primary application and with no significant latency.
+
+.Overview of consuming PTP fast events from the PTP event producer REST API v2
+image::319_OpenShift_PTP_bare-metal_OCP_nodes_0323_4.17.png[Overview of consuming PTP fast events from the PTP event producer REST API]
+
+image:darkcircle-1.png[20,20] Event is generated on the cluster host::
+The `linuxptp-daemon` process in the PTP Operator-managed pod runs as a Kubernetes `DaemonSet` and manages the various `linuxptp` processes (`ptp4l`, `phc2sys`, and optionally for grandmaster clocks, `ts2phc`).
+The `linuxptp-daemon` passes the event to the UNIX domain socket.
+
+image:darkcircle-2.png[20,20] Event is passed to the cloud-event-proxy sidecar::
+The PTP plugin reads the event from the UNIX domain socket and passes it to the `cloud-event-proxy` sidecar in the PTP Operator-managed pod.
+`cloud-event-proxy` delivers the event from the Kubernetes infrastructure to Cloud-Native Network Functions (CNFs) with low latency.
+
+image:darkcircle-3.png[20,20] Event is published::
+The `cloud-event-proxy` sidecar in the PTP Operator-managed pod processes the event and publishes the event by using the PTP events REST API v2.
+
+image:darkcircle-4.png[20,20] Consumer application requests a subscription and receives the subscribed event::
+The consumer application sends an API request to the producer `cloud-event-proxy` sidecar to create a PTP events subscription.
+Once subscribed, the consumer application listens to the address specified in the resource qualifier and receives and processes the PTP events.

modules/cnf-about-ptp-events-using-ptp-event-producer-with-o-ran-api.adoc

@@ -1,45 +1,17 @@
 // Module included in the following assemblies:
 //
-// * networking/ptp/using-ptp-events.adoc
+// * networking/ptp/ptp-cloud-events-consumer-dev-reference-v2.adoc
+// * networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc
 
 :_mod-docs-content-type: CONCEPT
-[id="cnf-about-ptp-fast-event-notifications-framework_{context}"]
+[id="cnf-about-ptp-fast-event-notifications-framework-{ptp-events-rest-api}_{context}"]
 = About the PTP fast event notifications framework
 
-Use the Precision Time Protocol (PTP) fast event notifications framework to subscribe cluster applications to PTP events that the bare-metal cluster node generates.
+Use the Precision Time Protocol (PTP) fast event REST API v2 to subscribe cluster applications to PTP events that the bare-metal cluster node generates.
 
 [NOTE]
 ====
-The fast events notifications framework uses a REST API for communication. The REST API is based on the _O-RAN O-Cloud Notification API Specification for Event Consumers 3.0_ that is available from link:https://orandownloadsweb.azurewebsites.net/specifications[O-RAN ALLIANCE Specifications].
-====
-
-The framework consists of a publisher, subscriber, and an HTTP messaging protocol to handle communications between the publisher and subscriber applications.
-Applications run the `cloud-event-proxy` container in a sidecar pattern to subscribe to PTP events.
-The `cloud-event-proxy` sidecar container can access the same resources as the primary application container without using any of the resources of the primary application and with no significant latency.
-
-.Overview of PTP fast events
-image::319_OpenShift_PTP_bare-metal_OCP_nodes_0323_4.13.png[Overview of PTP fast events]
-
-image:darkcircle-1.png[20,20] Event is generated on the cluster host::
-`linuxptp-daemon` in the PTP Operator-managed pod runs as a Kubernetes `DaemonSet` and manages the various `linuxptp` processes (`ptp4l`, `phc2sys`, and optionally for grandmaster clocks, `ts2phc`).
-The `linuxptp-daemon` passes the event to the UNIX domain socket.
-
-image:darkcircle-2.png[20,20] Event is passed to the cloud-event-proxy sidecar::
-The PTP plugin reads the event from the UNIX domain socket and passes it to the `cloud-event-proxy` sidecar in the PTP Operator-managed pod.
-`cloud-event-proxy` delivers the event from the Kubernetes infrastructure to Cloud-Native Network Functions (CNFs) with low latency.
+The fast events notifications framework uses a REST API for communication. The PTP events REST API v1 and v2 are based on the _O-RAN O-Cloud Notification API Specification for Event Consumers 3.0_ that is available from link:https://orandownloadsweb.azurewebsites.net/specifications[O-RAN ALLIANCE Specifications].
 
-image:darkcircle-3.png[20,20] Event is persisted::
-The `cloud-event-proxy` sidecar in the PTP Operator-managed pod processes the event and publishes the cloud-native event by using a REST API.
-
-image:darkcircle-4.png[20,20] Message is transported::
-The message transporter transports the event to the `cloud-event-proxy` sidecar in the application pod over HTTP.
-
-image:darkcircle-5.png[20,20] Event is available from the REST API::
-The `cloud-event-proxy` sidecar in the Application pod processes the event and makes it available by using the REST API.
-
-image:darkcircle-6.png[20,20] Consumer application requests a subscription and receives the subscribed event::
-The consumer application sends an API request to the `cloud-event-proxy` sidecar in the application pod to create a PTP events subscription.
-The `cloud-event-proxy` sidecar creates an HTTP messaging listener protocol for the resource specified in the subscription.
-
-The `cloud-event-proxy` sidecar in the application pod receives the event from the PTP Operator-managed pod, unwraps the cloud events object to retrieve the data, and posts the event to the consumer application.
-The consumer application listens to the address specified in the resource qualifier and receives and processes the PTP event.
+Only the PTP events REST API v2 is O-RAN v3 compliant.
+====

modules/cnf-about-ptp-fast-event-notifications-framework.adoc

@@ -1,9 +1,10 @@
 // Module included in the following assemblies:
 //
-// * networking/ptp/using-ptp-events.adoc
+// * networking/ptp/ptp-cloud-events-consumer-dev-reference-v2.adoc
+// * networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc
 
 :_mod-docs-content-type: PROCEDURE
-[id="cnf-configuring-the-ptp-fast-event-publisher_{context}"]
+[id="cnf-configuring-the-ptp-fast-event-publisher-{ptp-events-rest-api}_{context}"]
 = Configuring the PTP fast event notifications publisher
 
 To start using PTP fast event notifications for a network interface in your cluster, you must enable the fast event publisher in the PTP Operator `PtpOperatorConfig` custom resource (CR) and configure `ptpClockThreshold` values in a `PtpConfig` CR that you create.
@@ -22,21 +23,12 @@ To start using PTP fast event notifications for a network interface in your clus
 
 .. Save the following YAML in the `ptp-operatorconfig.yaml` file:
 +
-[source,yaml]
-----
-apiVersion: ptp.openshift.io/v1
-kind: PtpOperatorConfig
-metadata:
-  name: default
-  namespace: openshift-ptp
-spec:
-  daemonNodeSelector:
-    node-role.kubernetes.io/worker: ""
-  ptpEventConfig:
-    enableEventPublisher: true <1>
-----
-<1> Set `enableEventPublisher` to `true` to enable PTP fast event notifications.
-
+ifeval::["{ptp-events-rest-api}" == "v1"]
+include::snippets/ptp-event-config-api-v1.adoc[]
+endif::[]
+ifeval::["{ptp-events-rest-api}" == "v2"]
+include::snippets/ptp-event-config-api-v2.adoc[]
+endif::[]
 +
 [NOTE]
 ====