Merge "Updated PTP sidecar container liveness probe timeouts (r6, r7, r8, dsr6, dsr7, dsr8)" into r/stx.7.0

doc/source/guest_integration/kubernetes/integrate-application-with-notification-client-sidecar.rst

@@ -43,6 +43,298 @@ 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.
+
+.. note::
+
+    The following example is for ``ptp-notification`` v2 API. To integrate
+    with ``ptp-notification`` v1 API, change the image from ``starlingx/notificationclient-base:stx.9.0-v2.1.1``
+    to ``starlingx/notificationclient-base:stx.5.0-v1.0.4``.
+
+.. parsed-literal::
+
+    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:|v_starlingx-notificationclient-base|"
+               imagePullPolicy: IfNotPresent
+               tty: true
+               stdin: true
+               livenessProbe:
+               exec:
+                 command:
+                 - curl
+                 - http://127.0.0.1:8080/health
+               failureThreshold: 3
+               initialDelaySeconds: 30
+               periodSeconds: 5
+               successThreshold: 1
+               timeoutSeconds: 5
+            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/<subscription id> |
+    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 <name> 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 "/./<node name>"
+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/./<node name>/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/./<node name>/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/./<node name>/<ptp instance name>/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/./<node name>/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/./<node name>/<ptp instance name>/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/./<node name>/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/./<node name>/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": "/./<node name>/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": "/./<node name>/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": "/./<node name>/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": "/./<node name>/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": "/./<node name>/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

doc/source/guest_integration/kubernetes/ptp-notifications-overview.rst

@@ -89,7 +89,11 @@ probe, if required. You can edit the Sidecar values in the deployment
 manifest to include these parameters.
 
 .. note::
+    
     Port and timeout values can be configured to meet user preferences.
+    The ``periodSeconds`` and ``timeoutSeconds`` values can be adjusted based
+    on system performance. A shorter value places more resource demand on the
+    Sidecar pod, so longer values can improve pod stability.
 
 .. code-block:: none
 
@@ -102,13 +106,36 @@ manifest to include these parameters.
             livenessProbe:
               exec:
                 command:
-                - timeout
-                - "2"
                 - curl
                 - http://127.0.0.1:8080/health
               failureThreshold: 3
-              periodSeconds: 3
+              initialDelaySeconds: 30
+              periodSeconds: 5
               successThreshold: 1
-              timeoutSeconds: 3
+              timeoutSeconds: 5
     EOF
 
+**Container images and API compatibility**
+
+The ``ptp-notification`` provides a v1 API for backwards compatibility with
+client applications deployed on |prod| |prod-ver|, as well as a v2 API for
+O-RAN Spec Compliant Timing notifications. By default, ``ptp-notification``
+deploys two ``notificationservice-base`` containers to support these APIs.
+Users must decide which API they will use by deploying the appropriate
+``notificationclient-base`` image as a sidecar with their consumer application.
+
+-   The v1 API uses ``starlingx/notificationservice-base:stx.9.0-v2.1.1``
+
+    -   Compatible with the image:
+        ``starlingx/notificationclient-base:stx.5.0-v1.0.4``
+
+-   The v2 API uses ``starlingx/notificationservice-base-v2:stx.9.0-v2.1.1``
+
+    -   Compatible with the image:
+        ``starlingx/notificationclient-base:stx.9.0-v2.1.1``
+
+Upgrades of |prod| |prod-ver| to the next patch will automatically upgrade the
+``ptp-notification`` application and deploy both the v1 and v2 API containers.
+Consumer applications determine which API they interact with based on the
+version of ``notificationclient-base`` that is deployed along side their
+application.