starlingx/docs
Code Issues Proposed changes

Fixed figure width.

Browse Source 
Worked on the comments.
Corrected broken link in index.
Added container integration guide.

Signed-off-by: Adil <mohamed.adilassakkali@windriver.com>
Change-Id: Id9d8e1abd8f15a51d9069cf7543e1b559a118369
This commit is contained in:
Adil 2021-03-24 11:45:44 -03:00
parent 101421ffa1
commit 716f387f93
10 changed files with 569 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/source/container_integration/figures/cak1614112389132.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

BIN
doc/source/container_integration/figures/gvf1614702096862.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 90 KiB

164
doc/source/container_integration/kubernetes/create-test-and-terminate-a-ptp-notification-demo.rst Normal file
View File

@ -0,0 +1,164 @@
.. jff1614105111370
.. _create-test-and-terminate-a-ptp-notification-demo:
===================================================
Create, Test, and Terminate a PTP Notification Demo
===================================================
This section provides instructions on accessing, creating, testing and
terminating a **ptp-notification-demo**.
.. rubric:: |context|
Use the following procedure to copy the tarball from |dnload-loc|, create, test,
and terminate a ptp-notification-demo.
.. rubric:: |proc|
.. _create-test-and-terminate-a-ptp-notification-demo-steps-irz-5w4-t4b:
#. Copy the **ptp-notification-demo\_v1.0.2.tgz** file from |prod-long|
at `http://mirror.starlingx.cengn.ca/mirror/starlingx/
<http://mirror.starlingx.cengn.ca/mirror/starlingx/>`__ to yor system, and extract its content.
.. note::
The tarball includes the docker file and code to build the reference
API application, and the Helm chart to install the Sidecar along with
the application.
The following files are part of the tarball:
- Helm charts
- Chart.yaml
- values.yaml
- \_helpers.tpl
- configmap.yaml
- deployment.yaml
- .helmignore
- ptp-notification-override.yaml
- app\_start.sh
- sidecar\_start.sh
- notification-docker
- Dockerfile
- api
.. note::
The demo uses the following images:
- starlingx/notificationclient-base:stx.5.0-v1.0.3
- ptp-base:1.0.1
#. Build the **ptp-base:1.0.1** image using the following commands.
.. code-block:: none
$ tar xvf ptp-notification-demo_<v1.0.2>.tgz
$ cd ~/notification-dockers/ptp-base/
$ sudo docker build . -t ptp-base:1.0.1
$ sudo docker save ptp-base:1.0.1 -o ptp-base.1.0.1.tar
$ sudo ctr -n k8s.io image import ./ptp-base.1.0.1.tar
$ cd ~/charts
$ tar xvf ptp-notification-demo-1.tgz
.. note::
For |AIO|-SX and AIO-DX systems, ptp-base.1.0.1.tar should be copied to
each node and the import command, :command:`sudo ctr -n k8s.io image
import ./ptp-base.1.0.1.tar` should be run on each node.
#. Install the demo's pod using the following commands.
.. note::
This pod includes two containers, Sidecar and the referenced API
application.
.. code-block:: none
$ kubectl create namespace ptpdemo
$ helm install -n notification-demo ~/charts/ptp-notification-demo -f ~/charts/ptp-notification-demo/ptp-notification-override.yaml
$ kubectl get pods -n ptpdemo
.. code-block:: none
NAME READY STATUS RESTARTS AGE
notification-demo-ptp-notification-demo-cf7b65c47-s5jk6 2/2 Running 0 5m50s
#. Test the **ptp-notification** demo.
#. Display the app logs using the following command.
.. code-block:: none
$ kubectl logs -f notification-demo-ptp-notification-demo-<xyz> -c ptp-notification-demo-app -n ptpdemo
#. In another terminal, access the application container.
.. code-block:: none
$ kubectl exec -it notification-demo-ptp-notification-demo-<zyz> -c ptp-notification-demo-app -n ptpdemo -- bash
#. Check if you can pull |PTP| status using the REST API.
.. code-block:: none
$ curl -v -H 'Content-Type: application/json' http://127.0.0.1:8080/ocloudNotifications/v1/PTP/CurrentState
#. Subscribe to |PTP| notifications.
.. code-block:: none
$ curl -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:${SIDECAR_API_PORT}/ocloudNotifications/v1/subscriptions |python -m json.tool
#. Retrieve a list of subscriptions.
.. code-block:: none
$ curl -v -H 'Content-Type: application/json' http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v1/subscriptions |python -m json.tool
For example, to get a specific subscription, use the following command.
.. code-block:: none
$ curl -v -H 'Content-Type: application/json' http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v1/subscriptions/<subscriptionId>
#. To delete a specific subscription with the subscription ID, run the
following command.
.. code-block:: none
$ curl -X DELETE -v -H 'Content-Type: application/json' http://127.0.0.1:${SIDECAR_API_PORT}/ocloudNotifications/v1/subscriptions/<subscriptionId>
#. Terminate the demo using the following command.
.. code-block:: none
$ helm del --purge notification-demo

