docs/deployment.rst

   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-2022 Nordix Foundation
   4 .. Modifications Copyright (C) 2021 Bell Canada.
   5
   6 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
   7 .. _deployment:
   8
   9 CPS Deployment
  10 ##############
  11
  12 .. contents::
  13     :depth: 2
  14
  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   - `ncmp-dmi-plugin <https://github.com/onap/oom/tree/master/kubernetes/cps/components/ncmp-dmi-plugin>`__
  24
  25 Please 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.
  26
  27 Installing or Upgrading CPS Components
  28 ======================================
  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
 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:
 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>`_
 113   - `ncmp-dmi-plugin <https://github.com/onap/oom/blob/master/kubernetes/cps/components/ncmp-dmi-plugin/values.yaml>`_
 114
 115 Below 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 | 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
 129 The credential values from these secrets are configured in running container as environment variables. Eg:
 130 `cps core deployment.yaml <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/templates/deployment.yaml>`_
 131
 132 If no specific passwords are provided to the chart as override values for deployment, then passwords are automatically
 133 generated 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
 142 CPS Core Pods
 143 =============
 144 To 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
 154 .. note::
 155     The CPS Service will have to be restarted each time a change is made to a configurable property.
 156
 157 Additional CPS-Core Customizations
 158 ==================================
 159
 160 The following table lists some properties that can be specified as Helm chart
 161 values to configure the application to be deployed. This list is not exhaustive.
 162
 163 Any spring supported property can be configured by providing in ``config.additional.<spring-supported-property-name>: value`` Example: config.additional.spring.datasource.hikari.maximumPoolSize: 30
 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 |                                           |                                                                                                         |                               |
 174 |                                           | If not defined, the password is generated when deploying the application.                               |                               |
 175 |                                           |                                                                                                         |                               |
 176 |                                           | See also :ref:`cps_common_credentials_retrieval`.                                                       |                               |
 177 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 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 |                                           |                                                                                                         |                               |
 184 |                                           | See also :ref:`cps_common_credentials_retrieval`.                                                       |                               |
 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 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 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.                                            |                               |
 194 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 195 | config.eventPublisher.                    | Kafka hostname and port                                                                                 | ``<kafka-bootstrap>:9092``    |
 196 | spring.kafka.bootstrap-servers            |                                                                                                         |                               |
 197 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 198 | config.eventPublisher.                    | Kafka consumer client id                                                                                | ``cps-core``                  |
 199 | spring.kafka.consumer.client-id           |                                                                                                         |                               |
 200 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 201 | config.eventPublisher.                    | Kafka security protocol.                                                                                | ``SASL_PLAINTEXT``            |
 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 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 208 | config.eventPublisher.                    | Kafka security SASL mechanism. Required for SASL_PLAINTEXT and SASL_SSL protocols.                      | Not defined                   |
 209 | spring.kafka.properties.                  | Some possible values are:                                                                               |                               |
 210 | sasl.mechanism                            |                                                                                                         |                               |
 211 |                                           | * ``PLAIN``, for PLAINTEXT                                                                              |                               |
 212 |                                           | * ``SCRAM-SHA-512``, for SSL                                                                            |                               |
 213 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 214 | config.eventPublisher.                    | Kafka security SASL JAAS configuration. Required for SASL_PLAINTEXT and SASL_SSL protocols.             | Not defined                   |
 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 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 222 | config.eventPublisher.                    | Kafka security SASL SSL store type. Required for SASL_SSL protocol.                                     | Not defined                   |
 223 | spring.kafka.ssl.trust-store-type         | Some possible values are:                                                                               |                               |
 224 |                                           |                                                                                                         |                               |
 225 |                                           | * ``JKS``                                                                                               |                               |
 226 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 227 | config.eventPublisher.                    | Kafka security SASL SSL store file location. Required for SASL_SSL protocol.                            | Not defined                   |
 228 | spring.kafka.ssl.trust-store-location     |                                                                                                         |                               |
 229 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 230 | config.eventPublisher.                    | Kafka security SASL SSL store password. Required for SASL_SSL protocol.                                 | Not defined                   |
 231 | spring.kafka.ssl.trust-store-password     |                                                                                                         |                               |
 232 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 233 | config.eventPublisher.                    | Kafka security SASL SSL broker hostname identification verification. Required for SASL_SSL protocol.    | Not defined                   |
 234 | spring.kafka.properties.                  | Possible value is:                                                                                      |                               |
 235 | ssl.endpoint.identification.algorithm     |                                                                                                         |                               |
 236 |                                           | * ``""``, empty string to disable                                                                       |                               |
 237 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 238 | config.additional.                        | Core pool size in asynchronous execution of notification.                                               | ``2``                         |
 239 | notification.async.executor.              |                                                                                                         |                               |
 240 | core-pool-size                            |                                                                                                         |                               |
 241 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 242 | config.additional.                        | Max pool size in asynchronous execution of notification.                                                | ``1``                         |
 243 | notification.async.executor.              |                                                                                                         |                               |
 244 | max-pool-size                             |                                                                                                         |                               |
 245 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 246 | config.additional.                        | Queue Capacity in asynchronous execution of notification.                                               | ``500``                       |
 247 | notification.async.executor.              |                                                                                                         |                               |
 248 | queue-capacity                            |                                                                                                         |                               |
 249 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 250 | config.additional.                        | If the executor should wait for the tasks to be completed on shutdown                                   | ``true``                      |
 251 | notification.async.executor.              |                                                                                                         |                               |
 252 | wait-for-tasks-to-complete-on-shutdown    |                                                                                                         |                               |
 253 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 254 | config.additional.                        | Prefix to be added to the thread name in asynchronous execution of notifications.                       | ``Async-``                    |
 255 | notification.async.executor.              |                                                                                                         |                               |
 256 | thread-name-prefix                        |                                                                                                         |                               |
 257 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 258 | config.additional.                        | Specifies number of database connections between database and application.                              | ``10``                        |
 259 | spring.datasource.hikari.                 | This property controls the maximum size that the pool is allowed to reach,                              |                               |
 260 | maximumPoolSize                           | including both idle and in-use connections.                                                             |                               |
 261 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 262
 263 .. _additional-cps-ncmp-customizations:
 264
 265 Additional CPS-NCMP Customizations
 266 ==================================
 267 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 268 | config.dmiPluginUserName                  | User name used by cps-core to authenticate themselves for using ncmp-dmi-plugin service.                | ``dmiuser``                   |
 269 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 270 | config.dmiPluginUserPassword              | Internal password used by cps-core to connect to ncmp-dmi-plugin service.                               | Not defined                   |
 271 |                                           |                                                                                                         |                               |
 272 |                                           | If not defined, the password is generated when deploying the application.                               |                               |
 273 |                                           |                                                                                                         |                               |
 274 |                                           | See also :ref:`cps_common_credentials_retrieval`.                                                       |                               |
 275 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 276 | config.ncmp.timers                        | Specifies the delay in milliseconds in which the module sync watch dog will wake again after finishing. | ``30000``                     |
 277 | .advised-modules-sync.sleep-time-ms       |                                                                                                         |                               |
 278 |                                           |                                                                                                         |                               |
 279 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 280 | config.ncmp.timers                        | Specifies the delay in milliseconds in which the retry mechanism watch dog                              |                               |
 281 | .locked-modules-sync.sleep-time-ms        | will wake again after finishing.                                                                        | ``300000``                    |
 282 |                                           |                                                                                                         |                               |
 283 |                                           |                                                                                                         |                               |
 284 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 285 | config.ncmp.timers                        | Specifies the delay in milliseconds in which the data sync watch dog will wake again after finishing.   | ``30000``                     |
 286 | .cm-handle-data-sync.sleep-time-ms        |                                                                                                         |                               |
 287 |                                           |                                                                                                         |                               |
 288 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 289 | config.additional.ncmp.dmi.httpclient     | Specifies the maximum time in seconds, to wait for establishing a connection for the HTTP Client.       | ``180``                       |
 290 | .connectionTimeoutInSeconds               |                                                                                                         |                               |
 291 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 292 | config.additional.ncmp.dmi.httpclient     | Specifies the maximum number of connections allowed per route in the HTTP client.                       | ``50``                        |
 293 | .maximumConnectionsPerRoute               |                                                                                                         |                               |
 294 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 295 | config.additional.ncmp.dmi.httpclient     | Specifies the maximum total number of connections that can be held by the HTTP client.                  | ``100``                       |
 296 | .maximumConnectionsTotal                  |                                                                                                         |                               |
 297 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 298 | config.additional.ncmp.dmi.httpclient     | Specifies the duration in seconds for the threshold, after which idle connections will be evicted       | ``5``                         |
 299 | .idleConnectionEvictionThresholdInSeconds | from the connection pool by the HTTP client.                                                            |                               |
 300 +-------------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 301
 302 CPS-Core Docker Installation
 303 ============================
 304
 305 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.
 306 The latest instructions are covered in the `README <https://github.com/onap/cps/blob/master/docker-compose/README.md>`_.
 307
 308 .. Below Label is used by documentation for other CPS components to link here, do not remove even if it gives a warning
 309 .. _cps_common_distributed_datastructures:
 310
 311 CPS-Core and NCMP Distributed Datastructures
 312 ============================================
 313
 314 CPS-Core and NCMP both internally uses embedded distributed datastructure to replicate the state across various instances for low latency.
 315 These 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.
 316
 317 Below are the list of distributed datastructures that we have.
 318
 319 +--------------+---------------------------------+----------------------------------------------------------+
 320 | Component    | Datastructure name              |                 Use                                      |
 321 +==============+=================================+==========================================================+
 322 | cps-core     | anchorDataCache                 | Used to resolve prefix for the container name.           |
 323 +--------------+---------------------------------+----------------------------------------------------------+
 324 | cps-ncmp     | moduleSyncStartedOnCmHandles    | Watchdog process to register cmHandles.                  |
 325 +--------------+---------------------------------+----------------------------------------------------------+
 326 | cps-ncmp     | dataSyncSemaphores              | Watchdog process to sync data from the nodes.            |
 327 +--------------+---------------------------------+----------------------------------------------------------+
 328 | cps-ncmp     | moduleSyncWorkQueue             | Queue used internally for workers to pick the task.      |
 329 +--------------+---------------------------------+----------------------------------------------------------+
 330 | cps-ncmp     | forwardedSubscriptionEventCache | Keeps track of the LCM Subscription Events.              |
 331 +--------------+---------------------------------+----------------------------------------------------------+
 332 | cps-ncmp     | untrustworthyCmHandlesSet       | Stores untrustworthy cmHandles whose TrustLevel is NONE. |
 333 +--------------+---------------------------------+----------------------------------------------------------+
 334 | cps-ncmp     | trustLevelPerDmiPlugin          | Stores the TrustLevel for the dmi-plugins.               |
 335 +--------------+---------------------------------+----------------------------------------------------------+
 336 | cps-ncmp     | moduleSetTagCacheMapConfig      | Stores the Module Set Tags for cmHandles.                |
 337 +--------------+---------------------------------+----------------------------------------------------------+
 338 | cps-ncmp     | cmSubscriptionEventCache        | Stores and tracks CmSubscription requests.               |
 339 +--------------+---------------------------------+----------------------------------------------------------+
 340
 341 Total number of caches : 9