Gitiles
Code Review Sign In
gerrit.nordix.org / onap / cps / 14e5bf958bb2b114e3e7d8876bd6f031900c79ec / . / docs / deployment.rst
blob: 82c54f12c67008d65f2d53b978e86410f30cb6af [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>`__
23 - `cps-temporal <https://github.com/onap/oom/tree/master/kubernetes/cps/components/cps-temporal>`__
24 - `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]25
26Please refer to the `OOM documentation <https://docs.onap.org/projects/onap-oom/en/latest/oom_user_guide.html>`_ on how to install and deploy ONAP.
27
28Installing or Upgrading CPS Components
Bruno Sakotoa1129b62022-03-15 08:09:07 -0400[diff] [blame]29======================================
30
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]31The assumption is you have cloned the charts from the OOM repository into a local directory.
32
33**Step 1** Go to the cps charts and edit properties in values.yaml files to make any changes to particular cps component if required.
34
35.. code-block:: bash
36
37 cd oom/kubernetes/cps/components/<cps-component-name>
38
39**Step 2** Build the charts
40
41.. code-block:: bash
42
43 cd oom/kubernetes
44 make SKIP_LINT=TRUE cps
45
46.. note::
47 SKIP_LINT is only to reduce the "make" time
48
49**Step 3** Undeploying already deployed cps components
50
51After undeploying cps components, keep monitoring the cps pods until they go away.
52
53.. code-block:: bash
54
55 helm del --purge <my-helm-release>-<cps-component-name>
56 kubectl get pods -n <namespace> | grep <cps-component-name>
57
58**Step 4** Make sure there is no orphan database persistent volume or claim.
59
60First, find if there is an orphan database PV or PVC with the following commands:
61
62.. note::
63 This step does not apply to ncmp-dmi-plugin.
64
65.. code-block:: bash
66
67 kubectl get pvc -n <namespace> | grep <cps-component-name>
68 kubectl get pv -n <namespace> | grep <cps-component-name>
69
70If there are any orphan resources, delete them with
71
72.. code-block:: bash
73
74 kubectl delete pvc <orphan-cps-core-pvc-name>
75 kubectl delete pv <orphan-cps-core-pv-name>
76
77**Step 5** Delete NFS persisted data for CPS components
78
79Connect to the machine where the file system is persisted and then execute the below command
80
81.. code-block:: bash
82
83 rm -fr /dockerdata-nfs/<my-helm-release>/<cps-component-name>
84
85**Step 6** Re-Deploy cps pods
86
87After deploying cps, keep monitoring the cps pods until they come up.
88
89.. code-block:: bash
90
91 helm deploy <my-helm-release> local/cps --namespace <namespace>
92 kubectl get pods -n <namespace> | grep <cps-component-name>
93
94Restarting a faulty component
Bruno Sakotoa1129b62022-03-15 08:09:07 -0400[diff] [blame]95=============================
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]96Each cps component can be restarted independently by issuing the following command:
97
98.. code-block:: bash
99
100 kubectl delete pod <cps-component-pod-name> -n <namespace>
101
ToineSiebelink39207852021-10-21 12:11:25 +0100[diff] [blame]102.. Below Label is used by documentation for other CPS components to link here, do not remove even if it gives a warning
103.. _cps_common_credentials_retrieval:
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]104
105Credentials Retrieval
Bruno Sakotoa1129b62022-03-15 08:09:07 -0400[diff] [blame]106=====================
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]107
108Application and database credentials are kept in Kubernetes secrets. They are defined as external secrets in the
109values.yaml file to be used across different components as :
110
111.. container:: ulist
112
113 - `cps-core <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/values.yaml#L18>`_
114 - `cps-temporal <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-temporal/values.yaml#L28>`_
115 - `ncmp-dmi-plugin <https://github.com/onap/oom/blob/master/kubernetes/cps/components/ncmp-dmi-plugin/values.yaml#L22>`_
116
117Below are the list of secrets for different cps components.
118
119+--------------------------+---------------------------------+---------------------------------------------------+
120| Component | Secret type | Secret Name |
121+==========================+=================================+===================================================+
122| cps-core | Database authentication | <my-helm-release>-cps-core-pg-user-creds |
123+--------------------------+---------------------------------+---------------------------------------------------+
124| cps-core | Rest API Authentication | <my-helm-release>-cps-core-app-user-creds |
125+--------------------------+---------------------------------+---------------------------------------------------+
126| cps-temporal | Rest API Authentication | <my-helm-release>-cps-temporal-app-user-creds |
127+--------------------------+---------------------------------+---------------------------------------------------+
128| cps-temporal | Database authentication | <my-helm-release>-cps-temporal-pg-user-creds |
129+--------------------------+---------------------------------+---------------------------------------------------+
130| ncmp-dmi-plugin | Rest API Authentication | <my-helm-release>-cps-dmi-plugin-user-creds |
131+--------------------------+---------------------------------+---------------------------------------------------+
132| ncmp-dmi-plugin | SDNC authentication | <my-helm-release>-ncmp-dmi-plugin-sdnc-creds |
133+--------------------------+---------------------------------+---------------------------------------------------+
134
135The credential values from these secrets are configured in running container as environment variables. Eg:
136`cps core deployment.yaml <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/templates/deployment.yaml#L46>`_
137
138If no specific passwords are provided to the chart as override values for deployment, then passwords are automatically
139generated when deploying the Helm release. Below command can be used to retrieve application property credentials
140
141.. code::
142
143 kubectl get secret <my-helm-release>-<secret-name> -n <namespace> -o json | jq '.data | map_values(@base64d)'
144
145.. note::
146 base64d works only with jq version 1.6 or above.
147
148CPS Core Pods
149=============
150To get a listing of the cps-core Pods, run the following command:
151
152.. code-block:: bash
153
154 kubectl get pods -n <namespace> | grep cps-core
155
156 dev-cps-core-ccd4cc956-r98pv 1/1 Running 0 24h
157 dev-cps-core-postgres-primary-f7766d46c-s9d5b 1/1 Running 0 24h
158 dev-cps-core-postgres-replica-84659d68f9-6qnt4 1/1 Running 0 24h
159
DylanB95EST34fdca82022-05-06 10:43:58 +0100[diff] [blame]160.. note::
161 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]162
DylanB95EST34fdca82022-05-06 10:43:58 +0100[diff] [blame]163Additional CPS-Core Customizations
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]164==================================
165
166The following table lists some properties that can be specified as Helm chart
Renu Kumarifb4caa62022-03-21 09:18:41 -0400[diff] [blame]167values to configure the application to be deployed. This list is not exhaustive.
168
169Any 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]170
171+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
172| Property | Description | Default Value |
173+=======================================+=========================================================================================================+===============================+
174| config.appUserName | User name used by cps-core service to configure the authentication for REST API it exposes. | ``cpsuser`` |
175| | | |
176| | This is the user name to be used by cps-core REST clients to authenticate themselves. | |
177+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
178| config.appUserPassword | Password used by cps-core service to configure the authentication for REST API it exposes. | Not defined |
179| | | |
180| | This is the password to be used by CPS Temporal REST clients to authenticate themselves. | |
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+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]186| postgres.config.pgUserName | Internal user name used by cps-core to connect to its own database. | ``cps`` |
187+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
188| postgres.config.pgUserPassword | Internal password used by cps-core to connect to its own database. | Not defined |
189| | | |
190| | If not defined, the password is generated when deploying the application. | |
191| | | |
lukegleesonf027cfb2021-11-08 15:53:12 +0000[diff] [blame]192| | See also :ref:`cps_common_credentials_retrieval`. | |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]193+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
194| postgres.config.pgDatabase | Database name used by cps-core | ``cpsdb`` |
195| | | |
196+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
197| logging.level | Logging level set in cps-core | info |
198| | | |
199+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
lukegleeson4a34fa52022-09-19 15:31:59 +0100[diff] [blame]200| config.useStrimziKafka | If targeting a custom kafka cluster, ie useStrimziKafka: false, the config.eventPublisher.spring.kafka | true |
201| | values below must be set. | |
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]202+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
203| config.eventPublisher. | Kafka hostname and port | ``<kafka-bootstrap>:9092`` |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]204| spring.kafka.bootstrap-servers | | |
205+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
206| config.eventPublisher. | Kafka consumer client id | ``cps-core`` |
207| spring.kafka.consumer.client-id | | |
208+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]209| config.eventPublisher. | Kafka security protocol. | ``SASL_PLAINTEXT`` |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]210| spring.kafka.security.protocol | Some possible values are: | |
211| | | |
212| | * ``PLAINTEXT`` | |
213| | * ``SASL_PLAINTEXT``, for authentication | |
214| | * ``SASL_SSL``, for authentication and encryption | |
215+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]216| 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]217| spring.kafka.properties. | Some possible values are: | |
218| sasl.mechanism | | |
219| | * ``PLAIN``, for PLAINTEXT | |
220| | * ``SCRAM-SHA-512``, for SSL | |
221+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]222| 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]223| spring.kafka.properties. | Some possible values are: | |
224| sasl.jaas.config | | |
225| | * ``org.apache.kafka.common.security.plain.PlainLoginModule required username="..." password="...";``, | |
226| | for PLAINTEXT | |
227| | * ``org.apache.kafka.common.security.scram.ScramLoginModule required username="..." password="...";``, | |
228| | for SSL | |
229+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]230| 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]231| spring.kafka.ssl.trust-store-type | Some possible values are: | |
232| | | |
233| | * ``JKS`` | |
234+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]235| 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]236| spring.kafka.ssl.trust-store-location | | |
237+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]238| 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]239| spring.kafka.ssl.trust-store-password | | |
240+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
efiacorb8691812022-03-15 11:26:46 +0000[diff] [blame]241| 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]242| spring.kafka.properties. | Possible value is: | |
243| ssl.endpoint.identification.algorithm | | |
244| | * ``""``, empty string to disable | |
245+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
246| config.additional. | Kafka topic to publish to cps-temporal | ``cps.data-updated-events`` |
247| notification.data-updated.topic | | |
248+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
emacleeb176de22022-08-31 15:53:10 +0100[diff] [blame]249| config.additional. | Dataspaces to be enabled for publishing events to cps-temporal | |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]250| notification.data-updated.filters. | | |
251| enabled-dataspaces | | |
252+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
emacleeb176de22022-08-31 15:53:10 +0100[diff] [blame]253| config.additional. | If asynchronous messaging, user notifications, and updated event persistence should be enabled | ``true`` |
lukegleeson4a34fa52022-09-19 15:31:59 +0100[diff] [blame]254| notification.data-updated.enabled | | |
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]255+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
256| config.additional. | Core pool size in asynchronous execution of notification. | ``2`` |
257| notification.async.executor. | | |
258| core-pool-size | | |
259+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
260| config.additional. | Max pool size in asynchronous execution of notification. | ``1`` |
261| notification.async.executor. | | |
262| max-pool-size | | |
263+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
264| config.additional. | Queue Capacity in asynchronous execution of notification. | ``500`` |
265| notification.async.executor. | | |
266| queue-capacity | | |
267+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
268| config.additional. | If the executor should wait for the tasks to be completed on shutdown | ``true`` |
269| notification.async.executor. | | |
270| wait-for-tasks-to-complete-on-shutdown| | |
271+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
lukegleeson4a34fa52022-09-19 15:31:59 +0100[diff] [blame]272| 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]273| notification.async.executor. | | |
274| thread-name-prefix | | |
275+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
Renu Kumarifb4caa62022-03-21 09:18:41 -0400[diff] [blame]276| config.additional. | Specifies number of database connections between database and application. | ``10`` |
277| spring.datasource.hikari. | This property controls the maximum size that the pool is allowed to reach, | |
278| maximumPoolSize | including both idle and in-use connections. | |
279+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]280
DylanB95ESTdc656472022-08-08 15:22:54 +0100[diff] [blame]281.. _additional-cps-ncmp-customizations:
282
DylanB95EST34fdca82022-05-06 10:43:58 +0100[diff] [blame]283Additional CPS-NCMP Customizations
284==================================
285+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
286| config.dmiPluginUserName | User name used by cps-core to authenticate themselves for using ncmp-dmi-plugin service. | ``dmiuser`` |
287+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
288| config.dmiPluginUserPassword | Internal password used by cps-core to connect to ncmp-dmi-plugin service. | Not defined |
289| | | |
290| | If not defined, the password is generated when deploying the application. | |
291| | | |
292| | See also :ref:`cps_common_credentials_retrieval`. | |
293+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
lukegleeson4a34fa52022-09-19 15:31:59 +0100[diff] [blame]294| config.ncmp.timers | Specifies the delay in milliseconds in which the module sync watch dog will wake again after finishing. | ``30000`` |
295| .advised-modules-sync.sleep-time-ms | | |
DylanB95EST34fdca82022-05-06 10:43:58 +0100[diff] [blame]296| | | |
297+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
lukegleeson4a34fa52022-09-19 15:31:59 +0100[diff] [blame]298| config.ncmp.timers | Specifies the delay in milliseconds in which the retry mechanism watch dog | |
299| .locked-modules-sync.sleep-time-ms | will wake again after finishing. | ``300000`` |
300| | | |
DylanB95ESTdc656472022-08-08 15:22:54 +0100[diff] [blame]301| | | |
302+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
lukegleeson4a34fa52022-09-19 15:31:59 +0100[diff] [blame]303| config.ncmp.timers | Specifies the delay in milliseconds in which the data sync watch dog will wake again after finishing. | ``30000`` |
304| .cm-handle-data-sync.sleep-time-ms | | |
DylanB95ESTdc656472022-08-08 15:22:54 +0100[diff] [blame]305| | | |
306+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
DylanB95EST34fdca82022-05-06 10:43:58 +0100[diff] [blame]307
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[diff] [blame]308CPS-Core Docker Installation
309============================
310
311CPS-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.
312The latest instructions are covered in the `README <https://github.com/onap/cps/blob/master/docker-compose/README.md>`_.