From d6ae8c5fb1bed1504b0c86f0bce624c455eef292 Mon Sep 17 00:00:00 2001 From: Juanita-Balaraj Date: Tue, 13 Dec 2022 19:30:47 -0500 Subject: [PATCH] O-RAN Spec Compliant Timing API Notification Modified PTP Status Notification Table Added Includes file Updated example for kubernetes deployment of the sidecar and a simulated application Fixed formatting Updated Patchset 1 comments Removed override-default-application topic Fixed Table formatting Updated PTP Sections with modified content Signed-off-by: Juanita-Balaraj Change-Id: I7805615b1bbd44a541a12220b4497529cf714360 --- ...nstall-ptp-notifications-3a94b1ea1ae3.rest | 3 + .../index-admintasks-kub-ebc55fefc368.rst | 1 - .../kubernetes/install-ptp-notifications.rst | 237 +++++++++++--- .../override-default-application-values.rst | 60 ---- .../kubernetes/remove-ptp-notifications.rst | 21 +- .../index-guest-kub-5c89ec07e141.rst | 1 + ...ation-with-notification-client-sidecar.rst | 302 ++++++++++++++++++ ...ication-status-conditions-6d6105fccf10.rst | 78 +++++ .../kubernetes/ptp-notifications-overview.rst | 85 +++-- 9 files changed, 643 insertions(+), 145 deletions(-) create mode 100644 doc/source/_includes/install-ptp-notifications-3a94b1ea1ae3.rest delete mode 100644 doc/source/admintasks/kubernetes/override-default-application-values.rst create mode 100644 doc/source/guest_integration/kubernetes/ptp-notification-status-conditions-6d6105fccf10.rst diff --git a/doc/source/_includes/install-ptp-notifications-3a94b1ea1ae3.rest b/doc/source/_includes/install-ptp-notifications-3a94b1ea1ae3.rest new file mode 100644 index 000000000..b28b04f64 --- /dev/null +++ b/doc/source/_includes/install-ptp-notifications-3a94b1ea1ae3.rest @@ -0,0 +1,3 @@ + + + diff --git a/doc/source/admintasks/kubernetes/index-admintasks-kub-ebc55fefc368.rst b/doc/source/admintasks/kubernetes/index-admintasks-kub-ebc55fefc368.rst index 7d4d5f3c2..086fa492c 100644 --- a/doc/source/admintasks/kubernetes/index-admintasks-kub-ebc55fefc368.rst +++ b/doc/source/admintasks/kubernetes/index-admintasks-kub-ebc55fefc368.rst @@ -79,7 +79,6 @@ PTP Notifications install-ptp-notifications remove-ptp-notifications - override-default-application-values ------------------ O-RAN O2 Interface diff --git a/doc/source/admintasks/kubernetes/install-ptp-notifications.rst b/doc/source/admintasks/kubernetes/install-ptp-notifications.rst index 9b6fb8c93..338ed76ed 100644 --- a/doc/source/admintasks/kubernetes/install-ptp-notifications.rst +++ b/doc/source/admintasks/kubernetes/install-ptp-notifications.rst @@ -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 - `: - -.. 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 + +#. Locate the application tarball on the system controller. + + .. code-block:: + + ~(keystone_admin)]$ ls /usr/local/share/applications/helm/stx-ptp-notification-helm-2..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 -#. 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:: + .. 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:: + .. 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 -#. Apply ``ptp-notification`` using the command below. + You can override the default values for the ``ptp-notification`` application: - .. code-block:: + #. 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 + + ~(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 - ~(keystone_admin)]$ system application-apply ptp-notification .. 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 ` - `API PTP Notifications `__ + +.. only:: partner + + .. include:: /_includes/install-ptp-notifications-3a94b1ea1ae3.rest diff --git a/doc/source/admintasks/kubernetes/override-default-application-values.rst b/doc/source/admintasks/kubernetes/override-default-application-values.rst deleted file mode 100644 index 5a5872293..000000000 --- a/doc/source/admintasks/kubernetes/override-default-application-values.rst +++ /dev/null @@ -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 - - .. 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. - - diff --git a/doc/source/admintasks/kubernetes/remove-ptp-notifications.rst b/doc/source/admintasks/kubernetes/remove-ptp-notifications.rst index 9ebcd4146..29f08ee8c 100644 --- a/doc/source/admintasks/kubernetes/remove-ptp-notifications.rst +++ b/doc/source/admintasks/kubernetes/remove-ptp-notifications.rst @@ -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 ptp-notification + ~(keystone_admin)]$ system host-label-remove ptp-registration diff --git a/doc/source/guest_integration/kubernetes/index-guest-kub-5c89ec07e141.rst b/doc/source/guest_integration/kubernetes/index-guest-kub-5c89ec07e141.rst index 079cbdc34..03ade6c8d 100644 --- a/doc/source/guest_integration/kubernetes/index-guest-kub-5c89ec07e141.rst +++ b/doc/source/guest_integration/kubernetes/index-guest-kub-5c89ec07e141.rst @@ -17,4 +17,5 @@ PTP Notification ptp-notifications-overview integrate-application-with-notification-client-sidecar + ptp-notification-status-conditions-6d6105fccf10 diff --git a/doc/source/guest_integration/kubernetes/integrate-application-with-notification-client-sidecar.rst b/doc/source/guest_integration/kubernetes/integrate-application-with-notification-client-sidecar.rst index e87c0076a..ed140d15c 100644 --- a/doc/source/guest_integration/kubernetes/integrate-application-with-notification-client-sidecar.rst +++ b/doc/source/guest_integration/kubernetes/integrate-application-with-notification-client-sidecar.rst @@ -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/ | + 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 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 "/./" +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/.//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/.//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/.///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/.//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/.///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/.//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/.//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": "/.//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": "/.//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": "/.//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": "/.//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": "/.//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 diff --git a/doc/source/guest_integration/kubernetes/ptp-notification-status-conditions-6d6105fccf10.rst b/doc/source/guest_integration/kubernetes/ptp-notification-status-conditions-6d6105fccf10.rst new file mode 100644 index 000000000..49985cf74 --- /dev/null +++ b/doc/source/guest_integration/kubernetes/ptp-notification-status-conditions-6d6105fccf10.rst @@ -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 | + +---------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/doc/source/guest_integration/kubernetes/ptp-notifications-overview.rst b/doc/source/guest_integration/kubernetes/ptp-notifications-overview.rst index cbbaa4b2c..afa389fc9 100644 --- a/doc/source/guest_integration/kubernetes/ptp-notifications-overview.rst +++ b/doc/source/guest_integration/kubernetes/ptp-notifications-overview.rst @@ -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. `__. - 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 ` 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: