Install PTP Notifications

PTP notification is packaged as a system application and is managed using the system application and 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 system ptp-instance-apply, requires the ptp-notification application to be removed and reapplied, using the system application-remove ptp-notification, and 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 StarlingX Release 22.12. A specific subscription for each resource type must be created instead.

About this task

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

Procedure

  1. Apply labels to nodes that will be running the ptp-notification.

    1. Apply the registration label to the controller nodes.

      ~(keystone_admin)]$ system host-label-assign controller-0 ptp-registration=true

    2. Apply the notification label to each node that is configured for PTP clock synchronization.

      ~(keystone_admin)]$ system host-label-assign controller-0 ptp-notification=true
~(keystone_admin)]$ system host-label-assign compute-0 ptp-notification=true

    3. Verify the labels.

      ~(keystone_admin)]$ system host-label-list <node name>

  2. Locate the application tarball on the system controller.

    ~(keystone_admin)]$ ls /usr/local/share/applications/helm/ptp-notification-<version>.tgz

  3. Upload the ptp-notification application using the command below.

    ~(keystone_admin)]$ system application-upload <path to application>

  4. Verify if the application is in the uploaded state.

    ~(keystone_admin)]$ system application-list

  5. Apply Helm overrides as required. Create a yaml file and update the fields that require Helm overrides.

    ~(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.

    ~(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

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

      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.

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

      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.

    3. View existing values.

      ~(keystone_admin)]$ system helm-override-show ptp-notification ptp-notification notification

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

      ~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification -–values <notification-override.yaml>

~(keystone_admin)]$ system application-apply ptp-notification

  6. Verify the Helm overrides.

    ~(keystone_admin)]$ system helm-override-show ptp-notification ptp-notification notification

  7. Apply ptp-notification using the command below.

    ~(keystone_admin)]$ system application-apply ptp-notification

  8. Verify application status and pod status using the following commands:

    1. Application Status

      ~(keystone_admin)]$ system application-list

    2. Pod Status

      ~(keystone_admin)]$ kubectl get pods -n notification -o wide

Postrequisites

StarlingX supports applications that rely on PTP for synchronization. These applications are able to receive PTP status notifications from StarlingX hosting the application. For more information see: