openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity

Adding O-RAN API docs for PTP events

Browse Source 
Review updates

further updates for Jack

Lisa's comments
This commit is contained in:
Aidan Reilly
2024-08-21 16:32:44 +01:00
parent 9a296cf04f
commit 290d3146ca
31 changed files with 1261 additions and 425 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
_topic_maps/_topic_map.yml
View File

@@ -1371,10 +1371,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:

BIN
images/319_OpenShift_PTP_bare-metal_OCP_nodes_0323_4.17.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 79 KiB

13
modules/cnf-about-ptp-and-clock-synchronization.adoc
View File

@@ -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.

37
modules/cnf-about-ptp-events-consumer-sidecar-and-http-transport.adoc Normal file
View File

@@ -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.

28
modules/cnf-about-ptp-events-using-ptp-event-producer-with-o-ran-api.adoc Normal file
View File

@@ -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.

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

@@ -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 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].
Only the PTP events REST API v2 is O-RAN v3 compliant.
====
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.
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.

26
modules/cnf-configuring-the-ptp-fast-event-publisher.adoc
View File

@@ -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]
====

484
modules/cnf-fast-event-notifications-api-reference-v2.adoc Normal file
View File

@@ -0,0 +1,484 @@
// Module included in the following assemblies:
//
// * networking/ptp/ptp-events-rest-api-reference-v2.adoc
:_mod-docs-content-type: PROCEDURE
[id="cnf-fast-event-notifications-v2-api-refererence_{context}"]
= PTP events REST API v2 endpoints
[id="api-ocloud-notifications-v2-subscriptions_{context}"]
== api/ocloudNotifications/v2/subscriptions
[discrete]
=== HTTP method
`GET api/ocloudNotifications/v2/subscriptions`
[discrete]
=== Description
Returns a list of subscriptions. If subscriptions exist, a `200 OK` status code is returned along with the list of subscriptions.
.Example API response
[source,json]
----
[
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/sync-status/os-clock-sync-state",
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"SubscriptionId": "ccedbf08-3f96-4839-a0b6-2eb0401855ed",
"UriLocation": "http://ptp-event-publisher-service-compute-1.openshift-ptp.svc.cluster.local:9043/api/ocloudNotifications/v2/subscriptions/ccedbf08-3f96-4839-a0b6-2eb0401855ed"
},
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/ptp-status/clock-class",
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"SubscriptionId": "a939a656-1b7d-4071-8cf1-f99af6e931f2",
"UriLocation": "http://ptp-event-publisher-service-compute-1.openshift-ptp.svc.cluster.local:9043/api/ocloudNotifications/v2/subscriptions/a939a656-1b7d-4071-8cf1-f99af6e931f2"
},
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/ptp-status/lock-state",
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"SubscriptionId": "ba4564a3-4d9e-46c5-b118-591d3105473c",
"UriLocation": "http://ptp-event-publisher-service-compute-1.openshift-ptp.svc.cluster.local:9043/api/ocloudNotifications/v2/subscriptions/ba4564a3-4d9e-46c5-b118-591d3105473c"
},
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/gnss-status/gnss-sync-status",
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"SubscriptionId": "ea0d772e-f00a-4889-98be-51635559b4fb",
"UriLocation": "http://ptp-event-publisher-service-compute-1.openshift-ptp.svc.cluster.local:9043/api/ocloudNotifications/v2/subscriptions/ea0d772e-f00a-4889-98be-51635559b4fb"
},
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/sync-status/sync-state",
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"SubscriptionId": "762999bf-b4a0-4bad-abe8-66e646b65754",
"UriLocation": "http://ptp-event-publisher-service-compute-1.openshift-ptp.svc.cluster.local:9043/api/ocloudNotifications/v2/subscriptions/762999bf-b4a0-4bad-abe8-66e646b65754"
}
]
----
[discrete]
=== HTTP method
`POST api/ocloudNotifications/v2/subscriptions`
[discrete]
=== Description
Creates a new subscription for the required event by passing the appropriate payload.
If a subscription is successfully created, or if it already exists, a `201 Created` status code is returned.
You can subscribe to the following PTP events:
* `sync-state` events
* `lock-state` events
* `gnss-sync-status events` events
* `os-clock-sync-state` events
* `clock-class` events
.Query parameters
[cols=2*, width="60%", options="header"]
|====
|Parameter
|Type
|subscription
|data
|====
.Example sync-state subscription payload
[source,json]
----
{
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"ResourceAddress": "/cluster/node/{node_name}/sync/sync-status/sync-state"
}
----
.Example PTP lock-state events subscription payload
[source,json]
----
{
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"ResourceAddress": "/cluster/node/{node_name}/sync/ptp-status/lock-state"
}
----
.Example PTP gnss-sync-status events subscription payload
[source,json]
----
{
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"ResourceAddress": "/cluster/node/{node_name}/sync/gnss-status/gnss-sync-status"
}
----
.Example PTP os-clock-sync-state events subscription payload
[source,json]
----
{
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"ResourceAddress": "/cluster/node/{node_name}/sync/sync-status/os-clock-sync-state"
}
----
.Example PTP clock-class events subscription payload
[source,json]
----
{
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"ResourceAddress": "/cluster/node/{node_name}/sync/ptp-status/clock-class"
}
----
.Example API response
[source,json]
----
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/ptp-status/lock-state",
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"SubscriptionId": "620283f3-26cd-4a6d-b80a-bdc4b614a96a",
"UriLocation": "http://ptp-event-publisher-service-compute-1.openshift-ptp.svc.cluster.local:9043/api/ocloudNotifications/v2/subscriptions/620283f3-26cd-4a6d-b80a-bdc4b614a96a"
}
----
[discrete]
=== HTTP method
`DELETE api/ocloudNotifications/v2/subscriptions`
[discrete]
=== Description
Deletes all subscriptions.
.Example API response
[source,json]
----
{
"status": "deleted all subscriptions"
}
----
[id="api-ocloud-notifications-v2-subscriptions-subscription_id_{context}"]
== api/ocloudNotifications/v2/subscriptions/{subscription_id}
[discrete]
=== HTTP method
`GET api/ocloudNotifications/v2/subscriptions/{subscription_id}`
[discrete]
=== Description
Returns details for the subscription with ID `subscription_id`.
.Global path parameters
[cols=2*, width="60%", options="header"]
|====
|Parameter
|Type
|`subscription_id`
|string
|====
.Example API response
[source,json]
----
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/ptp-status/lock-state",
"EndpointUri": "http://consumer-events-subscription-service.cloud-events.svc.cluster.local:9043/event",
"SubscriptionId": "620283f3-26cd-4a6d-b80a-bdc4b614a96a",
"UriLocation": "http://ptp-event-publisher-service-compute-1.openshift-ptp.svc.cluster.local:9043/api/ocloudNotifications/v2/subscriptions/620283f3-26cd-4a6d-b80a-bdc4b614a96a"
}
----
[discrete]
=== HTTP method
`DELETE api/ocloudNotifications/v2/subscriptions/{subscription_id}`
[discrete]
=== Description
Deletes the subscription with ID `subscription_id`.
.Global path parameters
[cols=2*, width="60%", options="header"]
|====
|Parameter
|Type
|`subscription_id`
|string
|====
.HTTP response codes
[cols=2*, width="60%", options="header"]
|====
|HTTP response
|Description
|204 No Content
|Success
|====
[id="api-ocloudnotifications-v2-health_{context}"]
== api/ocloudNotifications/v2/health
[discrete]
=== HTTP method
`GET api/ocloudNotifications/v2/health/`
[discrete]
=== Description
Returns the health status for the `ocloudNotifications` REST API.
.HTTP response codes
[cols=2*, width="60%", options="header"]
|====
|HTTP response
|Description
|200 OK
|Success
|====
[id="api-ocloudnotifications-v2-publishers_{context}"]
== api/ocloudNotifications/v2/publishers
[discrete]
=== HTTP method
`GET api/ocloudNotifications/v2/publishers`
[discrete]
=== Description
Returns a list of publisher details for the cluster node.
The system generates notifications when the relevant equipment state changes.
You can use equipment synchronization status subscriptions together to deliver a detailed view of the overall synchronization health of the system.
.Example API response
[source,json]
----
[
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/sync-status/sync-state",
"EndpointUri": "http://localhost:9043/api/ocloudNotifications/v2/dummy",
"SubscriptionId": "4ea72bfa-185c-4703-9694-cdd0434cd570",
"UriLocation": "http://localhost:9043/api/ocloudNotifications/v2/publishers/4ea72bfa-185c-4703-9694-cdd0434cd570"
},
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/sync-status/os-clock-sync-state",
"EndpointUri": "http://localhost:9043/api/ocloudNotifications/v2/dummy",
"SubscriptionId": "71fbb38e-a65d-41fc-823b-d76407901087",
"UriLocation": "http://localhost:9043/api/ocloudNotifications/v2/publishers/71fbb38e-a65d-41fc-823b-d76407901087"
},
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/ptp-status/clock-class",
"EndpointUri": "http://localhost:9043/api/ocloudNotifications/v2/dummy",
"SubscriptionId": "7bc27cad-03f4-44a9-8060-a029566e7926",
"UriLocation": "http://localhost:9043/api/ocloudNotifications/v2/publishers/7bc27cad-03f4-44a9-8060-a029566e7926"
},
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/ptp-status/lock-state",
"EndpointUri": "http://localhost:9043/api/ocloudNotifications/v2/dummy",
"SubscriptionId": "6e7b6736-f359-46b9-991c-fbaed25eb554",
"UriLocation": "http://localhost:9043/api/ocloudNotifications/v2/publishers/6e7b6736-f359-46b9-991c-fbaed25eb554"
},
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/gnss-status/gnss-sync-status",
"EndpointUri": "http://localhost:9043/api/ocloudNotifications/v2/dummy",
"SubscriptionId": "31bb0a45-7892-45d4-91dd-13035b13ed18",
"UriLocation": "http://localhost:9043/api/ocloudNotifications/v2/publishers/31bb0a45-7892-45d4-91dd-13035b13ed18"
}
]
----
.HTTP response codes
[cols=2*, width="60%", options="header"]
|====
|HTTP response
|Description
|200 OK
|Success
|====
[id="resource-address-current-state-v2_{context}"]
== api/ocloudNotifications/v2/{resource_address}/CurrentState
[discrete]
=== HTTP method
`GET api/ocloudNotifications/v2/cluster/node/{node_name}/sync/ptp-status/lock-state/CurrentState`
`GET api/ocloudNotifications/v2/cluster/node/{node_name}/sync/sync-status/os-clock-sync-state/CurrentState`
`GET api/ocloudNotifications/v2/cluster/node/{node_name}/sync/ptp-status/clock-class/CurrentState`
`GET api/ocloudNotifications/v2/cluster/node/{node_name}/sync/sync-status/sync-state/CurrentState`
`GET api/ocloudNotifications/v2/cluster/node/{node_name}/sync/gnss-status/gnss-sync-state/CurrentState`
[discrete]
=== Description
Returns the current state of the `os-clock-sync-state`, `clock-class`, `lock-state`, `gnss-sync-status`, or `sync-state` events for the cluster node.
* `os-clock-sync-state` notifications describe the host operating system clock synchronization state. Can be in `LOCKED` or `FREERUN` state.
* `clock-class` notifications describe the current state of the PTP clock class.
* `lock-state` notifications describe the current status of the PTP equipment lock state. Can be in `LOCKED`, `HOLDOVER` or `FREERUN` state.
* `sync-state` notifications describe the current status of the least synchronized of the PTP clock `lock-state` and
`os-clock-sync-state` states.
* `gnss-sync-status` notifications describe the GNSS clock synchronization state.
.Global path parameters
[cols=2*, width="60%", options="header"]
|====
|Parameter
|Type
|`resource_address`
|string
|====
.Example lock-state API response
[source,json]
----
{
"id": "c1ac3aa5-1195-4786-84f8-da0ea4462921",
"type": "event.sync.ptp-status.ptp-state-change",
"source": "/cluster/node/compute-1.example.com/sync/ptp-status/lock-state",
"dataContentType": "application/json",
"time": "2023-01-10T02:41:57.094981478Z",
"data": {
"version": "1.0",
"values": [
{
"ResourceAddress": "/cluster/node/compute-1.example.com/ens5fx/master",
"dataType": "notification",
"valueType": "enumeration",
"value": "LOCKED"
},
{
"ResourceAddress": "/cluster/node/compute-1.example.com/ens5fx/master",
"dataType": "metric",
"valueType": "decimal64.3",
"value": "29"
}
]
}
}
----
.Example os-clock-sync-state API response
[source,json]
----
{
"specversion": "0.3",
"id": "4f51fe99-feaa-4e66-9112-66c5c9b9afcb",
"source": "/cluster/node/compute-1.example.com/sync/sync-status/os-clock-sync-state",
"type": "event.sync.sync-status.os-clock-sync-state-change",
"subject": "/cluster/node/compute-1.example.com/sync/sync-status/os-clock-sync-state",
"datacontenttype": "application/json",
"time": "2022-11-29T17:44:22.202Z",
"data": {
"version": "1.0",
"values": [
{
"ResourceAddress": "/cluster/node/compute-1.example.com/CLOCK_REALTIME",
"dataType": "notification",
"valueType": "enumeration",
"value": "LOCKED"
},
{
"ResourceAddress": "/cluster/node/compute-1.example.com/CLOCK_REALTIME",
"dataType": "metric",
"valueType": "decimal64.3",
"value": "27"
}
]
}
}
----
.Example clock-class API response
[source,json]
----
{
"id": "064c9e67-5ad4-4afb-98ff-189c6aa9c205",
"type": "event.sync.ptp-status.ptp-clock-class-change",
"source": "/cluster/node/compute-1.example.com/sync/ptp-status/clock-class",
"dataContentType": "application/json",
"time": "2023-01-10T02:41:56.785673989Z",
"data": {
"version": "1.0",
"values": [
{
"ResourceAddress": "/cluster/node/compute-1.example.com/ens5fx/master",
"dataType": "metric",
"valueType": "decimal64.3",
"value": "165"
}
]
}
}
----
.Example sync-state API response
[source,json]
----
{
"specversion": "0.3",
"id": "8c9d6ecb-ae9f-4106-82c4-0a778a79838d",
"source": "/sync/sync-status/sync-state",
"type": "event.sync.sync-status.synchronization-state-change",
"subject": "/cluster/node/compute-1.example.com/sync/sync-status/sync-state",
"datacontenttype": "application/json",
"time": "2024-08-28T14:50:57.327585316Z",
"data":
{
"version": "1.0",
"values": [
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/sync-status/sync-state",
"data_type": "notification",
"value_type": "enumeration",
"value": "LOCKED"
}]
}
}
----
.Example gnss-sync-state API response
[source,json]
----
{
"id": "435e1f2a-6854-4555-8520-767325c087d7",
"type": "event.sync.gnss-status.gnss-state-change",
"source": "/cluster/node/compute-1.example.com/sync/gnss-status/gnss-sync-status",
"dataContentType": "application/json",
"time": "2023-09-27T19:35:33.42347206Z",
"data": {
"version": "1.0",
"values": [
{
"resource": "/cluster/node/compute-1.example.com/ens2fx/master",
"dataType": "notification",
"valueType": "enumeration",
"value": "LOCKED"
},
{
"resource": "/cluster/node/compute-1.example.com/ens2fx/master",
"dataType": "metric",
"valueType": "decimal64.3",
"value": "5"
}
]
}
}
----

