starlingx/docs
Code Issues Proposed changes

Differentiate the ptp-notification behavior between T-GM and T-BC (dsR8)

Browse Source 
Fix indentation and formatting issues

closes-bug: 2039106

Change-Id: Ia1930d060fe7032e37212772de7013dead6ae4c5
Signed-off-by: Elisamara Aoki Goncalves <elisamaraaoki.goncalves@windriver.com>
This commit is contained in:
Elisamara Aoki Goncalves 2023-10-11 20:54:44 +00:00
parent b5d5129244
commit a8cbef9b82
2 changed files with 178 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -71,27 +71,27 @@ For example, follow the steps below:
.. rubric:: |proc| .. rubric:: |proc|
#. Apply labels to nodes that will be running the ``ptp-notification``. #. Apply labels to nodes that will be running the ``ptp-notification``.
#. Apply the registration label to the controller nodes. #. Apply the registration label to the controller nodes.
.. code-block:: .. code-block::
~(keystone_admin)]$ system host-label-assign controller-0 ptp-registration=true ~(keystone_admin)]$ system host-label-assign controller-0 ptp-registration=true
#. Apply the notification label to each node that is configured for PTP #. Apply the notification label to each node that is configured for PTP
clock synchronization. clock synchronization.
.. code-block:: .. code-block::
~(keystone_admin)]$ system host-label-assign controller-0 ptp-notification=true ~(keystone_admin)]$ system host-label-assign controller-0 ptp-notification=true
~(keystone_admin)]$ system host-label-assign compute-0 ptp-notification=true ~(keystone_admin)]$ system host-label-assign compute-0 ptp-notification=true
#. Verify the labels. #. Verify the labels.
.. code-block:: .. code-block::
~(keystone_admin)]$ system host-label-list <node name> ~(keystone_admin)]$ system host-label-list <node name>
#. Locate the application tarball on the system controller. #. Locate the application tarball on the system controller.
@ -117,9 +117,9 @@ For example, follow the steps below:
.. 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
.. note:: .. note::
You can override the default values for the ``ptp-notification`` You can override the default values for the ``ptp-notification``
application either by creating separate override sections for v1 application either by creating separate override sections for v1
and v2 APIs or by including v1 and v2 APIs in a single file as and v2 APIs or by including v1 and v2 APIs in a single file as
@ -132,6 +132,7 @@ For example, follow the steps below:
ptp4lServiceName: ptp4l-legacy ptp4lServiceName: ptp4l-legacy
phc2sysServiceName: phc2sys-legacy phc2sysServiceName: phc2sys-legacy
logging_level: INFO logging_level: INFO
ptp4lClockClassLockedList: "6,7,135"
device: device:
holdover_seconds: 15 holdover_seconds: 15
poll_freq_seconds: 2 poll_freq_seconds: 2
@ -139,6 +140,8 @@ For example, follow the steps below:
ptp4lServiceName: True ptp4lServiceName: True
phc2sysServiceName: True phc2sysServiceName: True
ts2phcServiceName: True ts2phcServiceName: True
ptp4lClockClassLockedList: "6,7,135"
phc2sysToleranceThreshold: 1000
log_level: INFO log_level: INFO
control_timeout: 2 control_timeout: 2
device: device:
@ -148,124 +151,173 @@ For example, follow the steps below:
overall: overall:
holdover_seconds: 15 holdover_seconds: 15
#. To configure the ``ptp-notification`` v1 API in a seperate section, #. To configure the ``ptp-notification`` v1 API in a seperate section,
include the following in the ``notification-override.yaml`` file. include the following in the ``notification-override.yaml`` file.
Ensure that values are updated to match the configured instance Ensure that values are updated to match the configured instance
names on your system. 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: .. code-block:: none
``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`` ptptracking:
Set the logging level. DEBUG can be used for additional logs. enabled: True
ptp4lSocket: /var/run/ptp4l-instancename
ptp4lServiceName: ptp4l-instancename
phc2sysServiceName: phc2sys-instancename
logging_level: INFO
ptp4lClockClassLockedList: "6,7,135"
device:
holdover_seconds: 15
poll_freq_seconds: 2
``holdover_seconds`` ``ptptracking``
``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, where the values are:
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`` ``ptp4lSocket``
Update this value to include the correct instance name of your
configured ptp4l instance.
where the values are: ``ptp4lServiceName``
Update this value to the instance name of your configured ptp4l
``ptp4lServiceName``: True instance.
``phc2sysServiceName``: True ``phc2sysServiceName``
Update this value to the instance name of your configure phc2sys
``ts2phcServiceName``: True instance.
- The ServiceName fields are defaulted to True in the application
and generally do not need to be altered. ``logging_level: INFO``
Set the logging level. DEBUG can be used for additional logs.
- 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 ``ptp4lClockClassLockedList``
(ie. node does not use ts2phc), then the application will automatically Set the list of clock classes that will allow ``ptp-notification``
determine this and not attempt to monitor it. to report **Locked**. The clockClass for a monitored ptp4l instance
is read via the |PMC|. If the instance clockClass matches one of
- Use these fields if there is a service that is configured on the the ``ptp4lClockClassLockedList`` values, then ``ptp-notification``
node but you do NOT wish to track. will report **Locked** for that instance.
``log_level: INFO`` The default values are "6,7,135", which means that
Set the logging level. DEBUG can be used for additional logs. ``ptp-notification`` will report locked when reading a clockClass
of 6, 7 or 135 from the configured ptp4l instance. These values are
``control_timeout: 2`` recommended for nodes operating as Boundary Clock (BC).
For nodes operating as |GM|, it is recommended to set the value to
"6", so that only clockClass 6 is reported as locked.
``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
ptp4lClockClassLockedList: "6,7,135"
phc2sysToleranceThreshold: 1000
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 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
the node (i.e. node does not use ts2phc), then the application
automatically determines this and does not attempt to monitor
the node.
- Use these fields if there is a service that is configured on
the node that you do NOT want to track.
``log_level: INFO``
Set the logging level. DEBUG can be used for additional logs.
``ptp4lClockClassLockedList``
Set the list of clock classes that will allow ``ptp-notification``
to report **Locked**. The clockClass for a monitored ptp4l instance
is read via the |PMC|. If the instance clockClass matches one of
the ``ptp4lClockClassLockedList`` values, then ``ptp-notification``
will report **Locked** for that instance.
The default values are "6,7,135", which means that
``ptp-notification`` will report locked when reading a clockClass
of 6, 7 or 135 from the configured ptp4l instance. These values are
recommended for nodes operating as Boundary Clock (BC).
For nodes operating as |GM|, it is recommended to set the value to
"6", so that only clockClass 6 is reported as locked.
``phc2sysToleranceThreshold``
Default value: 1000
Set the skew threshold in nanoseconds at which ``ptp-notification``
will report that the system clock is no longer considered
**Locked**.
The ``ptp-notification`` application compares the time of the
system clock to the configured source PHC. If the delta between the
system clock and the |PHC| is greater than the
``phc2sysToleranceThreshold``, a notification will be generated
that the system clock is not locked.
``control_timeout: 2``
control_timeout sets how frequently, in seconds the services are checked. control_timeout sets how frequently, in seconds the services are checked.
Value applies to all service types. Value applies to all service types.
``device`` ``device``
``device`` refers to ptp4l monitoring ``device`` refers to ptp4l monitoring
- ``holdover_seconds``: 15 - ``holdover_seconds: 15``
- ``poll_freq_seconds``: 2 - ``poll_freq_seconds: 2``
``osclock``: ``osclock``
holdover_seconds: 15 holdover_seconds: 15
``overall``: ``overall``
``holdover_seconds``: 15 holdover_seconds: 15
``holdover_seconds`` configures how long each service will stay in ``holdover_seconds`` configures how long each service will stay
the HOLDOVER state before transitioning to FREERUN. The holdover in the HOLDOVER state before transitioning to FREERUN. The
value used by the application equates to: holdover value used by the application equates to:
holdover_seconds - (control_timeout * 2). holdover_seconds - (control_timeout * 2).
This is done in order to account for time between the monitor This is done in order to account for time between the monitor
polling cycles. The ``holdover_seconds`` value should be polling cycles. The ``holdover_seconds`` value should be
configured to match the validated holdover time provided by the configured to match the validated holdover time provided by the
device manufacturer. device manufacturer.
#. View existing values. #. View existing values.
.. code-block:: none .. code-block:: none
@ -278,10 +330,14 @@ For example, follow the steps below:
.. note:: .. note::
The application could be in the "uploaded" or "applied" state. Changes to the ``ptp-notification`` override values require the
application to be removed and re-applied in order to re-create the
application containers.
.. code-block:: none .. code-block:: none
~(keystone_admin)]$ system application-remove ptp-notification
~(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>
~(keystone_admin)]$ system application-apply ptp-notification ~(keystone_admin)]$ system application-apply ptp-notification

