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 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   - `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
  31 The 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
  51 After 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
  60 First, 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
  70 If 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
  79 Connect 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
  87 After 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
  94 Restarting a faulty component
  95 =============================
  96 Each 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
 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:
 104
 105 Credentials Retrieval
 106 =====================
 107
 108 Application and database credentials are kept in Kubernetes secrets. They are defined as external secrets in the
 109 values.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
 117 Below 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
 135 The 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
 138 If no specific passwords are provided to the chart as override values for deployment, then passwords are automatically
 139 generated 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
 148 CPS Core Pods
 149 =============
 150 To 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
 160
 161 Additional Cps-Core Customizations
 162 ==================================
 163
 164 The following table lists some properties that can be specified as Helm chart
 165 values to configure the application to be deployed. This list is not
 166 exhaustive.
 167
 168 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 169 | Property                              | Description                                                                                             | Default Value                 |
 170 +=======================================+=========================================================================================================+===============================+
 171 | config.appUserName                    | User name used by cps-core service to configure the authentication for REST API it exposes.             | ``cpsuser``                   |
 172 |                                       |                                                                                                         |                               |
 173 |                                       | This is the user name to be used by cps-core REST clients to authenticate themselves.                   |                               |
 174 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 175 | config.appUserPassword                | Password used by cps-core service to configure the authentication for REST API it exposes.              | Not defined                   |
 176 |                                       |                                                                                                         |                               |
 177 |                                       | This is the password to be used by CPS Temporal REST clients to authenticate themselves.                |                               |
 178 |                                       |                                                                                                         |                               |
 179 |                                       | If not defined, the password is generated when deploying the application.                               |                               |
 180 |                                       |                                                                                                         |                               |
 181 |                                       | See also :ref:`cps_common_credentials_retrieval`.                                                       |                               |
 182 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 183 | config.dmiPluginUserName              | User name used by cps-core to authenticate themselves for using ncmp-dmi-plugin service.                | ``dmiuser``                   |
 184 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 185 | config.dmiPluginUserPassword          | Internal password used by cps-core to connect to ncmp-dmi-plugin service.                               | Not defined                   |
 186 |                                       |                                                                                                         |                               |
 187 |                                       | If not defined, the password is generated when deploying the application.                               |                               |
 188 |                                       |                                                                                                         |                               |
 189 |                                       | See also :ref:`cps_common_credentials_retrieval`.                                                       |                               |
 190 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 191 | postgres.config.pgUserName            | Internal user name used by cps-core to connect to its own database.                                     | ``cps``                       |
 192 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 193 | postgres.config.pgUserPassword        | Internal password used by cps-core to connect to its own database.                                      | Not defined                   |
 194 |                                       |                                                                                                         |                               |
 195 |                                       | If not defined, the password is generated when deploying the application.                               |                               |
 196 |                                       |                                                                                                         |                               |
 197 |                                       | See also :ref:`cps_common_credentials_retrieval`.                                                       |                               |
 198 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 199 | postgres.config.pgDatabase            | Database name used by cps-core                                                                          | ``cpsdb``                     |
 200 |                                       |                                                                                                         |                               |
 201 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 202 | logging.level                         | Logging level set in cps-core                                                                           | info                          |
 203 |                                       |                                                                                                         |                               |
 204 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 205 | config.eventPublisher.                | Kafka hostname and port                                                                                 | ``message-router-kafka:9092`` |
 206 | spring.kafka.bootstrap-servers        |                                                                                                         |                               |
 207 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 208 | config.eventPublisher.                | Kafka consumer client id                                                                                | ``cps-core``                  |
 209 | spring.kafka.consumer.client-id       |                                                                                                         |                               |
 210 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 211 | config.publisher.                     | Kafka security protocol.                                                                                | ``PLAINTEXT``                 |
 212 | spring.kafka.security.protocol        | Some possible values are:                                                                               |                               |
 213 |                                       |                                                                                                         |                               |
 214 |                                       | * ``PLAINTEXT``                                                                                         |                               |
 215 |                                       | * ``SASL_PLAINTEXT``, for authentication                                                                |                               |
 216 |                                       | * ``SASL_SSL``, for authentication and encryption                                                       |                               |
 217 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 218 | config.publisher.                     | Kafka security SASL mechanism. Required for SASL_PLAINTEXT and SASL_SSL protocols.                      | Not defined                   |
 219 | spring.kafka.properties.              | Some possible values are:                                                                               |                               |
 220 | sasl.mechanism                        |                                                                                                         |                               |
 221 |                                       | * ``PLAIN``, for PLAINTEXT                                                                              |                               |
 222 |                                       | * ``SCRAM-SHA-512``, for SSL                                                                            |                               |
 223 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 224 | config.publisher.                     | Kafka security SASL JAAS configuration. Required for SASL_PLAINTEXT and SASL_SSL protocols.             | Not defined                   |
 225 | spring.kafka.properties.              | Some possible values are:                                                                               |                               |
 226 | sasl.jaas.config                      |                                                                                                         |                               |
 227 |                                       | * ``org.apache.kafka.common.security.plain.PlainLoginModule required username="..." password="...";``,  |                               |
 228 |                                       |   for PLAINTEXT                                                                                         |                               |
 229 |                                       | * ``org.apache.kafka.common.security.scram.ScramLoginModule required username="..." password="...";``,  |                               |
 230 |                                       |   for SSL                                                                                               |                               |
 231 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 232 | config.publisher.                     | Kafka security SASL SSL store type. Required for SASL_SSL protocol.                                     | Not defined                   |
 233 | spring.kafka.ssl.trust-store-type     | Some possible values are:                                                                               |                               |
 234 |                                       |                                                                                                         |                               |
 235 |                                       | * ``JKS``                                                                                               |                               |
 236 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 237 | config.publisher.                     | Kafka security SASL SSL store file location. Required for SASL_SSL protocol.                            | Not defined                   |
 238 | spring.kafka.ssl.trust-store-location |                                                                                                         |                               |
 239 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 240 | config.publisher.                     | Kafka security SASL SSL store password. Required for SASL_SSL protocol.                                 | Not defined                   |
 241 | spring.kafka.ssl.trust-store-password |                                                                                                         |                               |
 242 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 243 | config.publisher.                     | Kafka security SASL SSL broker hostname identification verification. Required for SASL_SSL protocol.    | Not defined                   |
 244 | spring.kafka.properties.              | Possible value is:                                                                                      |                               |
 245 | ssl.endpoint.identification.algorithm |                                                                                                         |                               |
 246 |                                       | * ``""``, empty string to disable                                                                       |                               |
 247 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 248 | config.additional.                    | Kafka topic to publish to cps-temporal                                                                  | ``cps.data-updated-events``   |
 249 | notification.data-updated.topic       |                                                                                                         |                               |
 250 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 251 | config.additional.                    | If notification from cps-core to cps-temporal is enabled or not.                                        | ``true``                      |
 252 | notification.data-updated.enabled     | If this is set to false, then the config.publisher properties could be skipped.                         |                               |
 253 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 254 | config.additional.                    | Dataspaces to be enabled for publishing events to cps-temporal                                          | ````                          |
 255 | notification.data-updated.filters.    |                                                                                                         |                               |
 256 | enabled-dataspaces                    |                                                                                                         |                               |
 257 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 258 | config.additional.                    | If notifications should be processed in synchronous or asynchronous manner                              | ``false``                     |
 259 | notification.async.enabled            |                                                                                                         |                               |
 260 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 261 | config.additional.                    | Core pool size in asynchronous execution of notification.                                               | ``2``                         |
 262 | notification.async.executor.          |                                                                                                         |                               |
 263 | core-pool-size                        |                                                                                                         |                               |
 264 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 265 | config.additional.                    | Max pool size in asynchronous execution of notification.                                                | ``1``                         |
 266 | notification.async.executor.          |                                                                                                         |                               |
 267 | max-pool-size                         |                                                                                                         |                               |
 268 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 269 | config.additional.                    | Queue Capacity in asynchronous execution of notification.                                               | ``500``                       |
 270 | notification.async.executor.          |                                                                                                         |                               |
 271 | queue-capacity                        |                                                                                                         |                               |
 272 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 273 | config.additional.                    | If the executor should wait for the tasks to be completed on shutdown                                   | ``true``                      |
 274 | notification.async.executor.          |                                                                                                         |                               |
 275 | wait-for-tasks-to-complete-on-shutdown|                                                                                                         |                               |
 276 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 277 | config.additional.                    | Prefix to be added to the thread name in asynchronous execution of notifications.                       | ``async_``                    |
 278 | notification.async.executor.          |                                                                                                         |                               |
 279 | thread-name-prefix                    |                                                                                                         |                               |
 280 +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+
 281
 282 CPS-Core Docker Installation
 283 ============================
 284
 285 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.
 286 The latest instructions are covered in the `README <https://github.com/onap/cps/blob/master/docker-compose/README.md>`_.