Gitiles
Code Review Sign In
gerrit.nordix.org / onap / cps / 841e3df51a819618da69f67b80ebd58fb3935d51 / . / docs / deployment.rst
blob: 61f9ad2943309d20c3e365120341bb8574bdccdc [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
3.. Copyright (C) 2021 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
puthuparambil.aditya841e3df2021-10-05 10:56:04 +0100[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
16--------------
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
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>`_
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
29--------------------------------------
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
94-----------------------------
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
101.. _credentials_retrieval:
102
103Credentials Retrieval
104---------------------
105
106Application and database credentials are kept in Kubernetes secrets. They are defined as external secrets in the
107values.yaml file to be used across different components as :
108
109.. container:: ulist
110
111 - `cps-core <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/values.yaml#L18>`_
112 - `cps-temporal <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-temporal/values.yaml#L28>`_
113 - `ncmp-dmi-plugin <https://github.com/onap/oom/blob/master/kubernetes/cps/components/ncmp-dmi-plugin/values.yaml#L22>`_
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+--------------------------+---------------------------------+---------------------------------------------------+
124| cps-temporal | Rest API Authentication | <my-helm-release>-cps-temporal-app-user-creds |
125+--------------------------+---------------------------------+---------------------------------------------------+
126| cps-temporal | Database authentication | <my-helm-release>-cps-temporal-pg-user-creds |
127+--------------------------+---------------------------------+---------------------------------------------------+
128| ncmp-dmi-plugin | Rest API Authentication | <my-helm-release>-cps-dmi-plugin-user-creds |
129+--------------------------+---------------------------------+---------------------------------------------------+
130| ncmp-dmi-plugin | SDNC authentication | <my-helm-release>-ncmp-dmi-plugin-sdnc-creds |
131+--------------------------+---------------------------------+---------------------------------------------------+
132
133The credential values from these secrets are configured in running container as environment variables. Eg:
134`cps core deployment.yaml <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/templates/deployment.yaml#L46>`_
135
136If no specific passwords are provided to the chart as override values for deployment, then passwords are automatically
137generated when deploying the Helm release. Below command can be used to retrieve application property credentials
138
139.. code::
140
141 kubectl get secret <my-helm-release>-<secret-name> -n <namespace> -o json | jq '.data | map_values(@base64d)'
142
143.. note::
144 base64d works only with jq version 1.6 or above.
145
146CPS Core Pods
147=============
148To get a listing of the cps-core Pods, run the following command:
149
150.. code-block:: bash
151
152 kubectl get pods -n <namespace> | grep cps-core
153
154 dev-cps-core-ccd4cc956-r98pv 1/1 Running 0 24h
155 dev-cps-core-postgres-primary-f7766d46c-s9d5b 1/1 Running 0 24h
156 dev-cps-core-postgres-replica-84659d68f9-6qnt4 1/1 Running 0 24h
157
158
159Additional Cps-Core Customizations
160==================================
161
162The following table lists some properties that can be specified as Helm chart
163values to configure the application to be deployed. This list is not
164exhaustive.
165
166+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
167| Property | Description | Default Value |
168+=======================================+=========================================================================================================+===============================+
169| config.appUserName | User name used by cps-core service to configure the authentication for REST API it exposes. | ``cpsuser`` |
170| | | |
171| | This is the user name to be used by cps-core REST clients to authenticate themselves. | |
172+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
173| config.appUserPassword | Password used by cps-core service to configure the authentication for REST API it exposes. | Not defined |
174| | | |
175| | This is the password to be used by CPS Temporal REST clients to authenticate themselves. | |
176| | | |
177| | If not defined, the password is generated when deploying the application. | |
178| | | |
179| | See also :ref:`credentials_retrieval`. | |
180+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
181| config.dmiPluginUserName | User name used by cps-core to authenticate themselves for using ncmp-dmi-plugin service. | ``dmiuser`` |
182+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
183| config.dmiPluginUserPassword | Internal password used by cps-core to connect to ncmp-dmi-plugin service. | Not defined |
184| | | |
185| | If not defined, the password is generated when deploying the application. | |
186| | | |
187| | See also :ref:`credentials_retrieval`. | |
188+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
189| postgres.config.pgUserName | Internal user name used by cps-core to connect to its own database. | ``cps`` |
190+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
191| postgres.config.pgUserPassword | Internal password used by cps-core to connect to its own database. | Not defined |
192| | | |
193| | If not defined, the password is generated when deploying the application. | |
194| | | |
195| | See also :ref:`credentials_retrieval`. | |
196+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
197| postgres.config.pgDatabase | Database name used by cps-core | ``cpsdb`` |
198| | | |
199+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
200| logging.level | Logging level set in cps-core | info |
201| | | |
202+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
203| config.eventPublisher. | Kafka hostname and port | ``message-router-kafka:9092`` |
204| spring.kafka.bootstrap-servers | | |
205+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
206| config.eventPublisher. | Kafka consumer client id | ``cps-core`` |
207| spring.kafka.consumer.client-id | | |
208+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
209| config.publisher. | Kafka security protocol. | ``PLAINTEXT`` |
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+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
216| config.publisher. | Kafka security SASL mechanism. Required for SASL_PLAINTEXT and SASL_SSL protocols. | Not defined |
217| spring.kafka.properties. | Some possible values are: | |
218| sasl.mechanism | | |
219| | * ``PLAIN``, for PLAINTEXT | |
220| | * ``SCRAM-SHA-512``, for SSL | |
221+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
222| config.publisher. | Kafka security SASL JAAS configuration. Required for SASL_PLAINTEXT and SASL_SSL protocols. | Not defined |
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+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
230| config.publisher. | Kafka security SASL SSL store type. Required for SASL_SSL protocol. | Not defined |
231| spring.kafka.ssl.trust-store-type | Some possible values are: | |
232| | | |
233| | * ``JKS`` | |
234+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
235| config.publisher. | Kafka security SASL SSL store file location. Required for SASL_SSL protocol. | Not defined |
236| spring.kafka.ssl.trust-store-location | | |
237+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
238| config.publisher. | Kafka security SASL SSL store password. Required for SASL_SSL protocol. | Not defined |
239| spring.kafka.ssl.trust-store-password | | |
240+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
241| config.publisher. | Kafka security SASL SSL broker hostname identification verification. Required for SASL_SSL protocol. | Not defined |
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+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
249| config.additional. | If notification from cps-core to cps-temporal is enabled or not. | ``true`` |
250| notification.data-updated.enabled | If this is set to false, then the config.publisher properties could be skipped. | |
251+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
252| config.additional. | Dataspaces to be enabled for publishing events to cps-temporal | ```` |
253| notification.data-updated.filters. | | |
254| enabled-dataspaces | | |
255+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
256| config.additional. | If notifications should be processed in synchronous or asynchronous manner | ``false`` |
257| notification.async.enabled | | |
258+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
259| config.additional. | Core pool size in asynchronous execution of notification. | ``2`` |
260| notification.async.executor. | | |
261| core-pool-size | | |
262+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
263| config.additional. | Max pool size in asynchronous execution of notification. | ``1`` |
264| notification.async.executor. | | |
265| max-pool-size | | |
266+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
267| config.additional. | Queue Capacity in asynchronous execution of notification. | ``500`` |
268| notification.async.executor. | | |
269| queue-capacity | | |
270+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
271| config.additional. | If the executor should wait for the tasks to be completed on shutdown | ``true`` |
272| notification.async.executor. | | |
273| wait-for-tasks-to-complete-on-shutdown| | |
274+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
275| config.additional. | Prefix to be added to the thread name in asynchronous execution of notifications. | ``async_`` |
276| notification.async.executor. | | |
277| thread-name-prefix | | |
278+---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
279
280CPS-Core Docker Installation
281============================
282
283CPS-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.
284The latest instructions are covered in the `README <https://github.com/onap/cps/blob/master/docker-compose/README.md>`_.