19
doc/source/container_integration/kubernetes/index.rst Normal file
View File

@ -0,0 +1,19 @@
=====================
Container Integration
=====================
----------------
PTP Notification
----------------
.. toctree::
:maxdepth: 1
ptp-notifications-overview
install-ptp-notifications
remove-ptp-notifications
override-default-application-values
integrate-the-application-with-notification-client-sidecar
create-test-and-terminate-a-ptp-notification-demo

132
doc/source/container_integration/kubernetes/install-ptp-notifications.rst Normal file
View File

@ -0,0 +1,132 @@
.. xqd1614091832213
.. _install-ptp-notifications:
=========================
Install PTP Notifications
=========================
|PTP| notification is packaged as an Armada system application and is managed
using the :command:`system application` and :command:`system-helm-override`
commands.
.. rubric:: |context|
|prod| provides the capability for application\(s\) to subscribe to
asynchronous |PTP| status notifications and pull for the |PTP| state on demand.
.. rubric:: |prereq|
.. _install-ptp-notifications-ul-ydy-ggf-t4b:
- The |PTP| port must be configured as Subordinate mode \(Slave mode\). For
more information, see,
.. xbooklink :ref:`|prod-long| System Configuration
<system-configuration-management-overview>`:
- :ref:`Configuring PTP Service Using Horizon <configuring-ptp-service-using-horizon>`
- :ref:`Configuring PTP Service Using the CLI <configuring-ptp-service-using-the-cli>`
.. rubric:: |context|
Use the following steps to install the **ptp-notification** application.
.. rubric:: |proc|
#. Label the controller\(s\).
#. Source the platform environment.
.. code-block:: none
$ source /etc/platform/openrc
~(keystone_admin)]$
#. Assign the |PTP| registration label to the controller\(s\).
.. code-block:: none
~(keystone_admin)]$ system host-label-assign controller-0 ptp-registration=true
~(keystone_admin)]$ system host-label-assign controller-1 ptp-registration=true
#. Assign the |PTP| notification label to the node that is configured with
a Slave |PTP| port. For example:
.. code-block:: none
~(keystone_admin)]$ system host-label-assign controller-0 ptp-notification=true
#. Upload the |PTP| application using the following command:
.. code-block:: none
~(keystone_admin)]$ system application-upload /usr/local/share/applications/helm/ptp-notification-1.0-26.tgz
#. Verify the |PTP| application has been uploaded.
.. code-block:: none
~(keystone_admin)]$ system application-list
#. Apply the |PTP| notification application.
.. code-block:: none
$ system application-apply ptp-notification
#. Monitor the status.
.. code-block:: none
$ watch –n 5 system application-list
and/or
.. code-block:: none
$ watch kubectl get pods –n notification
The default configuration for |PTP| notification pod is:
- |PTP|-notification pod:
- Runs as a daemonset \(1 pod per node with label **ptp-notification=true**\)
- Three containers:
- ptp-notification-rabbitmq
- ptp-notification-location
- ptp-notification-ptptracking
- Registration pod:
- Runs as a deployment on nodes labeled with **ptp-registration=true**
- Replica count of 1
- One container: Rabbitmq

