ab916d4076
Fixed formatting errors
Updated Patchset 4 comments
Updated the location of the PTP Notification application
Fixed formatting errors
Added separate sections for ptptracking and ptptrackingv2
Fixed trailing spaces
Change-Id: I46e3c9663269174b929abfdf6581f4db1bcb16d3
Signed-off-by: Juanita Balaraj <juanita.balaraj@windriver.com>
(cherry picked from commit 9d67e696b8)
339 lines
11 KiB
ReStructuredText
339 lines
11 KiB
ReStructuredText
|
||
.. xqd1614091832213
|
||
.. _install-ptp-notifications:
|
||
|
||
=========================
|
||
Install PTP Notifications
|
||
=========================
|
||
|
||
|PTP| notification is packaged as a system application and is managed
|
||
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-long| provides the capability for application(s) to subscribe to
|
||
asynchronous |PTP| status notifications and pull for the |PTP| state on demand.
|
||
|
||
You must provide Helm override values indicating the ``ptp4l`` and ``phc2sys``
|
||
instances that you want tracked by your ``ptp-notification`` application.
|
||
|
||
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:
|
||
|
||
.. rubric:: |proc|
|
||
|
||
#. Apply labels to nodes that will be running the ``ptp-notification``.
|
||
|
||
#. Apply the registration label to the controller nodes.
|
||
|
||
.. code-block::
|
||
|
||
~(keystone_admin)]$ system host-label-assign controller-0 ptp-registration=true
|
||
|
||
#. 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-notification=true
|
||
~(keystone_admin)]$ system host-label-assign compute-0 ptp-notification=true
|
||
|
||
#. Verify the labels.
|
||
|
||
.. code-block::
|
||
|
||
~(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/ptp-notification-<version>.tgz
|
||
|
||
#. Upload the ``ptp-notification`` application using the command below.
|
||
|
||
.. code-block::
|
||
|
||
~(keystone_admin)]$ system application-upload <path to application>
|
||
|
||
#. Verify if the application is in the uploaded state.
|
||
|
||
.. code-block::
|
||
|
||
~(keystone_admin)]$ system application-list
|
||
|
||
#. Apply Helm overrides as required. Create a yaml file and update the fields
|
||
that require Helm overrides.
|
||
|
||
.. code-block::
|
||
|
||
~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification --values notification-override.yaml
|
||
|
||
.. note::
|
||
|
||
You can override the default values for the ``ptp-notification``
|
||
application either by creating separate override sections for v1
|
||
and v2 APIs or by including v1 and v2 APIs in a single file as
|
||
shown in the example below.
|
||
|
||
.. code-block:: none
|
||
|
||
~(keystone_admin)]$ cat notification-override.yaml
|
||
ptptracking:
|
||
ptp4lServiceName: ptp4l-legacy
|
||
phc2sysServiceName: phc2sys-legacy
|
||
logging_level: INFO
|
||
device:
|
||
holdover_seconds: 15
|
||
poll_freq_seconds: 2
|
||
ptptrackingv2:
|
||
ptp4lServiceName: True
|
||
phc2sysServiceName: True
|
||
ts2phcServiceName: True
|
||
log_level: INFO
|
||
control_timeout: 2
|
||
device:
|
||
holdover_seconds: 15
|
||
osclock:
|
||
holdover_seconds: 15
|
||
overall:
|
||
holdover_seconds: 15
|
||
|
||
#. To configure the ``ptp-notification`` v1 API in a seperate section,
|
||
include the following in the ``notification-override.yaml`` file.
|
||
Ensure that values are updated to match the configured instance
|
||
names on your system.
|
||
|
||
.. code-block:: none
|
||
|
||
ptptracking:
|
||
enabled: True
|
||
ptp4lSocket: /var/run/ptp4l-instancename
|
||
ptp4lServiceName: ptp4l-instancename
|
||
phc2sysServiceName: phc2sys-instancename
|
||
logging_level: INFO
|
||
device:
|
||
holdover_seconds: 15
|
||
poll_freq_seconds: 2
|
||
|
||
``ptptracking``
|
||
|
||
where the values are:
|
||
|
||
``ptp4lSocket``
|
||
Update this value to include the correct instance name of your
|
||
configured ptp4l instance.
|
||
|
||
``ptp4lServiceName``
|
||
Update this value to the instance name of your configured ptp4l
|
||
instance.
|
||
|
||
``phc2sysServiceName``
|
||
Update this value to the instance name of your configure phc2sys
|
||
instance.
|
||
|
||
``logging_level: INFO``
|
||
Set the logging level. DEBUG can be used for additional logs.
|
||
|
||
``holdover_seconds``
|
||
``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 - (poll_freq_seconds * 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.
|
||
|
||
``poll_freq_seconds``
|
||
poll_freq_seconds sets how frequently, in seconds the services are
|
||
checked.
|
||
|
||
#. To configure the ``ptp-notification`` v2 API in a seperate section,
|
||
include the following in the ``notification-override.yaml`` file.
|
||
Ensure that values are updated to match the configured instance
|
||
names on your system.
|
||
|
||
.. code-block:: none
|
||
|
||
ptptrackingv2:
|
||
ptp4lServiceName: True
|
||
phc2sysServiceName: True
|
||
ts2phcServiceName: True
|
||
log_level: INFO
|
||
control_timeout: 2
|
||
device:
|
||
holdover_seconds: 15
|
||
osclock:
|
||
holdover_seconds: 15
|
||
overall:
|
||
holdover_seconds: 15
|
||
|
||
``ptptrackingv2``
|
||
|
||
where the values are:
|
||
|
||
``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``
|
||
``device`` refers to ptp4l monitoring
|
||
|
||
- ``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|
|
||
|
||
|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
|
||
|
||
|