O-RAN Spec Compliant Timing API Notification
Modified PTP Status Notification Table Added Includes file Updated example for kubernetes deployment of the sidecar and a simulated application Fixed formatting Updated Patchset 1 comments Removed override-default-application topic Fixed Table formatting Updated PTP Sections with modified content Signed-off-by: Juanita-Balaraj <juanita.balaraj@windriver.com> Change-Id: I7805615b1bbd44a541a12220b4497529cf714360
This commit is contained in:
Juanita-Balaraj
parent
1a7cc09e6f
commit
d6ae8c5fb1
@ -0,0 +1,3 @@
|
||||
|
||||
|
||||
|
||||
@ -79,7 +79,6 @@ PTP Notifications
|
||||
|
||||
install-ptp-notifications
|
||||
remove-ptp-notifications
|
||||
override-default-application-values
|
||||
|
||||
------------------
|
||||
O-RAN O2 Interface
|
||||
|
||||
@ -10,16 +10,63 @@ Install PTP Notifications
|
||||
using the :command:`system application` and :command:`system helm-override`
|
||||
commands.
|
||||
|
||||
The application monitors time related services on a host and provides an API
|
||||
for subscribing to asynchronous status notifications as well as the ability to
|
||||
pull the state of each service on demand.
|
||||
|
||||
.. note::
|
||||
|
||||
Changes to a node's |PTP| configuration, applied using the
|
||||
:command:`system ptp-instance-apply`, requires the ``ptp-notification``
|
||||
application to be removed and reapplied, using the
|
||||
:command:`system application-remove ptp-notification`, and
|
||||
:command:`system application-apply ptp-notification` commands.
|
||||
This allows the containers to reload the updated configuration files and
|
||||
monitor the services correctly.
|
||||
|
||||
**v1 API**
|
||||
|
||||
The legacy functionality of ``ptp-notification`` remains available and is
|
||||
accessible through the v1 API; v1 is only capable of reporting status changes
|
||||
for the |PTP| Sync State on a system.
|
||||
|
||||
**Limitations**
|
||||
|
||||
The v1 API only supports monitoring a single ``ptp4l + phc2sys`` instance.
|
||||
Ensure the system is not configured with multiple instances when using the v1
|
||||
API.
|
||||
|
||||
**v2 API**
|
||||
|
||||
The API conforms to O-RAN.WG6.O-Cloud Notification API-v02.01 with the
|
||||
exception of the /././sync endpoint limitation. Using the v2 API, multiple
|
||||
``ptp4l`` instances can be tracked for independent |PTP| Sync State and |PTP|
|
||||
Clock Class notifications.
|
||||
|
||||
The application monitors the following services:
|
||||
|
||||
- PTP Sync State
|
||||
|
||||
- PTP Clock Class
|
||||
|
||||
- OS Clock Sync State
|
||||
|
||||
- GNSS Sync State
|
||||
|
||||
- Overall System Sync State
|
||||
|
||||
**Limitations**
|
||||
|
||||
The |O-RAN| Cloud Notification defines a /././sync API v2 endpoint intended to
|
||||
allow a client to subscribe to all notifications from a node. This endpoint is
|
||||
not supported in |prod-long| Release 22.12. A specific subscription for each
|
||||
resource type must be created instead.
|
||||
|
||||
.. rubric:: |context|
|
||||
|
||||
|prod| provides the capability for application\(s\) to subscribe to
|
||||
|prod-long| provides the capability for application(s) to subscribe to
|
||||
asynchronous |PTP| status notifications and pull for the |PTP| state on demand.
|
||||
|
||||
.. xbooklink :ref:`|prod-long| System Configuration
|
||||
<system-configuration-management-overview>`:
|
||||
|
||||
.. rubric:: |proc|
|
||||
|
||||
You must provide Helm override values indicating the ``ptp4l`` and ``phc2sys``
|
||||
instances that you want tracked by your ``ptp-notification`` application.
|
||||
|
||||
@ -27,31 +74,37 @@ Since multiple ``ptp4l`` instances can be supported on a node, you must specify
|
||||
the ``ServiceName`` of the instance that the ``ptp-notification`` application
|
||||
should track.
|
||||
|
||||
|
||||
For example, follow the steps below:
|
||||
|
||||
#. Label the controller(s).
|
||||
.. rubric:: |proc|
|
||||
|
||||
#. Source the platform environment.
|
||||
#. Apply labels to nodes that will be running the ``ptp-notification``.
|
||||
|
||||
#. Apply the registration label to the controller nodes.
|
||||
|
||||
.. code-block::
|
||||
|
||||
$ source /etc/platform/openrc
|
||||
~(keystone_admin)]$
|
||||
~(keystone_admin)]$ system host-label-apply controller-0 ptp-registration=true
|
||||
|
||||
#. Assign the |PTP| registration label to the controller(s).
|
||||
#. Apply the notification label to each node that is configured for PTP
|
||||
clock synchronization.
|
||||
|
||||
.. code-block::
|
||||
|
||||
~(keystone_admin)]$ system host-label-assign controller-0 ptp-registration=true
|
||||
~(keystone_admin)]$ system host-label-assign controller-1 ptp-registration=true
|
||||
~(keystone_admin)]$ system host-label-apply controller-0 ptp-notification=true
|
||||
~(keystone_admin)]$ system host-label-apply compute-0 ptp-notification=true
|
||||
|
||||
#. Assign the |PTP| notification label to any node(s) configured for ``ptp4l``
|
||||
clock synchronization. For example:
|
||||
#. Verify the labels.
|
||||
|
||||
.. code-block::
|
||||
|
||||
~(keystone_admin)]$ system host-label-assign controller-0 ptp-notification=true
|
||||
~(keystone_admin)]$ system host-label-list <node name>
|
||||
|
||||
#. Locate the application tarball on the system controller.
|
||||
|
||||
.. code-block::
|
||||
|
||||
~(keystone_admin)]$ ls /usr/local/share/applications/helm/stx-ptp-notification-helm-2.<minor_version>.tgz
|
||||
|
||||
#. Upload the ``ptp-notification`` application using the command below.
|
||||
|
||||
@ -59,40 +112,148 @@ For example, follow the steps below:
|
||||
|
||||
~(keystone_admin)]$ system application-upload <path to application>
|
||||
|
||||
#. Edit application overrides. The value for ``ptp4lSocket`` should be set to
|
||||
the socket path corresponding to the monitored ``ptp4l`` instance. Use the
|
||||
:command:`ls /var/run/ptp4l-*` command to determine this path. The value for
|
||||
``ptp4lServiceName`` should match the ``ptp4l`` instance name. The value for
|
||||
the ``phc2sysServiceName`` should match the ``phc2sys`` instance name. Use
|
||||
the :command:`system ptp-instance-list` command to determine the values for
|
||||
``ptp4lServiceName`` and ``phc2sysServiceName`` names.
|
||||
#. Verify if the application is in the uploaded state.
|
||||
|
||||
.. code-block::
|
||||
.. code-block::
|
||||
|
||||
cat ~/notification-override.yaml
|
||||
ptptracking:
|
||||
ptp4lSocket: /var/run/ptp4l-ptp1
|
||||
ptp4lServiceName: ptp1
|
||||
phc2sysServiceName: phc2sys1
|
||||
~(keystone_admin)]$ system application-list
|
||||
|
||||
#. Apply the overrides using the command below.
|
||||
#. Apply Helm overrides as required.
|
||||
|
||||
.. code-block::
|
||||
.. code-block::
|
||||
|
||||
~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification --values notification-override.yaml
|
||||
~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification --values notification-override.yaml
|
||||
|
||||
#. Apply ``ptp-notification`` using the command below.
|
||||
You can override the default values for the ``ptp-notification`` application:
|
||||
|
||||
.. code-block::
|
||||
#. Create a yaml file and update the fields that require Helm overrides.
|
||||
|
||||
.. code-block::
|
||||
|
||||
~(keystone_admin)]$ cat notification-override.yaml
|
||||
|
||||
ptptracking:
|
||||
ptp4lServiceName: True
|
||||
phc2sysServiceName: True
|
||||
ts2phcServiceName: True
|
||||
log_level: INFO
|
||||
control_timeout: 2
|
||||
device:
|
||||
holdover_seconds: 15
|
||||
poll_freq_seconds: 2
|
||||
osclock:
|
||||
holdover_seconds: 15
|
||||
overall:
|
||||
holdover_seconds: 15
|
||||
|
||||
where the values are:
|
||||
|
||||
**ptptracking**
|
||||
|
||||
ptp4lServiceName: True
|
||||
|
||||
phc2sysServiceName: True
|
||||
|
||||
ts2phcServiceName: True
|
||||
|
||||
- The ServiceName fields are defaulted to True in the application and
|
||||
generally do not need to be altered.
|
||||
|
||||
- A service can be set to "False" in order to disable tracking for that
|
||||
type. However, if a service type is not configured on a node
|
||||
(ie. node does not use ts2phc), then the application will automatically
|
||||
determine this and not attempt to monitor it.
|
||||
|
||||
- Use these fields if there is a service that is configured on the node
|
||||
but you do NOT wish to track.
|
||||
|
||||
**log_level: INFO**
|
||||
|
||||
Set the logging level. DEBUG can be used for additional logs.
|
||||
|
||||
**control_timeout: 2**
|
||||
|
||||
control_timeout sets how frequently, in seconds the services are checked.
|
||||
Value applies to all service types.
|
||||
|
||||
**device refers to ptp4l monitoring**
|
||||
|
||||
device:
|
||||
holdover_seconds: 15
|
||||
poll_freq_seconds: 2
|
||||
osclock:
|
||||
holdover_seconds: 15
|
||||
overall:
|
||||
holdover_seconds: 15
|
||||
|
||||
- ``holdover_seconds`` configures how long each service will stay in the
|
||||
HOLDOVER state before transitioning to FREERUN. The holdover value
|
||||
used by the application equates to: holdover_seconds
|
||||
|
||||
- (control_timeout * 2).
|
||||
|
||||
This is done in order to account for time between the monitor polling
|
||||
cycles. The ``holdover_seconds`` value should be configured to match the
|
||||
validated holdover time provided by the device manufacturer.
|
||||
|
||||
#. View existing values.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
~(keystone_admin)]$ system helm-override-show ptp-notification ptp-notification notification
|
||||
|
||||
#. Update and apply the values.
|
||||
|
||||
Application values can be added by the user and applied, using the following commands.
|
||||
|
||||
.. note::
|
||||
|
||||
The application could be in the "uploaded" or "applied" state.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification -–values <notification-override.yaml>
|
||||
|
||||
~(keystone_admin)]$ system application-apply ptp-notification
|
||||
|
||||
#. Verify the Helm overrides.
|
||||
|
||||
.. code-block::
|
||||
|
||||
~(keystone_admin)]$ system helm-override-show ptp-notification ptp-notification notification
|
||||
|
||||
#. Apply ``ptp-notification`` using the command below.
|
||||
|
||||
.. code-block::
|
||||
|
||||
~(keystone_admin)]$ system application-apply ptp-notification
|
||||
|
||||
|
||||
#. Verify application status and pod status using the following commands:
|
||||
|
||||
#. Application Status
|
||||
|
||||
.. code-block::
|
||||
|
||||
~(keystone_admin)]$ system application-list
|
||||
|
||||
#. Pod Status
|
||||
|
||||
.. code-block::
|
||||
|
||||
~(keystone_admin)]$ kubectl get pods -n notification -o wide
|
||||
|
||||
~(keystone_admin)]$ system application-apply ptp-notification
|
||||
|
||||
.. rubric:: |postreq|
|
||||
|
||||
StarlingX supports applications that rely on PTP for synchronization.
|
||||
These applications are able to receive PTP status notifications from StarlingX
|
||||
|prod-long| supports applications that rely on PTP for synchronization.
|
||||
These applications are able to receive PTP status notifications from |prod-long|
|
||||
hosting the application. For more information see:
|
||||
|
||||
- :ref:`PTP Notifications Overview <ptp-notifications-overview>`
|
||||
|
||||
- `API PTP Notifications <https://docs.starlingx.io/api-ref/ptp-notification-armada-app/api_ptp_notifications_definition_v1.html>`__
|
||||
|
||||
.. only:: partner
|
||||
|
||||
.. include:: /_includes/install-ptp-notifications-3a94b1ea1ae3.rest
|
||||
|
||||
@ -1,60 +0,0 @@
|
||||
|
||||
.. bdx1614099833159
|
||||
.. _override-default-application-values:
|
||||
|
||||
===================================
|
||||
Override Default Application Values
|
||||
===================================
|
||||
|
||||
You can override default application values using the commands described in this section.
|
||||
|
||||
|
||||
|
||||
.. rubric:: |proc|
|
||||
|
||||
|
||||
#. View existing values.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
~(keystone_admin)]$ system helm-override-show ptp-notification
|
||||
ptp-notification notification
|
||||
|
||||
#. Create a yaml file and update the fields that require Helm overrides.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
cat ~/override.yaml
|
||||
ptptracking:
|
||||
device:
|
||||
holdover_seconds: 25
|
||||
poll_freq_seconds: 2
|
||||
|
||||
#. Apply the values.
|
||||
|
||||
Application values can be added by the user and applied, using the following commands.
|
||||
|
||||
.. note::
|
||||
The application could be in the "uploaded" or "applied" state.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification -–values <override.yaml>
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
~(keystone_admin)]$ system application-apply ptp-notification
|
||||
|
||||
where the values are:
|
||||
|
||||
**simulated**
|
||||
value must be 'false' for a normal operation \(used only for troubleshooting\).
|
||||
|
||||
**holdover_seconds**
|
||||
value is the holdover time provided by the |NIC| specification. The default is 15 seconds.
|
||||
|
||||
**poll_freq_seconds**
|
||||
is the frequency that the tracking function monitors the ``ptp4l`` to
|
||||
derive the |PTP| sync state. The default is 2 seconds.
|
||||
|
||||
|
||||
@ -9,33 +9,32 @@ Remove PTP Notifications
|
||||
You can remove all pods and Kubernetes resources created during the application
|
||||
deployment.
|
||||
|
||||
|
||||
Use the following procedure to remove |PTP| notifications.
|
||||
|
||||
|
||||
.. rubric:: |proc|
|
||||
|
||||
|
||||
.. _remove-ptp-notifications-steps-klx-gnf-t4b:
|
||||
|
||||
#. Remove all pods and other Kubernetes resources created during the
|
||||
deployment, using the following command:
|
||||
#. Remove the ``ptp-notification`` application and verify the application
|
||||
status move backs to "uploaded" using the following command:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
~(keystone_admin)]$ system application-remove ptp-notification
|
||||
~(keystone_admin)]$ system application-list
|
||||
|
||||
#. Delete the ptp-notification from sysinv.
|
||||
#. Delete the ``ptp-notification`` and verify the application is removed from
|
||||
the application list.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
~(keystone_admin)]$ system application-delete ptp-notification
|
||||
~(keystone_admin)]$ system application-list
|
||||
|
||||
#. Remove labels applied to controller-0, using the following commands, for example:
|
||||
#. Remove labels applied to controller-0, (repeat for each labelled host)
|
||||
using the following commands, for example:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
~(keystone_admin)]$ system host-label-remove controller-0 ptp-notification
|
||||
~(keystone_admin)]$ system host-label-remove controller-0 ptp-registration
|
||||
~(keystone_admin)]$ system host-label-remove <host name> ptp-notification
|
||||
~(keystone_admin)]$ system host-label-remove <host name> ptp-registration
|
||||
|
||||
|
||||
|
||||
@ -17,4 +17,5 @@ PTP Notification
|
||||
|
||||
ptp-notifications-overview
|
||||
integrate-application-with-notification-client-sidecar
|
||||
ptp-notification-status-conditions-6d6105fccf10
|
||||
|
||||
|
||||
@ -14,6 +14,20 @@ Integrate the Application with Notification Client Sidecar
|
||||
|
||||
.. rubric:: |context|
|
||||
|
||||
This section provides an example of kubernetes deployment of the sidecar and a
|
||||
simulated application. Users could replace the ``ptp-notification-demo-app``
|
||||
container and related configurations with an application requiring |PTP| status
|
||||
updates. The user application must support querying and handling responses
|
||||
for either of the API definitions available at:
|
||||
|
||||
**See**:
|
||||
|
||||
- https://docs.starlingx.io/api-ref/ptp-notification-armada-app/api_ptp_notifications_definition_v1.html
|
||||
|
||||
- https://docs.starlingx.io/api-ref/ptp-notification-armada-app/api_ptp_notifications_definition_v2.html
|
||||
|
||||
|
||||
.. Cole please confirm if this is required
|
||||
|
||||
The integration between the application is done with the use of a Sidecar. The
|
||||
Sidecar runs as a container along with the application in the same pod. The
|
||||
@ -44,6 +58,294 @@ The following prerequisites are required before the integration:
|
||||
- The application supports the |PTP| Notifications API.
|
||||
|
||||
|
||||
The config provided below is for illustrative purposes and is not validated.
|
||||
A suitable user-supplied container would have to be run in the same pod and
|
||||
configured to make API calls to the notificationclient-base container.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: ptp-notification-example
|
||||
namespace: ptpexample
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: ptp-notification-example
|
||||
template:
|
||||
metadata:
|
||||
namespace: ptpexample
|
||||
labels:
|
||||
app: ptp-notification-example
|
||||
release: RELEASE-NAME
|
||||
spec:
|
||||
affinity:
|
||||
nodeAffinity:
|
||||
requiredDuringSchedulingIgnoredDuringExecution:
|
||||
nodeSelectorTerms:
|
||||
- matchExpressions:
|
||||
- key: ptp-notification
|
||||
operator: In
|
||||
values:
|
||||
- "true"
|
||||
containers:
|
||||
- name: ptp-notification-demo-sidecar
|
||||
image: "starlingx/notificationclient-base:stx.8.0-v2.0.2"
|
||||
imagePullPolicy: IfNotPresent
|
||||
tty: true
|
||||
stdin: true
|
||||
livenessProbe:
|
||||
exec:
|
||||
command:
|
||||
- timeout
|
||||
- "2"
|
||||
- curl
|
||||
- http://127.0.0.1:8080/health
|
||||
failureThreshold: 3
|
||||
periodSeconds: 3
|
||||
successThreshold: 1
|
||||
timeoutSeconds: 3
|
||||
env:
|
||||
- name: THIS_NODE_NAME
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: spec.nodeName
|
||||
- name: THIS_POD_IP
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: status.podIP
|
||||
- name: REGISTRATION_HOST
|
||||
value: "registration.notification.svc.cluster.local"
|
||||
- name: REGISTRATION_USER
|
||||
value: "admin"
|
||||
- name: REGISTRATION_PASS
|
||||
value: "admin"
|
||||
- name: REGISTRATION_PORT
|
||||
value: "5672"
|
||||
- name: NOTIFICATIONSERVICE_USER
|
||||
value: "admin"
|
||||
- name: NOTIFICATIONSERVICE_PASS
|
||||
value: "admin"
|
||||
- name: NOTIFICATIONSERVICE_PORT
|
||||
value: "5672"
|
||||
- name: SIDECAR_API_PORT
|
||||
value: "8080"
|
||||
- name: DATASTORE_PATH
|
||||
value: "/opt/datastore"
|
||||
- name: LOGGING_LEVEL
|
||||
value: "INFO"
|
||||
command: ["/bin/bash", "/mnt/sidecar_start.sh"]
|
||||
volumeMounts:
|
||||
- name: scripts
|
||||
mountPath: /mnt
|
||||
- name: data-volume
|
||||
mountPath: /opt/datastore
|
||||
resources:
|
||||
requests:
|
||||
cpu: 50m
|
||||
memory: 128Mi
|
||||
limits:
|
||||
cpu: 300m
|
||||
memory: 256Mi
|
||||
imagePullSecrets:
|
||||
- name: admin-registry-secret
|
||||
|
||||
-----------------
|
||||
Example API Calls
|
||||
-----------------
|
||||
|
||||
Below are examples of using curl to interact with the ``ptp-notification`` API.
|
||||
These can be used to validate the functionality of the application deployment.
|
||||
|
||||
.. note::
|
||||
|
||||
Some versions of curl have been seen to automatically normalize URLs
|
||||
which results in malformed requests to the server by removing parts of the
|
||||
URL containing '/././' or '/./'
|
||||
|
||||
If the version of curl being used supports the flag '--path-as-is' then it
|
||||
should be included in the command to avoid this behaviour.
|
||||
|
||||
**v1 Examples**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# pull
|
||||
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v1/PTP/CurrentState |
|
||||
python -m json.tool
|
||||
|
||||
# subscribe
|
||||
|
||||
curl --path-as-is -v -d '{"ResourceType": "PTP", "ResourceQualifier":
|
||||
{"NodeName":"controller-0"}, "EndpointUri": "http://127.0.0.1:9090/v1/resource_status/ptp"}'
|
||||
-H 'Content-Type: application/json' -X POST http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions
|
||||
|python -m json.tool
|
||||
curl --path-as-is -v -d '{"ResourceType": "PTP", "ResourceQualifier":
|
||||
{"NodeName":"controller-1"}, "EndpointUri": "http://127.0.0.1:9090/v1/resource_status/ptp"}'
|
||||
-H 'Content-Type: application/json' -X POST http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions
|
||||
|python -m json.tool
|
||||
|
||||
# get subscriptions
|
||||
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions |python -m json.tool
|
||||
|
||||
# get one subscription
|
||||
|
||||
# must supply the subscription ID found in "get subscriptions"
|
||||
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/<subscription id> |
|
||||
python -m json.tool
|
||||
|
||||
# unsubscribe
|
||||
# must supply the subscription ID found in "get subscriptions"
|
||||
curl --path-as-is -X DELETE -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/df71709c-9fff-11ec-bf54-6aa223637e5f
|
||||
|
||||
|
||||
**v2 Examples**
|
||||
|
||||
Some commands can target the status of specific node names or of specific ``ptp4l``
|
||||
instances. The names in the format <name> will vary depending on the user's
|
||||
environment.
|
||||
|
||||
The "| python -m json.tool" portion of the command is just for output
|
||||
formatting and is not required for operation.
|
||||
|
||||
Requests with the "/././" path with be automatically directed to the
|
||||
``ptp-notification`` server on the local node, while providing "/./<node name>"
|
||||
will route to the specified node
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
## pull
|
||||
|
||||
# overall
|
||||
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/././sync/sync-status/sync-state/CurrentState |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/./<node name>/sync/sync-status/sync-state/CurrentState |
|
||||
python -m json.tool
|
||||
|
||||
# ptp state
|
||||
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/././sync/ptp-status/lock-state/CurrentState |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/./<node name>/sync/ptp-status/lock-state/CurrentState |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/./<node name>/<ptp instance name>/sync/ptp-status/lock-state/CurrentState |
|
||||
python -m json.tool
|
||||
|
||||
# ptp class
|
||||
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/././sync/ptp-status/clock-class/CurrentState |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/./<node name>/sync/ptp-status/clock-class/CurrentState |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/./<node name>/<ptp instance name>/sync/ptp-status/clock-class/CurrentState |
|
||||
python -m json.tool
|
||||
|
||||
# phc2sys / os clock state
|
||||
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/././sync/sync-status/os-clock-sync-state/CurrentState |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/./<node name>/sync/sync-status/os-clock-sync-state/CurrentState |
|
||||
python -m json.tool
|
||||
|
||||
# gnss
|
||||
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/././sync/gnss-status/gnss-sync-status/CurrentState |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:8080/ocloudNotifications/v2/./<node name>/sync/gnss-status/gnss-sync-status/CurrentState |
|
||||
python -m json.tool
|
||||
|
||||
## subscribe
|
||||
|
||||
# subscribe overall
|
||||
|
||||
curl --path-as-is -v -d '{"ResourceAddress": "/././sync/sync-status/sync-state", "EndpointUri":
|
||||
"http://127.0.0.1:9090/v2/resource_status/ptp"}' -H 'Content-Type: application/json' -X POST
|
||||
http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -d '{"ResourceAddress": "/./<node name>/sync/sync-status/sync-state",
|
||||
"EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp"}' -H 'Content-Type:
|
||||
application/json' -X POST http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions |
|
||||
python -m json.tool
|
||||
|
||||
# subscribe PTP lock state
|
||||
|
||||
curl --path-as-is -v -d '{"ResourceAddress": "/././sync/ptp-status/lock-state",
|
||||
"EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp"}' -H 'Content-Type: application/json'
|
||||
-X POST http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -d '{"ResourceAddress": "/./<node name>/sync/ptp-status/lock-state",
|
||||
"EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp"}' -H 'Content-Type: application/json'
|
||||
-X POST http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions |
|
||||
python -m json.tool
|
||||
|
||||
# subscribe PTP clock class
|
||||
|
||||
curl --path-as-is -v -d '{"ResourceAddress": "/././sync/ptp-status/clock-class",
|
||||
"EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp"}'
|
||||
-H 'Content-Type: application/json' -X POST
|
||||
http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -d '{"ResourceAddress": "/./<node name>/sync/ptp-status/clock-class",
|
||||
"EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp"}' -H 'Content-Type: application/json'
|
||||
-X POST http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions |
|
||||
python -m json.tool
|
||||
|
||||
# subscribe Os clock
|
||||
|
||||
curl --path-as-is -v -d '{"ResourceAddress": "/././sync/sync-status/os-clock-sync-state",
|
||||
"EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp"}' -H 'Content-Type:
|
||||
application/json' -X POST http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -d '{"ResourceAddress": "/./<node name>/sync/sync-status/os-clock-sync-state",
|
||||
"EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp"}' -H 'Content-Type: application/json'
|
||||
-X POST http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions |
|
||||
python -m json.tool
|
||||
|
||||
# subscribe gnss
|
||||
|
||||
curl --path-as-is -v -d '{"ResourceAddress": "/././sync/gnss-status/gnss-sync-status",
|
||||
"EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp"}' -H 'Content-Type: application/json'
|
||||
-X POST http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions |
|
||||
python -m json.tool
|
||||
curl --path-as-is -v -d '{"ResourceAddress": "/./<node name>/sync/gnss-status/gnss-sync-status",
|
||||
"EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp"}' -H 'Content-Type:
|
||||
application/json' -X POST
|
||||
http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions |
|
||||
python -m json.tool
|
||||
|
||||
## List subscriptions
|
||||
|
||||
curl --path-as-is -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions |
|
||||
python -m json.tool
|
||||
|
||||
# unsubscribe
|
||||
|
||||
curl --path-as-is -X DELETE -v -H 'Content-Type: application/json'
|
||||
http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v2/subscriptions/b3862aa2-3499-11ed-a5b5-522422c3cf7d
|
||||
|
||||
.. image:: figures/cak1614112389132.png
|
||||
:width: 800
|
||||
|
||||
|
||||
@ -0,0 +1,78 @@
|
||||
.. _ptp-notification-status-conditions-6d6105fccf10:
|
||||
|
||||
==================================
|
||||
PTP Notification Status Conditions
|
||||
==================================
|
||||
|
||||
The |PTP| status notifications are derived based on the following conditions:
|
||||
|
||||
.. table::
|
||||
:widths: auto
|
||||
|
||||
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **PTP Lock State** |
|
||||
+=====================+===================================================+===================================================================================================================================================================+
|
||||
| Clock Status | Status | Description |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Freerun | Clock is out of sync state | - If portState is not “SECONDARY” or ClockClass value is NOT "6" or timeTraceable flag is FALSE. |
|
||||
| | | |
|
||||
| | | - If holdover time exceeds its provided value. |
|
||||
| | | |
|
||||
| | | - If PMC, ptp4l.conf, ptp4l or phc2sys are not accessible. |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Locked | Clock is in sync state | If portState is "SECONDARY" and ClockClass value is "6" and timeTraceable flag is TRUE and PMC, ptp4l.conf, ptp4l or phc2sys are accessible. |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Holdover | Clock is in holdover state | * For NICs using the Intel ice driver: If the state is transitioned from ``Locked`` to ``Holdover`` AND phc2sys is accessible, and holdover time does not expire. |
|
||||
| | | |
|
||||
| | | * For other NIC types: If the state is transitioned from ``Locked`` to ``Freerun`` AND phc2sys is accessible, and holdover time does not expire. |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **PTP Clock Class** |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| 6 | T-GM connected to a PRTC in locked mode | * For additional details on clockClass values, refer to ITU-T standard G.8275.1 |
|
||||
| | (e.g., PRTC traceable to GNSS) | |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| 7 | T-GM in holdover, within holdover specification, | |
|
||||
| | traceable to Category 1 frequency source | |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| 135 | T-BC in holdover, within holdover specification | |
|
||||
| | traceable to Category 1 frequency source | |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| 140 | T-GM in holdover, out of holdover specification, | |
|
||||
| | traceable to Category 1 frequency source | |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| 248 | T-GM or T-BC in free-run mode | |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| 255 | Slave only OC (does not send Announce messages) | |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **OS Clock State** |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Locked | Clock is out of sync state | * phc2sys is running and disciplining the os clock |
|
||||
| | | * OS clock is within 1000 ns of 37000000000 expected offset from PHC |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Holdover | Clock is in holdover state | * Holdover timer has not expired |
|
||||
| | | * phc2sys is not running and not disciplining the os clock |
|
||||
| | | * OR os clock offset is outside of range |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Freerun | Clock is in freerun | * Holdover conditions met but holdover timer has expired |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **GNSS State** |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| SYNCHRONIZED | GNSS data is present | * ts2phc is running and disciplining NIC PHC |
|
||||
| | | * NIC driver DPLL reports GNSS state is locked |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| FAILURE-NOFIX | GNSS data is not detected | * ts2phc is not running, NIC PHC is not being disciplined |
|
||||
| | | * NIC driver DPLL reports status other than locked |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **Overall Sync State** |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Locked | Overall state is locked | * All monitored services are Locked or Synchronized (excluding clockClass) |
|
||||
| | | |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **PTP Lock State** |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Holdover | Overall state is in holdover | * One or more monitored services are in a degraded state (holdover or freerun) |
|
||||
| | | * Overall sync state holdover time has not expired |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Freerun | Overall state is freerun | * One or more monitored services are in a degraded state (holdover or freerun) |
|
||||
| | | * Overall sync state holdover time has expired |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
@ -6,19 +6,33 @@
|
||||
PTP Notifications Overview
|
||||
==========================
|
||||
|
||||
|prod-long| supports applications that rely on |PTP| for synchronization. These
|
||||
applications are able to receive |PTP| status notifications from
|
||||
|prod-long| hosting the application.
|
||||
|prod-long| provides ``ptp-notification`` to support applications that rely on
|
||||
|PTP| for time synchronization and require the ability to determine if the system
|
||||
time is out of sync. ``ptp-notification`` provides the ability for user applications
|
||||
to query the sync state of hosts as well as subscribe to push notifications for
|
||||
changes in the sync status.
|
||||
|
||||
|prod-long| provides a Sidecar, which runs with the hosted application in the
|
||||
same pod and communicates with the application via a REST API.
|
||||
|
||||
|prod-long| supports the following features:
|
||||
PTP-notification consists of two main components:
|
||||
|
||||
- The ``ptp-notification`` system application can be installed on nodes
|
||||
using |PTP| clock synchronization. This monitors the various time services
|
||||
and provides the v1 and v2 REST API for clients to query and subscribe to.
|
||||
|
||||
- The ``ptp-notification`` sidecar. This is a container image which can be
|
||||
configured as a sidecar and deployed alongside user applications that wish
|
||||
to use the ``ptp-notification`` API. User applications only need to be
|
||||
aware of the sidecar, making queries and subscriptions via its API.
|
||||
The sidecar handles locating the appropriate ``ptp-notification`` endpoints,
|
||||
executing the query and returning the results to the user application.
|
||||
|
||||
.. _ptp-notifications-overview-ul-ggf-x1f-t4b:
|
||||
|
||||
- Provides the capability to enable application\(s\) subscribe to |PTP| status
|
||||
|prod-long| supports the following features:
|
||||
|
||||
- Provides the capability to enable application(s) subscribe to |PTP| status
|
||||
notifications and pull for the |PTP| state on demand.
|
||||
|
||||
- Uses a REST API to communicate |PTP| notifications to the application.
|
||||
@ -29,57 +43,58 @@ same pod and communicates with the application via a REST API.
|
||||
<https://docs.starlingx.io/api-ref/ptp-notification-armada-app/index.html>`__.
|
||||
|
||||
- Supports the **ptp4l** module and |PTP| port that is configured in
|
||||
Subordinate mode \(Secondary mode\).
|
||||
Subordinate mode (Secondary mode).
|
||||
|
||||
- The |PTP| notification Sidecar container can be configured with a Liveness
|
||||
Probe, if required. See, :ref:`Liveness Probe <liveness-probe>` for more
|
||||
information.
|
||||
|
||||
- The |PTP| status notifications are derived based on the following conditions:
|
||||
|
||||
|
||||
.. _ptp-notifications-overview-simpletable-n1r-dcf-t4b:
|
||||
|
||||
---------------------------------------
|
||||
Differences between v1 and v2 REST APIs
|
||||
---------------------------------------
|
||||
|
||||
.. table::
|
||||
:widths: auto
|
||||
Use of the v1 and v2 APIs is distinguished by the version identifier in the
|
||||
URI when interacting with the sidecar container. Both are always available.
|
||||
For example:
|
||||
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Clock Status | Status | Description |
|
||||
+=====================+===================================================+===================================================================================================================================================================+
|
||||
| Freerun | Clock is out of sync state | - If portState is not "SECONDARY" or ClockClass value is NOT "6, 7 or 135" or timeTraceable flag is FALSE. |
|
||||
| | | |
|
||||
| | | - If holdover time exceeds its provided value. |
|
||||
| | | |
|
||||
| | | - If PMC, ptp4l.conf, ptp4l or phc2sys are not accessible. |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Locked | Clock is in sync state | If portState is "SECONDARY" and ClockClass value is "6, 7 or 135" and timeTraceable flag is TRUE and PMC, ptp4l.conf, ptp4l or phc2sys are accessible. |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Holdover | Clock is in holdover state | * For NICs using the Intel ice driver: If the state is transitioned from ``Locked`` to ``Holdover`` AND phc2sys is accessible, and holdover time does not expire. |
|
||||
| | | |
|
||||
| | | * For other NIC types: If the state is transitioned from ``Locked`` to ``Freerun`` AND phc2sys is accessible, and holdover time does not expire. |
|
||||
+---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
**v1 API**
|
||||
|
||||
- /ocloudNotifications/v1/subscriptions
|
||||
|
||||
- /ocloudNotifications/v2/subscriptions
|
||||
|
||||
The v1 API is maintained for backward compatibility with existing deployments.
|
||||
New deployments should use the v2 API.
|
||||
|
||||
**v1 Limitations**
|
||||
|
||||
- Support for monitoring a single ``ptp4l`` instance per host - no other services
|
||||
can be queried/subscribed to.
|
||||
|
||||
- API does not conform to the O-RAN.WG6.O-Cloud Notification API-v02.01
|
||||
standard.
|
||||
|
||||
See the respective ``ptp-notification`` v1 and v2 document subsections for
|
||||
details on the behaviour.
|
||||
|
||||
**Integrated Containerized Applications**
|
||||
|
||||
.. _ptp-notifications-overview-ul-rn5-5w2-t4b:
|
||||
|
||||
- Applications that rely on |PTP| for synchronization have the ability to
|
||||
retrieve the relevant data that indicates the status of the PHC clock related
|
||||
to the worker node that the application is running on.
|
||||
retrieve the relevant data for the status of the monitored service. User
|
||||
applications may subscribe to notifications from multiple service types
|
||||
and from multiple separate nodes.
|
||||
|
||||
- Once an application subscribes to |PTP| notifications it receives the initial
|
||||
data that shows the PHC synchronization state, and receives notifications when
|
||||
there is a state change to the sync status and/or per request for notification
|
||||
\(pull\).
|
||||
|
||||
data that shows the service state, and receives notifications when there is
|
||||
a state change to the sync status and/or per request for notification (pull).
|
||||
|
||||
The figure below describes the subscription framework for |PTP| notifications.
|
||||
|
||||
.. image:: figures/gvf1614702096862.png
|
||||
:width: 500
|
||||
|
||||
|
||||
**Liveness Probe**
|
||||
|
||||
.. _liveness-probe:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user