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.

v2 API

The API conforms to O-RAN.WG6.O-Cloud Notification API-v02.01. 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

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
   

   1. To configure the ptp-notification v2 API 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
        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. 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.

   2. View existing values.

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

   3. Update and apply the values.

      Application values can be added by the user and applied, using the following commands.

      Note

      Changes to the ptp-notification override values require the application to be removed and re-applied in order to re-create the application containers.

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

Configure Liveness Probes for PTP Notification Pods

Helm overrides can be used to configure liveness probes for the following ptp-notification containers:

• locationservice-base

• notificationservice-base-v2

To enable the liveness probe for each container, include the following in the notification-override.yaml file:

location:
  endpoint:
    port: 8080
    liveness: True
    livenessDelaySeconds: 60
    livenessPeriodSeconds: 3
    livenessFailureThreshold: 3
    livenessTimeoutSeconds: 3
ptptrackingv2:
  endpoint:
    port: 8082
    liveness: True
    livenessDelaySeconds: 60
    livenessPeriodSeconds: 3
    livenessFailureThreshold: 3
    livenessTimeoutSeconds: 3

Apply the override values using the following commands:

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

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:

• PTP Notifications Overview

• https://docs.starlingx.io/api-ref/ptp-notification-armada-app/api_ptp_notifications_definition_v2.html

Change default rabbitmq credentials

PTP Notification deploys two separate rabbitmq instances with a default username and password. These values can be changed using the Helm overrides below:

Procedure

1. Remove the application if it is currently installed

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

2. Create an override file with these entries:

   cat <<EOF>> /home/sysadmin/notification-rabbitmq.yaml
   registration:
       endpoint:
           port: 5672
           user: <new username>
           pass: <new password>
   notification:
       endpoint:
           port: 5672
           user: <new username>
           pass: <new password>
   EOF
   

3. Apply the Helm overrides

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

4. Apply ptp-notification.

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