| shivasubedi | 44beaa3 | 2021-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.aditya | 841e3df | 2021-10-05 10:56:04 +0100 | [diff] [blame] | 4 | .. Modifications Copyright (C) 2021 Bell Canada. |
| shivasubedi | 44beaa3 | 2021-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 | |
| shivasubedi | 44beaa3 | 2021-09-13 15:16:30 +0100 | [diff] [blame] | 9 | CPS Deployment |
| puthuparambil.aditya | 841e3df | 2021-10-05 10:56:04 +0100 | [diff] [blame] | 10 | ============== |
| shivasubedi | 44beaa3 | 2021-09-13 15:16:30 +0100 | [diff] [blame] | 11 | |
| puthuparambil.aditya | 841e3df | 2021-10-05 10:56:04 +0100 | [diff] [blame] | 12 | .. contents:: |
| 13 | :depth: 2 |
| shivasubedi | 44beaa3 | 2021-09-13 15:16:30 +0100 | [diff] [blame] | 14 | |
| puthuparambil.aditya | 841e3df | 2021-10-05 10:56:04 +0100 | [diff] [blame] | 15 | CPS OOM Charts |
| 16 | -------------- |
| 17 | The CPS kubernetes chart is located in the `OOM repository <https://github.com/onap/oom/tree/master/kubernetes/cps>`_. |
| 18 | This 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 | |
| 26 | Please 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 | |
| 28 | Installing or Upgrading CPS Components |
| 29 | -------------------------------------- |
| 30 | The 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 | |
| 50 | After 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 | |
| 59 | First, 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 | |
| 69 | If 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 | |
| 78 | Connect 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 | |
| 86 | After 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 | |
| 93 | Restarting a faulty component |
| 94 | ----------------------------- |
| 95 | Each 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 | |
| ToineSiebelink | 3920785 | 2021-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.aditya | 841e3df | 2021-10-05 10:56:04 +0100 | [diff] [blame] | 103 | |
| 104 | Credentials Retrieval |
| 105 | --------------------- |
| 106 | |
| 107 | Application and database credentials are kept in Kubernetes secrets. They are defined as external secrets in the |
| 108 | values.yaml file to be used across different components as : |
| 109 | |
| 110 | .. container:: ulist |
| 111 | |
| 112 | - `cps-core <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/values.yaml#L18>`_ |
| 113 | - `cps-temporal <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-temporal/values.yaml#L28>`_ |
| 114 | - `ncmp-dmi-plugin <https://github.com/onap/oom/blob/master/kubernetes/cps/components/ncmp-dmi-plugin/values.yaml#L22>`_ |
| 115 | |
| 116 | Below are the list of secrets for different cps components. |
| 117 | |
| 118 | +--------------------------+---------------------------------+---------------------------------------------------+ |
| 119 | | Component | Secret type | Secret Name | |
| 120 | +==========================+=================================+===================================================+ |
| 121 | | cps-core | Database authentication | <my-helm-release>-cps-core-pg-user-creds | |
| 122 | +--------------------------+---------------------------------+---------------------------------------------------+ |
| 123 | | cps-core | Rest API Authentication | <my-helm-release>-cps-core-app-user-creds | |
| 124 | +--------------------------+---------------------------------+---------------------------------------------------+ |
| 125 | | cps-temporal | Rest API Authentication | <my-helm-release>-cps-temporal-app-user-creds | |
| 126 | +--------------------------+---------------------------------+---------------------------------------------------+ |
| 127 | | cps-temporal | Database authentication | <my-helm-release>-cps-temporal-pg-user-creds | |
| 128 | +--------------------------+---------------------------------+---------------------------------------------------+ |
| 129 | | ncmp-dmi-plugin | Rest API Authentication | <my-helm-release>-cps-dmi-plugin-user-creds | |
| 130 | +--------------------------+---------------------------------+---------------------------------------------------+ |
| 131 | | ncmp-dmi-plugin | SDNC authentication | <my-helm-release>-ncmp-dmi-plugin-sdnc-creds | |
| 132 | +--------------------------+---------------------------------+---------------------------------------------------+ |
| 133 | |
| 134 | The credential values from these secrets are configured in running container as environment variables. Eg: |
| 135 | `cps core deployment.yaml <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/templates/deployment.yaml#L46>`_ |
| 136 | |
| 137 | If no specific passwords are provided to the chart as override values for deployment, then passwords are automatically |
| 138 | generated when deploying the Helm release. Below command can be used to retrieve application property credentials |
| 139 | |
| 140 | .. code:: |
| 141 | |
| 142 | kubectl get secret <my-helm-release>-<secret-name> -n <namespace> -o json | jq '.data | map_values(@base64d)' |
| 143 | |
| 144 | .. note:: |
| 145 | base64d works only with jq version 1.6 or above. |
| 146 | |
| 147 | CPS Core Pods |
| 148 | ============= |
| 149 | To get a listing of the cps-core Pods, run the following command: |
| 150 | |
| 151 | .. code-block:: bash |
| 152 | |
| 153 | kubectl get pods -n <namespace> | grep cps-core |
| 154 | |
| 155 | dev-cps-core-ccd4cc956-r98pv 1/1 Running 0 24h |
| 156 | dev-cps-core-postgres-primary-f7766d46c-s9d5b 1/1 Running 0 24h |
| 157 | dev-cps-core-postgres-replica-84659d68f9-6qnt4 1/1 Running 0 24h |
| 158 | |
| 159 | |
| 160 | Additional Cps-Core Customizations |
| 161 | ================================== |
| 162 | |
| 163 | The following table lists some properties that can be specified as Helm chart |
| 164 | values to configure the application to be deployed. This list is not |
| 165 | exhaustive. |
| 166 | |
| 167 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 168 | | Property | Description | Default Value | |
| 169 | +=======================================+=========================================================================================================+===============================+ |
| 170 | | config.appUserName | User name used by cps-core service to configure the authentication for REST API it exposes. | ``cpsuser`` | |
| 171 | | | | | |
| 172 | | | This is the user name to be used by cps-core REST clients to authenticate themselves. | | |
| 173 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 174 | | config.appUserPassword | Password used by cps-core service to configure the authentication for REST API it exposes. | Not defined | |
| 175 | | | | | |
| 176 | | | This is the password to be used by CPS Temporal REST clients to authenticate themselves. | | |
| 177 | | | | | |
| 178 | | | If not defined, the password is generated when deploying the application. | | |
| 179 | | | | | |
| lukegleeson | f027cfb | 2021-11-08 15:53:12 +0000 | [diff] [blame] | 180 | | | See also :ref:`cps_common_credentials_retrieval`. | | |
| puthuparambil.aditya | 841e3df | 2021-10-05 10:56:04 +0100 | [diff] [blame] | 181 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 182 | | config.dmiPluginUserName | User name used by cps-core to authenticate themselves for using ncmp-dmi-plugin service. | ``dmiuser`` | |
| 183 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 184 | | config.dmiPluginUserPassword | Internal password used by cps-core to connect to ncmp-dmi-plugin service. | Not defined | |
| 185 | | | | | |
| 186 | | | If not defined, the password is generated when deploying the application. | | |
| 187 | | | | | |
| lukegleeson | f027cfb | 2021-11-08 15:53:12 +0000 | [diff] [blame] | 188 | | | See also :ref:`cps_common_credentials_retrieval`. | | |
| puthuparambil.aditya | 841e3df | 2021-10-05 10:56:04 +0100 | [diff] [blame] | 189 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 190 | | postgres.config.pgUserName | Internal user name used by cps-core to connect to its own database. | ``cps`` | |
| 191 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 192 | | postgres.config.pgUserPassword | Internal password used by cps-core to connect to its own database. | Not defined | |
| 193 | | | | | |
| 194 | | | If not defined, the password is generated when deploying the application. | | |
| 195 | | | | | |
| lukegleeson | f027cfb | 2021-11-08 15:53:12 +0000 | [diff] [blame] | 196 | | | See also :ref:`cps_common_credentials_retrieval`. | | |
| puthuparambil.aditya | 841e3df | 2021-10-05 10:56:04 +0100 | [diff] [blame] | 197 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 198 | | postgres.config.pgDatabase | Database name used by cps-core | ``cpsdb`` | |
| 199 | | | | | |
| 200 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 201 | | logging.level | Logging level set in cps-core | info | |
| 202 | | | | | |
| 203 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 204 | | config.eventPublisher. | Kafka hostname and port | ``message-router-kafka:9092`` | |
| 205 | | spring.kafka.bootstrap-servers | | | |
| 206 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 207 | | config.eventPublisher. | Kafka consumer client id | ``cps-core`` | |
| 208 | | spring.kafka.consumer.client-id | | | |
| 209 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 210 | | config.publisher. | Kafka security protocol. | ``PLAINTEXT`` | |
| 211 | | spring.kafka.security.protocol | Some possible values are: | | |
| 212 | | | | | |
| 213 | | | * ``PLAINTEXT`` | | |
| 214 | | | * ``SASL_PLAINTEXT``, for authentication | | |
| 215 | | | * ``SASL_SSL``, for authentication and encryption | | |
| 216 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 217 | | config.publisher. | Kafka security SASL mechanism. Required for SASL_PLAINTEXT and SASL_SSL protocols. | Not defined | |
| 218 | | spring.kafka.properties. | Some possible values are: | | |
| 219 | | sasl.mechanism | | | |
| 220 | | | * ``PLAIN``, for PLAINTEXT | | |
| 221 | | | * ``SCRAM-SHA-512``, for SSL | | |
| 222 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 223 | | config.publisher. | Kafka security SASL JAAS configuration. Required for SASL_PLAINTEXT and SASL_SSL protocols. | Not defined | |
| 224 | | spring.kafka.properties. | Some possible values are: | | |
| 225 | | sasl.jaas.config | | | |
| 226 | | | * ``org.apache.kafka.common.security.plain.PlainLoginModule required username="..." password="...";``, | | |
| 227 | | | for PLAINTEXT | | |
| 228 | | | * ``org.apache.kafka.common.security.scram.ScramLoginModule required username="..." password="...";``, | | |
| 229 | | | for SSL | | |
| 230 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 231 | | config.publisher. | Kafka security SASL SSL store type. Required for SASL_SSL protocol. | Not defined | |
| 232 | | spring.kafka.ssl.trust-store-type | Some possible values are: | | |
| 233 | | | | | |
| 234 | | | * ``JKS`` | | |
| 235 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 236 | | config.publisher. | Kafka security SASL SSL store file location. Required for SASL_SSL protocol. | Not defined | |
| 237 | | spring.kafka.ssl.trust-store-location | | | |
| 238 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 239 | | config.publisher. | Kafka security SASL SSL store password. Required for SASL_SSL protocol. | Not defined | |
| 240 | | spring.kafka.ssl.trust-store-password | | | |
| 241 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 242 | | config.publisher. | Kafka security SASL SSL broker hostname identification verification. Required for SASL_SSL protocol. | Not defined | |
| 243 | | spring.kafka.properties. | Possible value is: | | |
| 244 | | ssl.endpoint.identification.algorithm | | | |
| 245 | | | * ``""``, empty string to disable | | |
| 246 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 247 | | config.additional. | Kafka topic to publish to cps-temporal | ``cps.data-updated-events`` | |
| 248 | | notification.data-updated.topic | | | |
| 249 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 250 | | config.additional. | If notification from cps-core to cps-temporal is enabled or not. | ``true`` | |
| 251 | | notification.data-updated.enabled | If this is set to false, then the config.publisher properties could be skipped. | | |
| 252 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 253 | | config.additional. | Dataspaces to be enabled for publishing events to cps-temporal | ```` | |
| 254 | | notification.data-updated.filters. | | | |
| 255 | | enabled-dataspaces | | | |
| 256 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 257 | | config.additional. | If notifications should be processed in synchronous or asynchronous manner | ``false`` | |
| 258 | | notification.async.enabled | | | |
| 259 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 260 | | config.additional. | Core pool size in asynchronous execution of notification. | ``2`` | |
| 261 | | notification.async.executor. | | | |
| 262 | | core-pool-size | | | |
| 263 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 264 | | config.additional. | Max pool size in asynchronous execution of notification. | ``1`` | |
| 265 | | notification.async.executor. | | | |
| 266 | | max-pool-size | | | |
| 267 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 268 | | config.additional. | Queue Capacity in asynchronous execution of notification. | ``500`` | |
| 269 | | notification.async.executor. | | | |
| 270 | | queue-capacity | | | |
| 271 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 272 | | config.additional. | If the executor should wait for the tasks to be completed on shutdown | ``true`` | |
| 273 | | notification.async.executor. | | | |
| 274 | | wait-for-tasks-to-complete-on-shutdown| | | |
| 275 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 276 | | config.additional. | Prefix to be added to the thread name in asynchronous execution of notifications. | ``async_`` | |
| 277 | | notification.async.executor. | | | |
| 278 | | thread-name-prefix | | | |
| 279 | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ |
| 280 | |
| 281 | CPS-Core Docker Installation |
| 282 | ============================ |
| 283 | |
| 284 | CPS-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. |
| 285 | The latest instructions are covered in the `README <https://github.com/onap/cps/blob/master/docker-compose/README.md>`_. |