52
doc/source/container_integration/kubernetes/integrate-the-application-with-notification-client-sidecar.rst Normal file
View File

@ -0,0 +1,52 @@
.. yxg1614092306444
.. _integrate-the-application-with-notification-client-sidecar:
==========================================================
Integrate the Application with Notification Client Sidecar
==========================================================
This section describes the **ptp-notification-demo**, and provides instructions
for enabling communication between the Sidecar and the application via a REST
API.
.. rubric:: |context|
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
application and the Sidecar communicate via a REST API. See the figure below.
.. note::
In this demo, we provide a referenced API application.
.. rubric:: |prereq|
The following prerequisites are required before the integration:
.. _integrate-the-application-with-notification-client-sidecar-ul-iyd-mxf-t4b:
- The cloud is configured with a node that supports the Subordinate mode \(Slave mode\).
- The cloud is labeled with **ptp-registration=true**, and **ptp-notification=true**.
- The **ptp-notification-armada-app** application is installed successfully.
- The application supports the |PTP| Notifications API.
.. image:: ../figures/cak1614112389132.png
:width: 800
For instructions on creating, testing and terminating a
**ptp-notification-demo**, see, :ref:`Create, Test, and Terminate |PTP|
Notification Demo <create-test-and-terminate-a-ptp-notification-demo>`.

60
doc/source/container_integration/kubernetes/override-default-application-values.rst Normal file
View File

@ -0,0 +1,60 @@
.. 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 <<override.yaml>>
.. 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.

92
doc/source/container_integration/kubernetes/ptp-notifications-overview.rst Normal file
View File

@ -0,0 +1,92 @@
.. nko1614009294405
.. _ptp-notifications-overview:
==========================
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 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-notifications-overview-ul-ggf-x1f-t4b:
- 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.
- Enables operators to install the **ptp-notification-armada-app**, Sidecar
container, and the application supporting the REST API. For more information,
see, `https://docs.starlingx.io/api-ref/ptp-notification-armada-app/index.html
<https://docs.starlingx.io/api-ref/ptp-notification-armada-app/index.html>`__.
- Supports the **ptp4l** module and |PTP| port that is configured in
Subordinate mode \(Slave mode\).
- The |PTP| status notifications are derived based on the following conditions:
.. _ptp-notifications-overview-simpletable-n1r-dcf-t4b:
.. table::
:widths: auto
+---------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| Clock Status | Status | Description |
+=====================+===================================================+====================================================================================================================================================+
| Freerun | Clock is out of sync state | - If portState is not "SLAVE" 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 "SLAVE" 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 | If the state is transitioned from "Locked" to "Freerun" AND phc2sys is accessible, and holdover time does not expire. |
+---------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
**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.
- 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\).
The figure below describes the subscription framework for |PTP| notifications.
.. image:: ../figures/gvf1614702096862.png
For more information on |PTP| notifications, see:
.. _ptp-notifications-overview-ul-xqg-2wg-t4b:
- :ref:`Install PTP Notifications <install-ptp-notifications>`
- :ref:`Remove PTP Notifications <remove-ptp-notifications>`
- :ref:`Override Default Application Values <override-default-application-values>`
- :ref:`Integrate the Application with Notification Client Sidecar <integrate-the-application-with-notification-client-sidecar>`

41
doc/source/container_integration/kubernetes/remove-ptp-notifications.rst Normal file
View File

@ -0,0 +1,41 @@
.. nie1614092105640
.. _remove-ptp-notifications:
========================
Remove PTP Notifications
========================
You can remove all pods and Kubernetes resources created during the Armada
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 Armada
deployment, using the following command:
.. code-block:: none
~(keystone_admin)]$ system application-remove ptp-notification
#. Delete the ptp-notification from sysinv.
.. code-block:: none
~(keystone_admin)]$ system application-delete ptp-notification
#. Remove labels applied to controller-0, 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

9
doc/source/index.rst
View File

@ -165,6 +165,15 @@ Backup and restore
backup/index backup/index
---------------------
Container integration
---------------------
.. toctree::
:maxdepth: 2
container_integration/kubernetes/index
--------- ---------
Reference Reference
--------- ---------