Gitiles
Code Review Sign In
gerrit.nordix.org / onap / cps / deee6fff07452d230a4599eb136bded69d4cb595 / . / docs / deployment.rst
blob: eb5804e5bff236d2458cae3d29ccf056b8a3a72b [file] [log] [blame]
shivasubedi44beaa32021-09-13 15:16:30 +0100[diff] [blame]1.. This work is licensed under a Creative Commons Attribution 4.0 International License.
2.. http://creativecommons.org/licenses/by/4.0
DylanB95ESTdc656472022-08-08 15:22:54 +0100[diff] [blame]3.. Copyright (C) 2021-2022 Nordix Foundation
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]4.. Modifications Copyright (C) 2021 Bell Canada.
shivasubedi44beaa32021-09-13 15:16:30 +0100[diff] [blame]5
6.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
7.. _deployment:
8
shivasubedi44beaa32021-09-13 15:16:30 +0100[diff] [blame]9CPS Deployment
Bruno Sakotoa1129b62022-03-15 08:09:07 -0400[diff] [blame]10##############
shivasubedi44beaa32021-09-13 15:16:30 +0100[diff] [blame]11
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]12.. contents::
13 :depth: 2
shivasubedi44beaa32021-09-13 15:16:30 +0100[diff] [blame]14
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]15CPS OOM Charts
Bruno Sakotoa1129b62022-03-15 08:09:07 -0400[diff] [blame]16==============
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]17The CPS kubernetes chart is located in the `OOM repository <https://github.com/onap/oom/tree/master/kubernetes/cps>`_.
18This chart includes different cps components referred as <cps-component-name> further in the document are listed below:
19
20.. container:: ulist
21
emacleeb176de22022-08-31 15:53:10 +0100[diff] [blame]22 - `cps-core <https://github.com/onap/oom/tree/master/kubernetes/cps/components/cps-core>`__
emacleeb176de22022-08-31 15:53:10 +0100[diff] [blame]23 - `ncmp-dmi-plugin <https://github.com/onap/oom/tree/master/kubernetes/cps/components/ncmp-dmi-plugin>`__
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]24
mpriyankb673b542022-11-09 09:36:24 +0000[diff] [blame]25Please refer to the `OOM documentation <https://docs.onap.org/projects/onap-oom/en/latest/sections/guides/user_guides/oom_user_guide.html>`_ on how to install and deploy ONAP.
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]26
27Installing or Upgrading CPS Components
Bruno Sakotoa1129b62022-03-15 08:09:07 -0400[diff] [blame]28======================================
29
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]30The assumption is you have cloned the charts from the OOM repository into a local directory.
31
32**Step 1** Go to the cps charts and edit properties in values.yaml files to make any changes to particular cps component if required.
33
34.. code-block:: bash
35
36 cd oom/kubernetes/cps/components/<cps-component-name>
37
38**Step 2** Build the charts
39
40.. code-block:: bash
41
42 cd oom/kubernetes
43 make SKIP_LINT=TRUE cps
44
45.. note::
46 SKIP_LINT is only to reduce the "make" time
47
48**Step 3** Undeploying already deployed cps components
49
50After undeploying cps components, keep monitoring the cps pods until they go away.
51
52.. code-block:: bash
53
54 helm del --purge <my-helm-release>-<cps-component-name>
55 kubectl get pods -n <namespace> | grep <cps-component-name>
56
57**Step 4** Make sure there is no orphan database persistent volume or claim.
58
59First, find if there is an orphan database PV or PVC with the following commands:
60
61.. note::
62 This step does not apply to ncmp-dmi-plugin.
63
64.. code-block:: bash
65
66 kubectl get pvc -n <namespace> | grep <cps-component-name>
67 kubectl get pv -n <namespace> | grep <cps-component-name>
68
69If there are any orphan resources, delete them with
70
71.. code-block:: bash
72
73 kubectl delete pvc <orphan-cps-core-pvc-name>
74 kubectl delete pv <orphan-cps-core-pv-name>
75
76**Step 5** Delete NFS persisted data for CPS components
77
78Connect to the machine where the file system is persisted and then execute the below command
79
80.. code-block:: bash
81
82 rm -fr /dockerdata-nfs/<my-helm-release>/<cps-component-name>
83
84**Step 6** Re-Deploy cps pods
85
86After deploying cps, keep monitoring the cps pods until they come up.
87
88.. code-block:: bash
89
90 helm deploy <my-helm-release> local/cps --namespace <namespace>
91 kubectl get pods -n <namespace> | grep <cps-component-name>
92
93Restarting a faulty component
Bruno Sakotoa1129b62022-03-15 08:09:07 -0400[diff] [blame]94=============================
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]95Each cps component can be restarted independently by issuing the following command:
96
97.. code-block:: bash
98
99 kubectl delete pod <cps-component-pod-name> -n <namespace>
100
ToineSiebelink39207852021-10-21 12:11:25 +0100[diff] [blame]101.. Below Label is used by documentation for other CPS components to link here, do not remove even if it gives a warning
102.. _cps_common_credentials_retrieval:
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]103
104Credentials Retrieval
Bruno Sakotoa1129b62022-03-15 08:09:07 -0400[diff] [blame]105=====================
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]106
107Application and database credentials are kept in Kubernetes secrets. They are defined as external secrets in the
108values.yaml file to be used across different components as :
109
110.. container:: ulist
111
lukegleesonfb7005f2023-07-07 15:12:17 +0100[diff] [blame]112 - `cps-core <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/values.yaml>`_
lukegleesonfb7005f2023-07-07 15:12:17 +0100[diff] [blame]113 - `ncmp-dmi-plugin <https://github.com/onap/oom/blob/master/kubernetes/cps/components/ncmp-dmi-plugin/values.yaml>`_
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]114
115Below are the list of secrets for different cps components.
116
117+--------------------------+---------------------------------+---------------------------------------------------+
118| Component | Secret type | Secret Name |
119+==========================+=================================+===================================================+
120| cps-core | Database authentication | <my-helm-release>-cps-core-pg-user-creds |
121+--------------------------+---------------------------------+---------------------------------------------------+
122| cps-core | Rest API Authentication | <my-helm-release>-cps-core-app-user-creds |
123+--------------------------+---------------------------------+---------------------------------------------------+
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]124| ncmp-dmi-plugin | Rest API Authentication | <my-helm-release>-cps-dmi-plugin-user-creds |
125+--------------------------+---------------------------------+---------------------------------------------------+
126| ncmp-dmi-plugin | SDNC authentication | <my-helm-release>-ncmp-dmi-plugin-sdnc-creds |
127+--------------------------+---------------------------------+---------------------------------------------------+
128
129The credential values from these secrets are configured in running container as environment variables. Eg:
lukegleesonfb7005f2023-07-07 15:12:17 +0100[diff] [blame]130`cps core deployment.yaml <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/templates/deployment.yaml>`_
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]131
132If no specific passwords are provided to the chart as override values for deployment, then passwords are automatically
133generated when deploying the Helm release. Below command can be used to retrieve application property credentials
134
135.. code::
136
137 kubectl get secret <my-helm-release>-<secret-name> -n <namespace> -o json | jq '.data | map_values(@base64d)'
138
139.. note::
140 base64d works only with jq version 1.6 or above.
141
142CPS Core Pods
143=============
144To get a listing of the cps-core Pods, run the following command:
145
146.. code-block:: bash
147
148 kubectl get pods -n <namespace> | grep cps-core
149
150 dev-cps-core-ccd4cc956-r98pv 1/1 Running 0 24h
151 dev-cps-core-postgres-primary-f7766d46c-s9d5b 1/1 Running 0 24h
152 dev-cps-core-postgres-replica-84659d68f9-6qnt4 1/1 Running 0 24h
153
DylanB95EST34fdca82022-05-06 10:43:58 +0100[diff] [blame]154.. note::
155 The CPS Service will have to be restarted each time a change is made to a configurable property.
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]156
DylanB95EST34fdca82022-05-06 10:43:58 +0100[diff] [blame]157Additional CPS-Core Customizations
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]158==================================
159
160The following table lists some properties that can be specified as Helm chart
Renu Kumarifb4caa62022-03-21 09:18:41 -0400[diff] [blame]161values to configure the application to be deployed. This list is not exhaustive.
162
163Any spring supported property can be configured by providing in ``config.additional.<spring-supported-property-name>: value`` Example: config.additional.spring.datasource.hikari.maximumPoolSize: 30
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]164
165+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
166| Property | Description | Default Value |
167+=======================================+=========================================================================================================+===============================+
168| config.appUserName | User name used by cps-core service to configure the authentication for REST API it exposes. | ``cpsuser`` |
169| | | |
170| | This is the user name to be used by cps-core REST clients to authenticate themselves. | |
171+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
172| config.appUserPassword | Password used by cps-core service to configure the authentication for REST API it exposes. | Not defined |
173| | | |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]174| | If not defined, the password is generated when deploying the application. | |
175| | | |
lukegleesonf027cfb2021-11-08 15:53:12 +0000[diff] [blame]176| | See also :ref:`cps_common_credentials_retrieval`. | |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]177+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]178| postgres.config.pgUserName | Internal user name used by cps-core to connect to its own database. | ``cps`` |
179+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
180| postgres.config.pgUserPassword | Internal password used by cps-core to connect to its own database. | Not defined |
181| | | |
182| | If not defined, the password is generated when deploying the application. | |
183| | | |
lukegleesonf027cfb2021-11-08 15:53:12 +0000[diff] [blame]184| | See also :ref:`cps_common_credentials_retrieval`. | |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]185+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
186| postgres.config.pgDatabase | Database name used by cps-core | ``cpsdb`` |
187| | | |
188+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
189| logging.level | Logging level set in cps-core | info |
190| | | |
191+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
ToineSiebelink74eed2c2023-08-31 17:38:52 +0100[diff] [blame]192| config.useStrimziKafka | If targeting a custom kafka cluster, i.e. useStrimziKafka: false, the | true |
193| | config.eventPublisher.spring.kafka values below must be set. | |
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]194+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
195| config.eventPublisher. | Kafka hostname and port | ``<kafka-bootstrap>:9092`` |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]196| spring.kafka.bootstrap-servers | | |
197+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
198| config.eventPublisher. | Kafka consumer client id | ``cps-core`` |
199| spring.kafka.consumer.client-id | | |
200+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]201| config.eventPublisher. | Kafka security protocol. | ``SASL_PLAINTEXT`` |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]202| spring.kafka.security.protocol | Some possible values are: | |
203| | | |
204| | * ``PLAINTEXT`` | |
205| | * ``SASL_PLAINTEXT``, for authentication | |
206| | * ``SASL_SSL``, for authentication and encryption | |
207+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]208| config.eventPublisher. | Kafka security SASL mechanism. Required for SASL_PLAINTEXT and SASL_SSL protocols. | Not defined |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]209| spring.kafka.properties. | Some possible values are: | |
210| sasl.mechanism | | |
211| | * ``PLAIN``, for PLAINTEXT | |
212| | * ``SCRAM-SHA-512``, for SSL | |
213+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]214| config.eventPublisher. | Kafka security SASL JAAS configuration. Required for SASL_PLAINTEXT and SASL_SSL protocols. | Not defined |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]215| spring.kafka.properties. | Some possible values are: | |
216| sasl.jaas.config | | |
217| | * ``org.apache.kafka.common.security.plain.PlainLoginModule required username="..." password="...";``, | |
218| | for PLAINTEXT | |
219| | * ``org.apache.kafka.common.security.scram.ScramLoginModule required username="..." password="...";``, | |
220| | for SSL | |
221+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]222| config.eventPublisher. | Kafka security SASL SSL store type. Required for SASL_SSL protocol. | Not defined |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]223| spring.kafka.ssl.trust-store-type | Some possible values are: | |
224| | | |
225| | * ``JKS`` | |
226+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]227| config.eventPublisher. | Kafka security SASL SSL store file location. Required for SASL_SSL protocol. | Not defined |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]228| spring.kafka.ssl.trust-store-location | | |
229+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]230| config.eventPublisher. | Kafka security SASL SSL store password. Required for SASL_SSL protocol. | Not defined |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]231| spring.kafka.ssl.trust-store-password | | |
232+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]233| config.eventPublisher. | Kafka security SASL SSL broker hostname identification verification. Required for SASL_SSL protocol. | Not defined |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]234| spring.kafka.properties. | Possible value is: | |
235| ssl.endpoint.identification.algorithm | | |
236| | * ``""``, empty string to disable | |
237+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
emacleeb176de22022-08-31 15:53:10 +0100[diff] [blame]238| config.additional. | If asynchronous messaging, user notifications, and updated event persistence should be enabled | ``true`` |
lukegleeson4a34fa52022-09-19 15:31:59 +0100[diff] [blame]239| notification.data-updated.enabled | | |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]240+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
241| config.additional. | Core pool size in asynchronous execution of notification. | ``2`` |
242| notification.async.executor. | | |
243| core-pool-size | | |
244+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
245| config.additional. | Max pool size in asynchronous execution of notification. | ``1`` |
246| notification.async.executor. | | |
247| max-pool-size | | |
248+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
249| config.additional. | Queue Capacity in asynchronous execution of notification. | ``500`` |
250| notification.async.executor. | | |
251| queue-capacity | | |
252+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
253| config.additional. | If the executor should wait for the tasks to be completed on shutdown | ``true`` |
254| notification.async.executor. | | |
255| wait-for-tasks-to-complete-on-shutdown| | |
256+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
lukegleeson4a34fa52022-09-19 15:31:59 +0100[diff] [blame]257| config.additional. | Prefix to be added to the thread name in asynchronous execution of notifications. | ``Async-`` |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]258| notification.async.executor. | | |
259| thread-name-prefix | | |
260+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
Renu Kumarifb4caa62022-03-21 09:18:41 -0400[diff] [blame]261| config.additional. | Specifies number of database connections between database and application. | ``10`` |
262| spring.datasource.hikari. | This property controls the maximum size that the pool is allowed to reach, | |
263| maximumPoolSize | including both idle and in-use connections. | |
264+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]265
DylanB95ESTdc656472022-08-08 15:22:54 +0100[diff] [blame]266.. _additional-cps-ncmp-customizations:
267
DylanB95EST34fdca82022-05-06 10:43:58 +0100[diff] [blame]268Additional CPS-NCMP Customizations
269==================================
270+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
271| config.dmiPluginUserName | User name used by cps-core to authenticate themselves for using ncmp-dmi-plugin service. | ``dmiuser`` |
272+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
273| config.dmiPluginUserPassword | Internal password used by cps-core to connect to ncmp-dmi-plugin service. | Not defined |
274| | | |
275| | If not defined, the password is generated when deploying the application. | |
276| | | |
277| | See also :ref:`cps_common_credentials_retrieval`. | |
278+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
lukegleeson4a34fa52022-09-19 15:31:59 +0100[diff] [blame]279| config.ncmp.timers | Specifies the delay in milliseconds in which the module sync watch dog will wake again after finishing. | ``30000`` |
280| .advised-modules-sync.sleep-time-ms | | |
DylanB95EST34fdca82022-05-06 10:43:58 +0100[diff] [blame]281| | | |
282+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
lukegleeson4a34fa52022-09-19 15:31:59 +0100[diff] [blame]283| config.ncmp.timers | Specifies the delay in milliseconds in which the retry mechanism watch dog | |
284| .locked-modules-sync.sleep-time-ms | will wake again after finishing. | ``300000`` |
285| | | |
DylanB95ESTdc656472022-08-08 15:22:54 +0100[diff] [blame]286| | | |
287+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
lukegleeson4a34fa52022-09-19 15:31:59 +0100[diff] [blame]288| config.ncmp.timers | Specifies the delay in milliseconds in which the data sync watch dog will wake again after finishing. | ``30000`` |
289| .cm-handle-data-sync.sleep-time-ms | | |
DylanB95ESTdc656472022-08-08 15:22:54 +0100[diff] [blame]290| | | |
291+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
DylanB95EST34fdca82022-05-06 10:43:58 +0100[diff] [blame]292
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]293CPS-Core Docker Installation
294============================
295
296CPS-Core can also be installed in a docker environment. Latest `docker-compose <https://github.com/onap/cps/blob/master/docker-compose/docker-compose.yml>`_ is included in the repo to start all the relevant services.
297The latest instructions are covered in the `README <https://github.com/onap/cps/blob/master/docker-compose/README.md>`_.
mpriyankb45c8092023-09-13 11:42:05 +0100[diff] [blame]298
mpriyank1ae90802023-11-27 13:53:12 +0000[diff] [blame]299.. Below Label is used by documentation for other CPS components to link here, do not remove even if it gives a warning
300.. _cps_common_distributed_datastructures:
301
mpriyankb45c8092023-09-13 11:42:05 +0100[diff] [blame]302CPS-Core and NCMP Distributed Datastructures
303============================================
304
305CPS-Core and NCMP both internally uses embedded distributed datastructure to replicate the state across various instances for low latency.
306These instances require some additional ports to be available. The default range starts from 5701 and based on the number of instances configured they are incremented sequentially.
307
308Below are the list of distributed datastructures that we have.
309
310+--------------+---------------------------------+----------------------------------------------------------+
311| Component | Datastructure name | Use |
312+==============+=================================+==========================================================+
313| cps-core | anchorDataCache | Used to resolve prefix for the container name. |
314+--------------+---------------------------------+----------------------------------------------------------+
315| cps-ncmp | moduleSyncStartedOnCmHandles | Watchdog process to register cmHandles. |
316+--------------+---------------------------------+----------------------------------------------------------+
317| cps-ncmp | dataSyncSemaphores | Watchdog process to sync data from the nodes. |
318+--------------+---------------------------------+----------------------------------------------------------+
319| cps-ncmp | moduleSyncWorkQueue | Queue used internally for workers to pick the task. |
320+--------------+---------------------------------+----------------------------------------------------------+
321| cps-ncmp | forwardedSubscriptionEventCache | Keeps track of the LCM Subscription Events. |
322+--------------+---------------------------------+----------------------------------------------------------+
323| cps-ncmp | untrustworthyCmHandlesSet | Stores untrustworthy cmHandles whose TrustLevel is NONE. |
324+--------------+---------------------------------+----------------------------------------------------------+
325| cps-ncmp | trustLevelPerDmiPlugin | Stores the TrustLevel for the dmi-plugins. |
326+--------------+---------------------------------+----------------------------------------------------------+
leventecsanyi928c1eb2023-09-26 12:57:57 +0200[diff] [blame]327| cps-ncmp | moduleSetTagCacheMapConfig | Stores the Module Set Tags for cmHandles. |
328+--------------+---------------------------------+----------------------------------------------------------+
mpriyankb45c8092023-09-13 11:42:05 +0100[diff] [blame]329
ToineSiebelinkd0e4a9c2023-11-08 17:29:50 +0000[diff] [blame]330Total number of caches : 8