276
modules/cnf-fast-event-notifications-api-refererence.adoc → modules/cnf-fast-event-notifications-api-reference.adoc
View File

@@ -1,12 +1,10 @@
// Module included in the following assemblies:
//
// * networking/ptp/using-ptp-events.adoc
// * networking/ptp/ptp-events-rest-api-reference.adoc
:_mod-docs-content-type: PROCEDURE
[id="cnf-fast-event-notifications-api-refererence_{context}"]
= PTP events REST API reference
Use the PTP event notifications REST API to subscribe a cluster application to the PTP events that are generated on the parent node.
= PTP events REST API v1 endpoints
[id="api-ocloud-notifications-v1-subscriptions_{context}"]
== api/ocloudNotifications/v1/subscriptions
@@ -42,7 +40,15 @@ Returns a list of subscriptions. If subscriptions exist, a `200 OK` status code
[discrete]
=== Description
Creates a new subscription. If a subscription is successfully created, or if it already exists, a `201 Created` status code is returned.
Creates a new subscription for the required event by passing the appropriate payload.
If a subscription is successfully created, or if it already exists, a `201 Created` status code is returned.
You can subscribe to the following PTP events:
* `lock-state` events
* `os-clock-sync-state` events
* `clock-class` events
* `gnss-sync-status` events
* `sync-state` events
.Query parameters
[cols=2*, width="60%", options="header"]
@@ -54,7 +60,7 @@ Creates a new subscription. If a subscription is successfully created, or if it
|data
|====
.Example payload
.Example PTP events subscription payload
[source,json]
----
{
@@ -63,6 +69,51 @@ Creates a new subscription. If a subscription is successfully created, or if it
}
----
.Example PTP lock-state events subscription payload
[source,json]
----
{
"endpointUri": "http://localhost:8989/event",
"resource": "/cluster/node/{node_name}/sync/ptp-status/lock-state"
}
----
.Example PTP os-clock-sync-state events subscription payload
[source,json]
----
{
"endpointUri": "http://localhost:8989/event",
"resource": "/cluster/node/{node_name}/sync/sync-status/os-clock-sync-state"
}
----
.Example PTP clock-class events subscription payload
[source,json]
----
{
"endpointUri": "http://localhost:8989/event",
"resource": "/cluster/node/{node_name}/sync/ptp-status/clock-class"
}
----
.Example PTP gnss-sync-status events subscription payload
[source,json]
----
{
"endpointUri": "http://localhost:8989/event",
"resource": "/cluster/node/{node_name}/sync/gnss-status/gnss-sync-status"
}
----
.Example sync-state subscription payload
[source,json]
----
{
"endpointUri": "http://localhost:8989/event",
"resource": "/cluster/node/{node_name}/sync/sync-status/sync-state"
}
----
[discrete]
=== HTTP method
@@ -165,6 +216,12 @@ OK
[id="api-ocloudnotifications-v1-publishers_{context}"]
== api/ocloudNotifications/v1/publishers
[IMPORTANT]
====
The `api/ocloudNotifications/v1/publishers` endpoint is only available from the cloud-event-proxy container in the PTP Operator managed pod.
It is not available for consumer applications in the application pod.
====
[discrete]
=== HTTP method
@@ -173,14 +230,9 @@ OK
[discrete]
=== Description
Returns an array of `os-clock-sync-state`, `ptp-clock-class-change`, `lock-state`, and `gnss-sync-status` details for the cluster node.
Returns a list of publisher details for the cluster node.
The system generates notifications when the relevant equipment state changes.
* `os-clock-sync-state` notifications describe the host operating system clock synchronization state. Can be in `LOCKED` or `FREERUN` state.
* `ptp-clock-class-change` notifications describe the current state of the PTP clock class.
* `lock-state` notifications describe the current status of the PTP equipment lock state. Can be in `LOCKED`, `HOLDOVER` or `FREERUN` state.
* `gnss-sync-status` notifications describe the GPS synchronization state with regard to the external GNSS clock signal. Can be in `LOCKED` or `FREERUN` state.
You can use equipment synchronization status subscriptions together to deliver a detailed view of the overall synchronization health of the system.
.Example API response
@@ -197,7 +249,7 @@ You can use equipment synchronization status subscriptions together to deliver a
"id": "28cd82df-8436-4f50-bbd9-7a9742828a71",
"endpointUri": "http://localhost:9085/api/ocloudNotifications/v1/dummy",
"uriLocation": "http://localhost:9085/api/ocloudNotifications/v1/publishers/28cd82df-8436-4f50-bbd9-7a9742828a71",
"resource": "/cluster/node/compute-1.example.com/sync/ptp-status/ptp-clock-class-change"
"resource": "/cluster/node/compute-1.example.com/sync/ptp-status/clock-class"
},
{
"id": "44aa480d-7347-48b0-a5b0-e0af01fa9677",
@@ -214,143 +266,33 @@ You can use equipment synchronization status subscriptions together to deliver a
]
----
You can find `os-clock-sync-state`, `ptp-clock-class-change`, `lock-state`, and `gnss-sync-status` events in the logs for the `cloud-event-proxy` container. For example:
[source,terminal]
----
$ oc logs -f linuxptp-daemon-cvgr6 -n openshift-ptp -c cloud-event-proxy
----
.Example os-clock-sync-state event
[source,json]
----
{
"id":"c8a784d1-5f4a-4c16-9a81-a3b4313affe5",
"type":"event.sync.sync-status.os-clock-sync-state-change",
"source":"/cluster/compute-1.example.com/ptp/CLOCK_REALTIME",
"dataContentType":"application/json",
"time":"2022-05-06T15:31:23.906277159Z",
"data":{
"version":"v1",
"values":[
{
"resource":"/sync/sync-status/os-clock-sync-state",
"dataType":"notification",
"valueType":"enumeration",
"value":"LOCKED"
},
{
"resource":"/sync/sync-status/os-clock-sync-state",
"dataType":"metric",
"valueType":"decimal64.3",
"value":"-53"
}
]
}
}
----
.Example ptp-clock-class-change event
[source,json]
----
{
"id":"69eddb52-1650-4e56-b325-86d44688d02b",
"type":"event.sync.ptp-status.ptp-clock-class-change",
"source":"/cluster/compute-1.example.com/ptp/ens2fx/master",
"dataContentType":"application/json",
"time":"2022-05-06T15:31:23.147100033Z",
"data":{
"version":"v1",
"values":[
{
"resource":"/sync/ptp-status/ptp-clock-class-change",
"dataType":"metric",
"valueType":"decimal64.3",
"value":"135"
}
]
}
}
----
.Example lock-state event
[source,json]
----
{
"id":"305ec18b-1472-47b3-aadd-8f37933249a9",
"type":"event.sync.ptp-status.ptp-state-change",
"source":"/cluster/compute-1.example.com/ptp/ens2fx/master",
"dataContentType":"application/json",
"time":"2022-05-06T15:31:23.467684081Z",
"data":{
"version":"v1",
"values":[
{
"resource":"/sync/ptp-status/lock-state",
"dataType":"notification",
"valueType":"enumeration",
"value":"LOCKED"
},
{
"resource":"/sync/ptp-status/lock-state",
"dataType":"metric",
"valueType":"decimal64.3",
"value":"62"
}
]
}
}
----
.Example gnss-sync-status event
[source,json]
----
{
"id": "435e1f2a-6854-4555-8520-767325c087d7",
"type": "event.sync.gnss-status.gnss-state-change",
"source": "/cluster/node/compute-1.example.com/sync/gnss-status/gnss-sync-status",
"dataContentType": "application/json",
"time": "2023-09-27T19:35:33.42347206Z",
"data": {
"version": "v1",
"values": [
{
"resource": "/cluster/node/compute-1.example.com/ens2fx/master",
"dataType": "notification",
"valueType": "enumeration",
"value": "LOCKED"
},
{
"resource": "/cluster/node/compute-1.example.com/ens2fx/master",
"dataType": "metric",
"valueType": "decimal64.3",
"value": "5"
}
]
}
}
----
[id="resource-address-current-state_{context}"]
== api/ocloudNotifications/v1/{resource_address}/CurrentState
[discrete]
=== HTTP method
`GET api/ocloudNotifications/v1/cluster/node/<node_name>/sync/ptp-status/lock-state/CurrentState`
`GET api/ocloudNotifications/v1/cluster/node/{node_name}/sync/ptp-status/lock-state/CurrentState`
`GET api/ocloudNotifications/v1/cluster/node/<node_name>/sync/sync-status/os-clock-sync-state/CurrentState`
`GET api/ocloudNotifications/v1/cluster/node/{node_name}/sync/sync-status/os-clock-sync-state/CurrentState`
`GET api/ocloudNotifications/v1/cluster/node/<node_name>/sync/ptp-status/ptp-clock-class-change/CurrentState`
`GET api/ocloudNotifications/v1/cluster/node/{node_name}/sync/ptp-status/clock-class/CurrentState`
`GET api/ocloudNotifications/v1/cluster/node/{node_name}/sync/sync-status/sync-state/CurrentState`
`GET api/ocloudNotifications/v1/cluster/node/{node_name}/sync/gnss-status/gnss-sync-state/CurrentState`
[discrete]
=== Description
Configure the `CurrentState` API endpoint to return the current state of the `os-clock-sync-state`, `ptp-clock-class-change`, `lock-state` events for the cluster node.
Returns the current state of the `os-clock-sync-state`, `clock-class`, `lock-state`, `gnss-sync-status`, or `sync-state` events for the cluster node.
* `os-clock-sync-state` notifications describe the host operating system clock synchronization state. Can be in `LOCKED` or `FREERUN` state.
* `ptp-clock-class-change` notifications describe the current state of the PTP clock class.
* `clock-class` notifications describe the current state of the PTP clock class.
* `lock-state` notifications describe the current status of the PTP equipment lock state. Can be in `LOCKED`, `HOLDOVER` or `FREERUN` state.
* `sync-state` notifications describe the current status of the least synchronized of the `ptp-status/lock-state` and
`sync-status/os-clock-sync-state` endpoints.
* `gnss-sync-status` notifications describe the GNSS clock synchronization state.
.Global path parameters
[cols=2*, width="60%", options="header"]
@@ -372,7 +314,7 @@ Configure the `CurrentState` API endpoint to return the current state of the `os
"dataContentType": "application/json",
"time": "2023-01-10T02:41:57.094981478Z",
"data": {
"version": "v1",
"version": "1.0",
"values": [
{
"resource": "/cluster/node/compute-1.example.com/ens5fx/master",
@@ -403,7 +345,7 @@ Configure the `CurrentState` API endpoint to return the current state of the `os
"datacontenttype": "application/json",
"time": "2022-11-29T17:44:22.202Z",
"data": {
"version": "v1",
"version": "1.0",
"values": [
{
"resource": "/cluster/node/compute-1.example.com/CLOCK_REALTIME",
@@ -422,17 +364,17 @@ Configure the `CurrentState` API endpoint to return the current state of the `os
}
----
.Example ptp-clock-class-change API response
.Example clock-class API response
[source,json]
----
{
"id": "064c9e67-5ad4-4afb-98ff-189c6aa9c205",
"type": "event.sync.ptp-status.ptp-clock-class-change",
"source": "/cluster/node/compute-1.example.com/sync/ptp-status/ptp-clock-class-change",
"source": "/cluster/node/compute-1.example.com/sync/ptp-status/clock-class",
"dataContentType": "application/json",
"time": "2023-01-10T02:41:56.785673989Z",
"data": {
"version": "v1",
"version": "1.0",
"values": [
{
"resource": "/cluster/node/compute-1.example.com/ens5fx/master",
@@ -444,3 +386,57 @@ Configure the `CurrentState` API endpoint to return the current state of the `os
}
}
----
.Example sync-state API response
[source,json]
----
{
"specversion": "0.3",
"id": "8c9d6ecb-ae9f-4106-82c4-0a778a79838d",
"source": "/sync/sync-status/sync-state",
"type": "event.sync.sync-status.synchronization-state-change",
"subject": "/cluster/node/compute-1.example.com/sync/sync-status/sync-state",
"datacontenttype": "application/json",
"time": "2024-08-28T14:50:57.327585316Z",
"data":
{
"version": "1.0",
"values": [
{
"ResourceAddress": "/cluster/node/compute-1.example.com/sync/sync-status/sync-state",
"data_type": "notification",
"value_type": "enumeration",
"value": "LOCKED"
}]
}
}
----
.Example gnss-sync-status API response
[source,json]
----
{
"id": "435e1f2a-6854-4555-8520-767325c087d7",
"type": "event.sync.gnss-status.gnss-state-change",
"source": "/cluster/node/compute-1.example.com/sync/gnss-status/gnss-sync-status",
"dataContentType": "application/json",
"time": "2023-09-27T19:35:33.42347206Z",
"data": {
"version": "1.0",
"values": [
{
"resource": "/cluster/node/compute-1.example.com/ens2fx/master",
"dataType": "notification",
"valueType": "enumeration",
"value": "LOCKED"
},
{
"resource": "/cluster/node/compute-1.example.com/ens2fx/master",
"dataType": "metric",
"valueType": "decimal64.3",
"value": "5"
}
]
}
}
----

1
modules/cnf-migrating-from-amqp-to-http-transport.adoc
View File

@@ -9,6 +9,7 @@
If you have previously deployed PTP or bare-metal events consumer applications, you need to update the applications to use HTTP message transport.
.Prerequisites
* You have installed the OpenShift CLI (`oc`).

17
modules/cnf-monitoring-fast-events-metrics.adoc
View File

@@ -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-monitoring-fast-events-metrics_{context}"]
[id="cnf-monitoring-fast-events-metrics-{ptp-events-rest-api}_{context}"]
= Monitoring PTP fast event metrics
You can monitor PTP fast events metrics from cluster nodes where the `linuxptp-daemon` is running.
@@ -34,15 +35,25 @@ sh-4.4# curl http://localhost:9091/metrics
----
+
.Example output
[source,terminal]
----
# HELP cne_api_events_published Metric to get number of events published by the rest api
# TYPE cne_api_events_published gauge
cne_api_events_published{address="/cluster/node/compute-1.example.com/sync/gnss-status/gnss-sync-status",status="success"} 1
cne_api_events_published{address="/cluster/node/compute-1.example.com/sync/ptp-status/lock-state",status="success"} 94
cne_api_events_published{address="/cluster/node/compute-1.example.com/sync/ptp-status/ptp-clock-class-change",status="success"} 18
cne_api_events_published{address="/cluster/node/compute-1.example.com/sync/ptp-status/class-change",status="success"} 18
cne_api_events_published{address="/cluster/node/compute-1.example.com/sync/sync-status/os-clock-sync-state",status="success"} 27
----
. Optional.
You can also find PTP events in the logs for the `cloud-event-proxy` container.
For example, run the following command:
+
[source,terminal]
----
$ oc logs -f linuxptp-daemon-cvgr6 -n openshift-ptp -c cloud-event-proxy
----
. To view the PTP event in the {product-title} web console, copy the name of the PTP metric you want to query, for example, `openshift_ptp_offset_ns`.
. In the {product-title} web console, click *Observe* -> *Metrics*.

7
modules/nw-ptp-operator-metrics-reference.adoc
View File

@@ -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: REFERENCE
[id="nw-ptp-operator-metrics-reference_{context}"]
[id="nw-ptp-operator-metrics-reference-{ptp-events-rest-api}_{context}"]
= PTP fast event metrics reference
The following table describes the PTP fast events metrics that are available from cluster nodes where the `linuxptp-daemon` service is running.
@@ -112,5 +113,3 @@ Possible values are 0 (`NOFIX`), 1 (`DEAD RECKONING ONLY`), 2 (`2D-FIX`), 3 (`3D
|`{from="gnss",iface="ens2fx",node="compute-1.example.com",process="gnss"} 3`
|====

18
modules/ptp-cloud-event-proxy-sidecar-api.adoc
View File

@@ -1,18 +0,0 @@
// Module included in the following assemblies:
//
// * networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc
:_mod-docs-content-type: REFERENCE
[id="ptp-cloud-event-proxy-sidecar-api_{context}"]
= PTP events available from the cloud-event-proxy sidecar REST API
PTP events consumer applications can poll the PTP events producer for the following PTP timing events.
.PTP events available from the cloud-event-proxy sidecar
[options="header"]
|====
|Resource URI|Description
|`/cluster/node/<node_name>/sync/ptp-status/lock-state`| Describes the current status of the PTP equipment lock state. Can be in `LOCKED`, `HOLDOVER`, or `FREERUN` state.
|`/cluster/node/<node_name>/sync/sync-status/os-clock-sync-state`| Describes the host operating system clock synchronization state. Can be in `LOCKED` or `FREERUN` state.
|`/cluster/node/<node_name>/sync/ptp-status/ptp-clock-class-change`| Describes the current state of the PTP clock class.
|====

108
modules/ptp-events-consumer-application-v2.adoc Normal file
View File

@@ -0,0 +1,108 @@
// Module included in the following assemblies:
//
// * networking/ptp/ptp-cloud-events-consumer-dev-reference-v2.adoc
:_mod-docs-content-type: REFERENCE
[id="ptp-events-consumer-application-v2_{context}"]
= PTP events REST API v2 consumer application reference
PTP event consumer applications require the following features:
. A web service running with a `POST` handler to receive the cloud native PTP events JSON payload
. A `createSubscription` function to subscribe to the PTP events producer
. A `getCurrentState` function to poll the current state of the PTP events producer
The following example Go snippets illustrate these requirements:
.Example PTP events consumer server function in Go
[source,go]
----
func server() {
http.HandleFunc("/event", getEvent)
http.ListenAndServe(":9043", nil)
}
func getEvent(w http.ResponseWriter, req *http.Request) {
defer req.Body.Close()
bodyBytes, err := io.ReadAll(req.Body)
if err != nil {
log.Errorf("error reading event %v", err)
}
e := string(bodyBytes)
if e != "" {
processEvent(bodyBytes)
log.Infof("received event %s", string(bodyBytes))
} else {
w.WriteHeader(http.StatusNoContent)
}
}
----
.Example PTP events createSubscription function in Go
[source,go,subs="attributes+"]
----
import (
"github.com/redhat-cne/sdk-go/pkg/pubsub"
"github.com/redhat-cne/sdk-go/pkg/types"
v1pubsub "github.com/redhat-cne/sdk-go/v1/pubsub"
)
// Subscribe to PTP events using v2 REST API
s1,_:=createsubscription("/cluster/node/<node_name>/sync/sync-status/sync-state")
s2,_:=createsubscription("/cluster/node/<node_name>/sync/ptp-status/lock-state")
s3,_:=createsubscription("/cluster/node/<node_name>/sync/gnss-status/gnss-sync-status")
s4,_:=createsubscription("/cluster/node/<node_name>/sync/sync-status/os-clock-sync-state")
s5,_:=createsubscription("/cluster/node/<node_name>/sync/ptp-status/clock-class")
// Create PTP event subscriptions POST
func createSubscription(resourceAddress string) (sub pubsub.PubSub, err error) {
var status int
apiPath := "/api/ocloudNotifications/v2/"
localAPIAddr := "localhost:8989" // vDU service API address
apiAddr := "ptp-event-publisher-service-<node_name>.openshift-ptp.svc.cluster.local:9043" // <1>
apiVersion := "2.0"
subURL := &types.URI{URL: url.URL{Scheme: "http",
Host: apiAddr
Path: fmt.Sprintf("%s%s", apiPath, "subscriptions")}}
endpointURL := &types.URI{URL: url.URL{Scheme: "http",
Host: localAPIAddr,
Path: "event"}}
sub = v1pubsub.NewPubSub(endpointURL, resourceAddress, apiVersion)
var subB []byte
if subB, err = json.Marshal(&sub); err == nil {
rc := restclient.New()
if status, subB = rc.PostWithReturn(subURL, subB); status != http.StatusCreated {
err = fmt.Errorf("error in subscription creation api at %s, returned status %d", subURL, status)
} else {
err = json.Unmarshal(subB, &sub)
}
} else {
err = fmt.Errorf("failed to marshal subscription for %s", resourceAddress)
}
return
}
----
<1> Replace `<node_name>` with the FQDN of the node that is generating the PTP events. For example, `compute-1.example.com`.
.Example PTP events consumer getCurrentState function in Go
[source,go,subs="attributes+"]
----
//Get PTP event state for the resource
func getCurrentState(resource string) {
//Create publisher
url := &types.URI{URL: url.URL{Scheme: "http",
Host: "ptp-event-publisher-service-<node_name>.openshift-ptp.svc.cluster.local:9043", // <1>
Path: fmt.SPrintf("/api/ocloudNotifications/v2/%s/CurrentState",resource}}
rc := restclient.New()
status, event := rc.Get(url)
if status != http.StatusOK {
log.Errorf("CurrentState:error %d from url %s, %s", status, url.String(), event)
} else {
log.Debugf("Got CurrentState: %s ", event)
}
}
----
<1> Replace `<node_name>` with the FQDN of the node that is generating the PTP events. For example, `compute-1.example.com`.

12
modules/ptp-events-consumer-application.adoc
View File

@@ -3,7 +3,7 @@
// * networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc
:_mod-docs-content-type: REFERENCE
[id="ptp-events-consumer-application_{context}"]
[id="ptp-events-consumer-application-{ptp-events-rest-api}_{context}"]
= PTP events consumer application reference
PTP event consumer applications require the following features:
@@ -39,7 +39,7 @@ func getEvent(w http.ResponseWriter, req *http.Request) {
----
.Example PTP events createSubscription function in Go
[source,go]
[source,go,subs="attributes+"]
----
import (
"github.com/redhat-cne/sdk-go/pkg/pubsub"
@@ -49,13 +49,13 @@ v1pubsub "github.com/redhat-cne/sdk-go/v1/pubsub"
// Subscribe to PTP events using REST API
s1,_:=createsubscription("/cluster/node/<node_name>/sync/sync-status/os-clock-sync-state") <1>
s2,_:=createsubscription("/cluster/node/<node_name>/sync/ptp-status/ptp-clock-class-change")
s2,_:=createsubscription("/cluster/node/<node_name>/sync/ptp-status/class-change")
s3,_:=createsubscription("/cluster/node/<node_name>/sync/ptp-status/lock-state")
// Create PTP event subscriptions POST
func createSubscription(resourceAddress string) (sub pubsub.PubSub, err error) {
var status int
apiPath:= "/api/ocloudNotifications/v1/"
apiPath:= "/api/ocloudNotifications/{ptp-events-rest-api}/"
localAPIAddr:=localhost:8989 // vDU service API address
apiAddr:= "localhost:8089" // event framework API address
@@ -85,14 +85,14 @@ func createSubscription(resourceAddress string) (sub pubsub.PubSub, err error) {
<1> Replace `<node_name>` with the FQDN of the node that is generating the PTP events. For example, `compute-1.example.com`.
.Example PTP events consumer getCurrentState function in Go
[source,go]
[source,go,subs="attributes+"]
----
//Get PTP event state for the resource
func getCurrentState(resource string) {
//Create publisher
url := &types.URI{URL: url.URL{Scheme: "http",
Host: localhost:8989,
Path: fmt.SPrintf("/api/ocloudNotifications/v1/%s/CurrentState",resource}}
Path: fmt.SPrintf("/api/ocloudNotifications/{ptp-events-rest-api}/%s/CurrentState",resource}}
rc := restclient.New()
status, event := rc.Get(url)
if status != http.StatusOK {

46
modules/ptp-getting-the-current-ptp-clock-status.adoc
View File

@@ -1,46 +0,0 @@
// Module included in the following assemblies:
//
// * networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc
:_mod-docs-content-type: REFERENCE
[id="ptp-getting-the-current-ptp-clock-status_{context}"]
= Getting the current PTP clock status
To get the current PTP status for the node, send a `GET` action to one of the following event REST APIs:
* `+http://localhost:8081/api/ocloudNotifications/v1/cluster/node/<node_name>/sync/ptp-status/lock-state/CurrentState+`
* `+http://localhost:8081/api/ocloudNotifications/v1/cluster/node/<node_name>/sync/sync-status/os-clock-sync-state/CurrentState+`
* `+http://localhost:8081/api/ocloudNotifications/v1/cluster/node/<node_name>/sync/ptp-status/ptp-clock-class-change/CurrentState+`
The response is a cloud native event JSON object. For example:
.Example lock-state API response
[source,json]
----
{
"id": "c1ac3aa5-1195-4786-84f8-da0ea4462921",
"type": "event.sync.ptp-status.ptp-state-change",
"source": "/cluster/node/compute-1.example.com/sync/ptp-status/lock-state",
"dataContentType": "application/json",
"time": "2023-01-10T02:41:57.094981478Z",
"data": {
"version": "v1",
"values": [
{
"resource": "/cluster/node/compute-1.example.com/ens5fx/master",
"dataType": "notification",
"valueType": "enumeration",
"value": "LOCKED"
},
{
"resource": "/cluster/node/compute-1.example.com/ens5fx/master",
"dataType": "metric",
"valueType": "decimal64.3",
"value": "29"
}
]
}
}
----

108
modules/ptp-reference-deployment-and-service-crs-v2.adoc Normal file
View File

@@ -0,0 +1,108 @@
// Module included in the following assemblies:
//
// * networking/ptp/ptp-cloud-events-consumer-dev-reference-v2.adoc
:_mod-docs-content-type: REFERENCE
[id="ptp-reference-deployment-and-service-crs-v2_{context}"]
= Reference event consumer deployment and service CRs using PTP events REST API v2
Use the following example PTP event consumer custom resources (CRs) as a reference when deploying your PTP events consumer application for use with the PTP events REST API v2.
.Reference cloud event consumer namespace
[source,yaml]
----
apiVersion: v1
kind: Namespace
metadata:
name: cloud-events
labels:
security.openshift.io/scc.podSecurityLabelSync: "false"
pod-security.kubernetes.io/audit: "privileged"
pod-security.kubernetes.io/enforce: "privileged"
pod-security.kubernetes.io/warn: "privileged"
name: cloud-events
openshift.io/cluster-monitoring: "true"
annotations:
workload.openshift.io/allowed: management
----
.Reference cloud event consumer deployment
[source,yaml]
----
apiVersion: apps/v1
kind: Deployment
metadata:
name: cloud-consumer-deployment
namespace: cloud-events
labels:
app: consumer
spec:
replicas: 1
selector:
matchLabels:
app: consumer
template:
metadata:
annotations:
target.workload.openshift.io/management: '{"effect": "PreferredDuringScheduling"}'
labels:
app: consumer
spec:
nodeSelector:
node-role.kubernetes.io/worker: ""
serviceAccountName: consumer-sa
containers:
- name: cloud-event-consumer
image: cloud-event-consumer
imagePullPolicy: Always
args:
- "--local-api-addr=consumer-events-subscription-service.cloud-events.svc.cluster.local:9043"
- "--api-path=/api/ocloudNotifications/v2/"
- "--api-addr=127.0.0.1:8089"
- "--api-version=2.0"
- "--http-event-publishers=ptp-event-publisher-service-NODE_NAME.openshift-ptp.svc.cluster.local:9043"
env:
- name: NODE_NAME
valueFrom:
fieldRef:
fieldPath: spec.nodeName
- name: CONSUMER_TYPE
value: "PTP"
- name: ENABLE_STATUS_CHECK
value: "true"
volumes:
- name: pubsubstore
emptyDir: {}
----
.Reference cloud event consumer service account
[source,yaml]
----
apiVersion: v1
kind: ServiceAccount
metadata:
name: consumer-sa
namespace: cloud-events
----
.Reference cloud event consumer service
[source,yaml]
----
apiVersion: v1
kind: Service
metadata:
annotations:
prometheus.io/scrape: "true"
name: consumer-events-subscription-service
namespace: cloud-events
labels:
app: consumer-service
spec:
ports:
- name: sub-port
port: 9043
selector:
app: consumer
sessionAffinity: None
type: ClusterIP
----

2
modules/ptp-reference-deployment-and-service-crs.adoc
View File

@@ -3,7 +3,7 @@
// * networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc
:_mod-docs-content-type: REFERENCE
[id="ptp-reference-deployment-and-service-crs_{context}"]
[id="ptp-reference-deployment-and-service-crs-{ptp-events-rest-api}_{context}"]
= Reference cloud-event-proxy deployment and service CRs
Use the following example `cloud-event-proxy` deployment and subscriber service CRs as a reference when deploying your PTP events consumer application.

91
modules/ptp-subscribing-consumer-app-to-events.adoc
View File

@@ -1,81 +1,32 @@
// Module included in the following assemblies:
//
// * networking/ptp/ptp-cloud-events-consumer-dev-reference-v2.adoc
// * networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc
:_mod-docs-content-type: REFERENCE
[id="ptp-subscribing-consumer-app-to-events_{context}"]
= Subscribing the consumer application to PTP events
[id="ptp-subscribing-consumer-app-to-events-{ptp-events-rest-api}_{context}"]
= Subscribing to PTP events with the REST API {ptp-events-rest-api}
Before the PTP events consumer application can poll for events, you need to subscribe the application to the event producer.
ifeval::["{ptp-events-rest-api}" == "v2"]
Deploy your `cloud-event-consumer` application container and subscribe the `cloud-event-consumer` application to PTP events posted by the `cloud-event-proxy` container in the pod managed by the PTP Operator.
[id="ptp-sub-lock-state-events_{context}"]
== Subscribing to PTP lock-state events
Subscribe consumer applications to PTP events by sending a `POST` request to `\http://ptp-event-publisher-service-NODE_NAME.openshift-ptp.svc.cluster.local:9043/api/ocloudNotifications/v2/subscriptions` passing the appropriate subscription request payload.
To create a subscription for PTP `lock-state` events, send a `POST` action to the cloud event API at `+http://localhost:8081/api/ocloudNotifications/v1/subscriptions+` with the following payload:
[NOTE]
====
`9043` is the default port for the `cloud-event-proxy` container deployed in the PTP event producer pod.
You can configure a different port for your application as required.
====
endif::[]
[source,json]
----
{
"endpointUri": "http://localhost:8989/event",
"resource": "/cluster/node/<node_name>/sync/ptp-status/lock-state",
}
----
ifeval::["{ptp-events-rest-api}" == "v1"]
Deploy your `cloud-event-consumer` application container and `cloud-event-proxy` sidecar container in a separate application pod.
.Example response
[source,json]
----
{
"id": "e23473d9-ba18-4f78-946e-401a0caeff90",
"endpointUri": "http://localhost:8989/event",
"uriLocation": "http://localhost:8089/api/ocloudNotifications/v1/subscriptions/e23473d9-ba18-4f78-946e-401a0caeff90",
"resource": "/cluster/node/<node_name>/sync/ptp-status/lock-state",
}
----
Subscribe the `cloud-event-consumer` application to PTP events posted by the `cloud-event-proxy` container at `\http://localhost:8089/api/ocloudNotifications/v1/` in the application pod.
[id="ptp-sub-os-clock-sync-state_{context}"]
== Subscribing to PTP os-clock-sync-state events
To create a subscription for PTP `os-clock-sync-state` events, send a `POST` action to the cloud event API at `+http://localhost:8081/api/ocloudNotifications/v1/subscriptions+` with the following payload:
[source,json]
----
{
"endpointUri": "http://localhost:8989/event",
"resource": "/cluster/node/<node_name>/sync/sync-status/os-clock-sync-state",
}
----
.Example response
[source,json]
----
{
"id": "e23473d9-ba18-4f78-946e-401a0caeff90",
"endpointUri": "http://localhost:8989/event",
"uriLocation": "http://localhost:8089/api/ocloudNotifications/v1/subscriptions/e23473d9-ba18-4f78-946e-401a0caeff90",
"resource": "/cluster/node/<node_name>/sync/sync-status/os-clock-sync-state",
}
----
[id="ptp-sub-ptp-clock-class-change_{context}"]
== Subscribing to PTP ptp-clock-class-change events
To create a subscription for PTP `ptp-clock-class-change` events, send a `POST` action to the cloud event API at `+http://localhost:8081/api/ocloudNotifications/v1/subscriptions+` with the following payload:
[source,json]
----
{
"endpointUri": "http://localhost:8989/event",
"resource": "/cluster/node/<node_name>/sync/ptp-status/ptp-clock-class-change",
}
----
.Example response
[source,json]
----
{
"id": "e23473d9-ba18-4f78-946e-401a0caeff90",
"endpointUri": "http://localhost:8989/event",
"uriLocation": "http://localhost:8089/api/ocloudNotifications/v1/subscriptions/e23473d9-ba18-4f78-946e-401a0caeff90",
"resource": "/cluster/node/<node_name>/sync/ptp-status/ptp-clock-class-change",
}
----
[NOTE]
====
`9089` is the default port for the `cloud-event-consumer` container deployed in the application pod.
You can configure a different port for your application as required.
====
endif::[]

82
modules/ptp-verifying-events-consumer-app-is-receiving-events-v2.adoc Normal file
View File

@@ -0,0 +1,82 @@
// Module included in the following assemblies:
//
// * 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="ptp-verifying-events-consumer-app-is-receiving-events-v2_{context}"]
= Verifying that the PTP events REST API v2 consumer application is receiving events
Verify that the `cloud-event-consumer` container in the application pod is receiving Precision Time Protocol (PTP) events.
.Prerequisites
* You have installed the OpenShift CLI (`oc`).
* You have logged in as a user with `cluster-admin` privileges.
* You have installed and configured the PTP Operator.
* You have deployed a cloud events application pod and PTP events consumer application.
.Procedure
. Check the logs for the deployed events consumer application.
For example, run the following command:
+
[source,terminal]
----
$ oc -n cloud-events logs -f deployment/cloud-consumer-deployment
----
+
.Example output
[source,terminal]
----
time = "2024-09-02T13:49:01Z"
level = info msg = "transport host path is set to ptp-event-publisher-service-compute-1.openshift-ptp.svc.cluster.local:9043"
time = "2024-09-02T13:49:01Z"
level = info msg = "apiVersion=2.0, updated apiAddr=ptp-event-publisher-service-compute-1.openshift-ptp.svc.cluster.local:9043, apiPath=/api/ocloudNotifications/v2/"
time = "2024-09-02T13:49:01Z"
level = info msg = "Starting local API listening to :9043"
time = "2024-09-02T13:49:06Z"
level = info msg = "transport host path is set to ptp-event-publisher-service-compute-1.openshift-ptp.svc.cluster.local:9043"
time = "2024-09-02T13:49:06Z"
level = info msg = "checking for rest service health"
time = "2024-09-02T13:49:06Z"
level = info msg = "health check http://ptp-event-publisher-service-compute-1.openshift-ptp.svc.cluster.local:9043/api/ocloudNotifications/v2/health"
time = "2024-09-02T13:49:07Z"
level = info msg = "rest service returned healthy status"
time = "2024-09-02T13:49:07Z"
level = info msg = "healthy publisher; subscribing to events"
time = "2024-09-02T13:49:07Z"
level = info msg = "received event {\"specversion\":\"1.0\",\"id\":\"ab423275-f65d-4760-97af-5b0b846605e4\",\"source\":\"/sync/ptp-status/clock-class\",\"type\":\"event.sync.ptp-status.ptp-clock-class-change\",\"time\":\"2024-09-02T13:49:07.226494483Z\",\"data\":{\"version\":\"1.0\",\"values\":[{\"ResourceAddress\":\"/cluster/node/compute-1.example.com/ptp-not-set\",\"data_type\":\"metric\",\"value_type\":\"decimal64.3\",\"value\":\"0\"}]}}"
----
. Optional. Test the REST API by using `oc` and port-forwarding port `9043` from the `linuxptp-daemon` deployment.
For example, run the following command:
+
[source,terminal]
----
$ oc port-forward -n openshift-ptp ds/linuxptp-daemon 9043:9043
----
+
.Example output
[source,terminal]
----
Forwarding from 127.0.0.1:9043 -> 9043
Forwarding from [::1]:9043 -> 9043
Handling connection for 9043
----
+
Open a new shell prompt and test the REST API v2 endpoints:
+
[source,terminal]
----
$ curl -X GET http://localhost:9043/api/ocloudNotifications/v2/health
----
+
.Example output
[source,terminal]
----
OK
----

4
modules/ptp-verifying-events-consumer-app-is-receiving-events.adoc
View File

@@ -3,8 +3,8 @@
// * networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc
:_mod-docs-content-type: PROCEDURE
[id="ptp-verifying-events-consumer-app-is-receiving-events_{context}"]
= Verifying that the PTP events consumer application is receiving events
[id="ptp-verifying-events-consumer-app-is-receiving-events-{ptp-events-rest-api}_{context}"]
= Verifying that the PTP events REST API v1 consumer application is receiving events
Verify that the `cloud-event-proxy` container in the application pod is receiving PTP events.

2
networking/ptp/about-ptp.adoc
View File

@@ -36,3 +36,5 @@ include::modules/ptp-dual-nics.adoc[leveloffset=+1]
include::modules/ptp-linuxptp-introduction.adoc[leveloffset=+1]
include::modules/ptp-overview-of-gnss-grandmaster-clock.adoc[leveloffset=+1]
include::modules/cnf-about-ptp-and-clock-synchronization.adoc[leveloffset=+1]

6
networking/ptp/configuring-ptp.adoc
View File

@@ -25,7 +25,7 @@ include::modules/nw-ptp-configuring-linuxptp-services-as-grandmaster-clock-dual-
[role="_additional-resources"]
.Additional resources
* xref:../../networking/ptp/using-ptp-events.adoc#cnf-configuring-the-ptp-fast-event-publisher_using-ptp-hardware-fast-events-framework[Configuring the PTP fast event notifications publisher]
* xref:../../networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc#cnf-configuring-the-ptp-fast-event-publisher-v2_ptp-consumer[Configuring the PTP fast event notifications publisher]
include::modules/nw-ptp-grandmaster-clock-configuration-reference.adoc[leveloffset=+2]
@@ -44,7 +44,7 @@ include::modules/nw-ptp-configuring-linuxptp-services-as-boundary-clock.adoc[lev
* xref:../../networking/ptp/configuring-ptp.adoc#cnf-configuring-fifo-priority-scheduling-for-ptp_configuring-ptp[Configuring FIFO priority scheduling for PTP hardware]
* xref:../../networking/ptp/using-ptp-events.adoc#cnf-configuring-the-ptp-fast-event-publisher_using-ptp-hardware-fast-events-framework[Configuring the PTP fast event notifications publisher]
* xref:../../networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc#cnf-configuring-the-ptp-fast-event-publisher-v2_ptp-consumer[Configuring the PTP fast event notifications publisher]
include::modules/ptp-configuring-linuxptp-services-as-boundary-clock-dual-nic.adoc[leveloffset=+2]
@@ -57,7 +57,7 @@ include::modules/nw-ptp-configuring-linuxptp-services-as-ordinary-clock.adoc[lev
* xref:../../networking/ptp/configuring-ptp.adoc#cnf-configuring-fifo-priority-scheduling-for-ptp_configuring-ptp[Configuring FIFO priority scheduling for PTP hardware]
* xref:../../networking/ptp/using-ptp-events.adoc#cnf-configuring-the-ptp-fast-event-publisher_using-ptp-hardware-fast-events-framework[Configuring the PTP fast event notifications publisher]
* xref:../../networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc#cnf-configuring-the-ptp-fast-event-publisher-v2_ptp-consumer[Configuring the PTP fast event notifications publisher]
include::modules/nw-columbiaville-ptp-config-refererence.adoc[leveloffset=+2]

55
networking/ptp/ptp-cloud-events-consumer-dev-reference-v2.adoc Normal file
View File

@@ -0,0 +1,55 @@
:_mod-docs-content-type: ASSEMBLY
:ptp-events-rest-api: v2
[id="ptp-cloud-events-consumer-dev-reference-{ptp-events-rest-api}"]
= Developing PTP events consumer applications with the REST API {ptp-events-rest-api}
include::_attributes/common-attributes.adoc[]
:context: ptp-consumer
toc::[]
When developing consumer applications that make use of Precision Time Protocol (PTP) events on a bare-metal cluster node, you deploy your consumer application in a separate application pod.
The consumer application subscribes to PTP events by using the PTP events REST API {ptp-events-rest-api}.
[NOTE]
====
The following information provides general guidance for developing consumer applications that use PTP events.
A complete events consumer application example is outside the scope of this information.
====
[role="_additional-resources"]
.Additional resources
* xref:../../networking/ptp/ptp-events-rest-api-reference-v2.adoc#ptp-events-rest-api-reference-v2[PTP events REST API v2 reference]
include::modules/cnf-about-ptp-fast-event-notifications-framework.adoc[leveloffset=+1]
include::modules/cnf-about-ptp-events-using-ptp-event-producer-with-o-ran-api.adoc[leveloffset=+1]
include::modules/cnf-configuring-the-ptp-fast-event-publisher.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* For a complete example CR that configures `linuxptp` services as an ordinary clock with PTP fast events, see xref:../../networking/ptp/configuring-ptp.adoc#configuring-linuxptp-services-as-ordinary-clock_configuring-ptp[Configuring linuxptp services as ordinary clock].
include::modules/ptp-events-consumer-application-v2.adoc[leveloffset=+1]
include::modules/ptp-reference-deployment-and-service-crs-v2.adoc[leveloffset=+1]
include::modules/ptp-subscribing-consumer-app-to-events.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* xref:../../networking/ptp/ptp-events-rest-api-reference-v2.adoc#api-ocloud-notifications-v2-subscriptions_using-ptp-hardware-fast-events-framework-v2[api/ocloudNotifications/v2/subscriptions]
include::modules/ptp-verifying-events-consumer-app-is-receiving-events-v2.adoc[leveloffset=+1]
include::modules/cnf-monitoring-fast-events-metrics.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* xref:../../observability/monitoring/managing-metrics.adoc#managing-metrics[Managing metrics]
include::modules/nw-ptp-operator-metrics-reference.adoc[leveloffset=+1]

46
networking/ptp/ptp-cloud-events-consumer-dev-reference.adoc
View File

@@ -1,16 +1,14 @@
:_mod-docs-content-type: ASSEMBLY
[id="ptp-cloud-events-consumer-dev-reference"]
= Developing PTP events consumer applications
:ptp-events-rest-api: v1
[id="ptp-cloud-events-consumer-dev-reference-{ptp-events-rest-api}"]
= Developing PTP events consumer applications with the REST API {ptp-events-rest-api}
include::_attributes/common-attributes.adoc[]
:context: ptp-consumer
toc::[]
When developing consumer applications that make use of Precision Time Protocol (PTP) events on a bare-metal cluster node, you need to deploy your consumer application and a `cloud-event-proxy` container in a separate application pod.
The `cloud-event-proxy` container receives the events from the PTP Operator pod and passes it to the consumer application.
The consumer application subscribes to the events posted in the `cloud-event-proxy` container by using a REST API.
For more information about deploying PTP events applications, see xref:../../networking/ptp/using-ptp-events.adoc#cnf-about-ptp-fast-event-notifications-framework_using-ptp-hardware-fast-events-framework[About the PTP fast event notifications framework].
When developing consumer applications that make use of Precision Time Protocol (PTP) events on a bare-metal cluster node, you deploy your consumer application in a separate application pod.
The consumer application subscribes to PTP events by using the PTP events REST API {ptp-events-rest-api}.
[NOTE]
====
@@ -18,14 +16,42 @@ The following information provides general guidance for developing consumer appl
A complete events consumer application example is outside the scope of this information.
====
include::snippets/ptp-events-rest-api-v1-deprecation.adoc[]
[role="_additional-resources"]
.Additional resources
* xref:../../networking/ptp/ptp-events-rest-api-reference.adoc#ptp-events-rest-api-reference[PTP events REST API v1 reference]
include::modules/cnf-about-ptp-fast-event-notifications-framework.adoc[leveloffset=+1]
include::modules/cnf-about-ptp-events-consumer-sidecar-and-http-transport.adoc[leveloffset=+1]
include::modules/cnf-configuring-the-ptp-fast-event-publisher.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* For a complete example CR that configures `linuxptp` services as an ordinary clock with PTP fast events, see xref:../../networking/ptp/configuring-ptp.adoc#configuring-linuxptp-services-as-ordinary-clock_configuring-ptp[Configuring linuxptp services as ordinary clock].
include::modules/ptp-events-consumer-application.adoc[leveloffset=+1]
include::modules/ptp-reference-deployment-and-service-crs.adoc[leveloffset=+1]
include::modules/ptp-cloud-event-proxy-sidecar-api.adoc[leveloffset=+1]
include::modules/ptp-subscribing-consumer-app-to-events.adoc[leveloffset=+1]
include::modules/ptp-getting-the-current-ptp-clock-status.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* xref:../../networking/ptp/ptp-events-rest-api-reference.adoc#api-ocloud-notifications-v1-subscriptions_using-ptp-hardware-fast-events-framework-v1[api/ocloudNotifications/v1/subscriptions]
include::modules/ptp-verifying-events-consumer-app-is-receiving-events.adoc[leveloffset=+1]
include::modules/cnf-monitoring-fast-events-metrics.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* xref:../../observability/monitoring/managing-metrics.adoc#managing-metrics[Managing metrics]
include::modules/nw-ptp-operator-metrics-reference.adoc[leveloffset=+1]

29
networking/ptp/ptp-events-rest-api-reference-v2.adoc Normal file
View File

@@ -0,0 +1,29 @@
:_mod-docs-content-type: ASSEMBLY
[id="ptp-events-rest-api-reference-v2"]
= PTP events REST API v2 reference
include::_attributes/common-attributes.adoc[]
:context: using-ptp-hardware-fast-events-framework-v2
toc::[]
Use the following REST API v2 endpoints to subscribe the `cloud-event-consumer` application to Precision Time Protocol (PTP) events posted at `\http://localhost:9043/api/ocloudNotifications/v2` in the PTP events producer pod.
* xref:../../networking/ptp/ptp-events-rest-api-reference-v2.adoc#api-ocloud-notifications-v2-subscriptions_{context}[`api/ocloudNotifications/v2/subscriptions`]
** `POST`: Creates a new subscription
** `GET`: Retrieves a list of subscriptions
** `DELETE`: Deletes all subscriptions
* xref:../../networking/ptp/ptp-events-rest-api-reference-v2.adoc#api-ocloud-notifications-v2-subscriptions-subscription_id_{context}[`api/ocloudNotifications/v2/subscriptions/{subscription_id}`]
** `GET`: Returns details for the specified subscription ID
** `DELETE`: Deletes the subscription associated with the specified subscription ID
* xref:../../networking/ptp/ptp-events-rest-api-reference-v2.adoc#api-ocloudnotifications-v2-health_{context}[`api/ocloudNotifications/v2/health`]
** `GET`: Returns the health status of `ocloudNotifications` API
* xref:../../networking/ptp/ptp-events-rest-api-reference-v2.adoc#api-ocloudnotifications-v2-publishers_{context}[`api/ocloudNotifications/v2/publishers`]
** `GET`: Returns a list of PTP event publishers for the cluster node
* xref:../../networking/ptp/ptp-events-rest-api-reference-v2.adoc#resource-address-current-state-v2_{context}[`api/ocloudnotifications/v2/{resource_address}/CurrentState`]
** `GET`: Returns the current state of the event type specified by the `{resouce_address}`.
include::modules/cnf-fast-event-notifications-api-reference-v2.adoc[leveloffset=+1]

33
networking/ptp/ptp-events-rest-api-reference.adoc Normal file
View File

@@ -0,0 +1,33 @@
:_mod-docs-content-type: ASSEMBLY
[id="ptp-events-rest-api-reference"]
= PTP events REST API v1 reference
include::_attributes/common-attributes.adoc[]
:context: using-ptp-hardware-fast-events-framework-v1
toc::[]
Use the following Precision Time Protocol (PTP) fast event REST API v1 endpoints to subscribe the `cloud-event-consumer` application to PTP events posted by the `cloud-event-proxy` container at [x-]`http://localhost:8089/api/ocloudNotifications/v1/` in the application pod.
include::snippets/ptp-events-rest-api-v1-deprecation.adoc[]
The following API endpoints are available:
* xref:../../networking/ptp/ptp-events-rest-api-reference.adoc#api-ocloud-notifications-v1-subscriptions_{context}[`api/ocloudNotifications/v1/subscriptions`]
** `POST`: Creates a new subscription
** `GET`: Retrieves a list of subscriptions
** `DELETE`: Deletes all subscriptions
* xref:../../networking/ptp/ptp-events-rest-api-reference.adoc#api-ocloud-notifications-v1-subscriptions-subscription_id_{context}[`api/ocloudNotifications/v1/subscriptions/{subscription_id}`]
** `GET`: Returns details for the specified subscription ID
** `DELETE`: Deletes the subscription associated with the specified subscription ID
* xref:../../networking/ptp/ptp-events-rest-api-reference.adoc#api-ocloudnotifications-v1-health_{context}[`api/ocloudNotifications/v1/health`]
** `GET`: Returns the health status of `ocloudNotifications` API
* xref:../../networking/ptp/ptp-events-rest-api-reference.adoc#api-ocloudnotifications-v1-publishers_{context}[`api/ocloudNotifications/v1/publishers`]
** `GET`: Returns a list of PTP event publishers for the cluster node
* xref:../../networking/ptp/ptp-events-rest-api-reference.adoc#resource-address-current-state_{context}[`api/ocloudnotifications/v1/{resource_address}/CurrentState`]
** `GET`: Returns the current state of one the following event types: `sync-state`, `os-clock-sync-state`, `clock-class`, `lock-state`, or `gnss-sync-status` events
include::modules/cnf-fast-event-notifications-api-reference.adoc[leveloffset=+1]

64
networking/ptp/using-ptp-events.adoc
View File

@@ -1,64 +0,0 @@
:_mod-docs-content-type: ASSEMBLY
[id="using-ptp-hardware-fast-events-framework"]
= Using the PTP hardware fast event notifications framework
include::_attributes/common-attributes.adoc[]
:context: using-ptp-hardware-fast-events-framework
toc::[]
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.
Precision Time Protocol (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).
include::modules/cnf-about-ptp-and-clock-synchronization.adoc[leveloffset=+1]
include::modules/cnf-about-ptp-fast-event-notifications-framework.adoc[leveloffset=+1]
include::modules/cnf-configuring-the-ptp-fast-event-publisher.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* For a complete example CR that configures `linuxptp` services as an ordinary clock with PTP fast events, see xref:../../networking/ptp/configuring-ptp.adoc#configuring-linuxptp-services-as-ordinary-clock_configuring-ptp[Configuring linuxptp services as ordinary clock].
[id="subscribing-du-applications-to-ptp-events-rest-api-reference_{context}"]
== Subscribing DU applications to PTP events with the REST API
Subscribe applications to PTP events by using the resource address `/cluster/node/<node_name>/ptp`, where `<node_name>` is the cluster node running the DU application.
Deploy your `cloud-event-consumer` DU application container and `cloud-event-proxy` sidecar container in a separate DU application pod. The `cloud-event-consumer` DU application subscribes to the `cloud-event-proxy` container in the application pod.
Use the following API endpoints to subscribe the `cloud-event-consumer` DU application to PTP events posted by the `cloud-event-proxy` container at [x-]`http://localhost:8089/api/ocloudNotifications/v1/` in the DU application pod:
* xref:../../networking/ptp/using-ptp-events.adoc#api-ocloud-notifications-v1-subscriptions_{context}[`/api/ocloudNotifications/v1/subscriptions`]
- `POST`: Creates a new subscription
- `GET`: Retrieves a list of subscriptions
- `DELETE`: Deletes all subscriptions
* xref:../../networking/ptp/using-ptp-events.adoc#api-ocloud-notifications-v1-subscriptions-subscription_id_{context}[`/api/ocloudNotifications/v1/subscriptions/{subscription_id}`]
- `GET`: Returns details for the specified subscription ID
- `DELETE`: Deletes the subscription associated with the specified subscription ID
* xref:../../networking/ptp/using-ptp-events.adoc#api-ocloudnotifications-v1-health_{context}[`/api/ocloudNotifications/v1/health`]
- `GET`: Returns the health status of `ocloudNotifications` API
* xref:../../networking/ptp/using-ptp-events.adoc#api-ocloudnotifications-v1-publishers_{context}[`api/ocloudNotifications/v1/publishers`]
- `GET`: Returns an array of `os-clock-sync-state`, `ptp-clock-class-change`, `lock-state`, and `gnss-sync-status` messages for the cluster node
* xref:../../networking/ptp/using-ptp-events.adoc#resource-address-current-state_{context}[`/api/ocloudnotifications/v1/{resource_address}/CurrentState`]
- `GET`: Returns the current state of one the following event types: `os-clock-sync-state`, `ptp-clock-class-change`, `lock-state`, or `gnss-state-change` events
[NOTE]
====
`9089` is the default port for the `cloud-event-consumer` container deployed in the application pod. You can configure a different port for your DU application as required.
====
include::modules/cnf-fast-event-notifications-api-refererence.adoc[leveloffset=+2]
include::modules/cnf-monitoring-fast-events-metrics.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* xref:../../observability/monitoring/managing-metrics.adoc#managing-metrics[Managing metrics]
include::modules/nw-ptp-operator-metrics-reference.adoc[leveloffset=+1]

15
snippets/ptp-event-config-api-v1.adoc Normal file
View File

@@ -0,0 +1,15 @@
:_mod-docs-content-type: SNIPPET
[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> Enable PTP fast event notifications by setting `enableEventPublisher` to `true`.

18
snippets/ptp-event-config-api-v2.adoc Normal file
View File

@@ -0,0 +1,18 @@
:_mod-docs-content-type: SNIPPET
[source,yaml]
----
apiVersion: ptp.openshift.io/v1
kind: PtpOperatorConfig
metadata:
name: default
namespace: openshift-ptp
spec:
daemonNodeSelector:
node-role.kubernetes.io/worker: ""
ptpEventConfig:
apiVersion: 2.0 <1>
enableEventPublisher: true <2>
----
<1> Enable the PTP events REST API v2 for the PTP event producer by setting the `ptpEventConfig.apiVersion` to 2.0.
The default value is 1.0.
<2> Enable PTP fast event notifications by setting `enableEventPublisher` to `true`.

6
snippets/ptp-events-rest-api-v1-deprecation.adoc Normal file
View File

@@ -0,0 +1,6 @@
:_mod-docs-content-type: SNIPPET
[IMPORTANT]
====
The PTP events REST API v1 will be deprecated in a future release.
When developing applications that use PTP events, use the xref:../../networking/ptp/ptp-events-rest-api-reference-v2.adoc#ptp-events-rest-api-reference-v2[PTP events REST API v2].
====