starlingx/docs
Code Issues Proposed changes

Merge "O-RAN Spec Compliant Timing API Notification"

Browse Source
This commit is contained in:
Zuul
2022-12-21 01:28:38 +00:00
committed by Gerrit Code Review
parent f01c69c1e4 d6ae8c5fb1
commit a83f9ab5fe
9 changed files with 643 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/source/_includes/install-ptp-notifications-3a94b1ea1ae3.rest Normal file
View File

@@ -0,0 +1,3 @@

1
doc/source/admintasks/kubernetes/index-admintasks-kub-ebc55fefc368.rst
View File

@@ -79,7 +79,6 @@ PTP Notifications
install-ptp-notifications
remove-ptp-notifications
override-default-application-values
------------------
O-RAN O2 Interface

225
doc/source/admintasks/kubernetes/install-ptp-notifications.rst
View File

@@ -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::
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::
~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification --values notification-override.yaml
You can override the default values for the ``ptp-notification`` application:
#. 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
.. 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

60
doc/source/admintasks/kubernetes/override-default-application-values.rst
View File

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

21
doc/source/admintasks/kubernetes/remove-ptp-notifications.rst
View File

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

1
doc/source/guest_integration/kubernetes/index-guest-kub-5c89ec07e141.rst
View File

@@ -17,4 +17,5 @@ PTP Notification
ptp-notifications-overview
integrate-application-with-notification-client-sidecar
ptp-notification-status-conditions-6d6105fccf10

302
doc/source/guest_integration/kubernetes/integrate-application-with-notification-client-sidecar.rst
View File

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

78
doc/source/guest_integration/kubernetes/ptp-notification-status-conditions-6d6105fccf10.rst Normal file
View File

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

85
doc/source/guest_integration/kubernetes/ptp-notifications-overview.rst
View File

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