2
doc/source/shared/abbrevs.txt
View File

@ -55,6 +55,7 @@
.. |FPGA| replace:: :abbr:`FPGA (Field Programmable Gate Array)` .. |FPGA| replace:: :abbr:`FPGA (Field Programmable Gate Array)`
.. |FQDN| replace:: :abbr:`FQDN (Fully Qualified Domain Name)` .. |FQDN| replace:: :abbr:`FQDN (Fully Qualified Domain Name)`
.. |FQDNs| replace:: :abbr:`FQDNs (Fully Qualified Domain Names)` .. |FQDNs| replace:: :abbr:`FQDNs (Fully Qualified Domain Names)`
.. |GM| replace:: :abbr:`GM (Grand Master)`
.. |GNP| replace:: :abbr:`GNP (Global Network Policy)` .. |GNP| replace:: :abbr:`GNP (Global Network Policy)`
.. |GNPs| replace:: :abbr:`GNPs (Global Network Policies)` .. |GNPs| replace:: :abbr:`GNPs (Global Network Policies)`
.. |GNSS| replace:: :abbr:`GNSS (Global Navigation Satellite System)` .. |GNSS| replace:: :abbr:`GNSS (Global Navigation Satellite System)`
@ -119,6 +120,7 @@
.. |PHB| replace:: :abbr:`PHB (Per-Hop Behavior)` .. |PHB| replace:: :abbr:`PHB (Per-Hop Behavior)`
.. |PHC| replace:: :abbr:`PHC (PTP Hardware Clock)` .. |PHC| replace:: :abbr:`PHC (PTP Hardware Clock)`
.. |PHCs| replace:: :abbr:`PHC (PTP Hardware Clock)` .. |PHCs| replace:: :abbr:`PHC (PTP Hardware Clock)`
.. |PMC| replace:: :abbr:`PMC (PTP Management Client)`
.. |PMD| replace:: :abbr:`PMD (Pole Mode Driver)` .. |PMD| replace:: :abbr:`PMD (Pole Mode Driver)`
.. |PQDN| replace:: :abbr:`PDQN (Partially Qualified Domain Name)` .. |PQDN| replace:: :abbr:`PDQN (Partially Qualified Domain Name)`
.. |PQDNs| replace:: :abbr:`PQDNs (Partially Qualified Domain Names)` .. |PQDNs| replace:: :abbr:`PQDNs (Partially Qualified Domain Names)`