docs/sections/installation_oom.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 DCAE Deployment (using Helm and Cloudify)
   5 =========================================
   6
   7 This document describes the details of the Helm chart based deployment process for ONAP and how DCAE is deployed through this process.
   8
   9
  10 Deployment Overview
  11 -------------------
  12
  13 ONAP deployments are done on kubernetes through OOM/Helm charts. Kubernetes is a container orchestration technology that organizes containers into composites of various patterns for easy deployment, management, and scaling.
  14 ONAP uses Kubernetes as the foundation for fulfilling its platform maturity promises.
  15
  16 ONAP manages Kubernetes specifications using Helm charts (in OOM project), under which all Kubernetes yaml-formatted resource specifications and additional files
  17 are organized into a hierarchy of charts, sub-charts, and resources.  These yaml files are further augmented with Helm's templating, which makes dependencies
  18 and cross-references of parameters and parameter derivatives among resources manageable for a large and complex Kubernetes system such as ONAP.
  19
  20 At deployment time, with a single **helm deploy** command, Helm resolves all the templates and compiles the chart hierarchy into Kubernetes resource definitions,
  21 and invokes Kubernetes deployment operations for all the resources.
  22
  23 All ONAP Helm charts are organized under the **kubernetes** directory of the **OOM** project, where roughly each ONAP component occupies a subdirectory.
  24 DCAE charts are placed under the **dcaegen2** directory.
  25
  26 All DCAE platform components  have corresponding Helm chart which will be used to trigger the deployment.
  27 All DCAE Services are deployed through Cloudify Blueprint. The default ONAP DCAE deployment includes small subset of DCAE services deployed through Bootstrap pod to meet
  28 ONAP Integration usecases. Optionally operators can deploy on-demand other MS required for their usecases as described in :doc:`On-demand MS Installation
  29 <./installation_MS_ondemand>`.
  30
  31
  32 The PNDA data platform is an optional DCAE component that is placed under the **pnda**
  33 directory. Details for how to configure values to enable PNDA installation during Helm install
  34 are described in :doc:`Installing PNDA through Helm Chart
  35 <./installation_pnda>`.
  36
  37
  38 DCAE Chart Organization
  39 -----------------------
  40
  41 Following Helm conventions, the DCAE Helm chart directory (``oom/kubernetes/dcaegen2``) consists of the following files and subdirectories:
  42
  43 * ``Chart.yaml``: metadata.
  44 * ``requirements.yaml``: dependency charts.
  45 * ``values.yaml``: values for Helm templating engine to expand templates.
  46 * ``resources``: subdirectory for additional resource definitions such as configuration, scripts, etc.
  47 * ``Makefile``: make file to build DCAE charts
  48 * ``components``: subdirectory for DCAE sub-charts.
  49
  50 The dcaegen2 chart has the following sub-charts:
  51
  52 * ``dcae-bootstrap``: deploys the DCAE bootstrap service that performs some DCAE initialization and deploys additional DCAE components.
  53 * ``dcae-cloudify-manager``: deploys the DCAE Cloudify Manager instance.
  54 * ``dcae-config-binding-service``: deploys the DCAE config binding service.
  55 * ``dcae-deployment-handler``: deploys the DCAE deployment handler service.
  56 * ``dcae-healthcheck``: deploys the DCAE healthcheck service that provides an API to check the health of all DCAE components.
  57 * ``dcae-policy-handler``: deploys the DCAE policy handler service.
  58 * ``dcae-redis``: deploys the DCAE Redis cluster.
  59 * ``dcae-dashboard``: deploys the DCAE Dashboard for managing DCAE microservices deployments
  60 * ``dcae-servicechange-handler``: deploys the DCAE service change handler service.  A subchart (``dcae-inventory-api``) deploys the DCAE inventory API service.
  61
  62 DCAE Deployment
  63 ---------------
  64
  65 At deployment time, when the **helm deploy** command is executed,
  66 all DCAE resources defined within the subcharts above are deployed.
  67 These include:
  68
  69 * the DCAE bootstrap service
  70 * the DCAE healthcheck service
  71 * the DCAE platform components:
  72
  73   * Cloudify Manager
  74   * Config binding service
  75   * Deployment handler
  76   * Policy handler
  77   * Service change handler
  78   * Inventory API service (launched as a subchart of service change handler)
  79   * Inventory postgres database service (launched as a dependency of the inventory API service)
  80   * DCAE postgres database service (launched as a dependency of the bootstrap service)
  81   * DCAE Redis cluster
  82
  83 Some of the DCAE subcharts include an initContainer that checks to see if
  84 other services that they need in order to run have become ready.  The installation
  85 of these subcharts will pause until the needed services are available.
  86
  87 In addition, DCAE operations depends on a Consul server cluster.
  88 For ONAP OOM deployment, the Consul cluster is provided as a shared
  89 resource. Its charts are defined under the ``oom/kubernetes/consul``
  90 directory, not as part of the DCAE chart hierarchy.
  91
  92 The dcae-bootstrap service has a number of prerequisites because the subsequently deployed DCAE components depends on a number of resources having entered their normal operation state.  DCAE bootstrap job will not start before these resources are ready.  They are:
  93
  94
  95   * dcae-cloudify-manager
  96   * consul-server
  97   * msb-discovery
  98   * kube2msb
  99   * dcae-config-binding-service
 100   * dcae-db
 101   * dcae-mongodb
 102   * dcae-inventory-api
 103
 104 Additionaly tls-init-container invoked during component deployment relies on AAF to generate the required certificate hence AAF
 105 must be enabled under OOM deployment configuration.
 106
 107 Once started, the DCAE bootstrap service will call Cloudify Manager to deploy
 108 a series of blueprints which specify the additional DCAE microservice components.
 109 These blueprints use the DCAE Kubernetes plugin (``k8splugin``) to deploy
 110 Docker images into the ONAP Kubernetes cluster.  For each component, the plugin
 111 creates a Kubernetes deployment and other Kubernetes resources (services, volumes, logging sidecar, etc.)
 112 as needed.
 113
 114 The DCAE bootstrap service creates the following Kubernetes deployments:
 115
 116 * deploy/dep-dcae-hv-ves-collector
 117 * deploy/dep-dcae-prh
 118 * deploy/dep-dcae-tca-analytics
 119 * deploy/dep-dcae-tcagen2
 120 * deploy/dep-dcae-ves-collector
 121 * deploy/dep-holmes-engine-mgmt
 122 * deploy/dep-holmes-rule-mgmt
 123
 124 After deploying all of the blueprints, the DCAE bootstrap service
 125 continues to run.   The bootstrap container can be useful for
 126 troubleshooting or for launching additional components.  The bootstrap
 127 container logs (accessed using the ``kubectl logs`` command) show the
 128 details of all of the component deployments.
 129
 130 DCAE Configuration
 131 ------------------
 132
 133 Deployment time configuration of DCAE components are defined in several places.
 134
 135   * Helm Chart templates:
 136      * Helm/Kubernetes template files can contain static values for configuration parameters;
 137   * Helm Chart resources:
 138      * Helm/Kubernetes resources files can contain static values for configuration parameters;
 139   * Helm values.yaml files:
 140      * The values.yaml files supply the values that Helm templating engine uses to expand any templates defined in Helm templates;
 141      * In a Helm chart hierarchy, values defined in values.yaml files in higher level supersedes values defined in values.yaml files in lower level;
 142      * Helm command line supplied values supersedes values defined in any values.yaml files.
 143
 144 In addition, for DCAE components deployed through Cloudify Manager blueprints, their configuration parameters are defined in the following places:
 145
 146      * The blueprint files can contain static values for configuration parameters;
 147         * The blueprint files are defined under the ``blueprints`` directory of the ``dcaegen2/platform/blueprints`` repo, named with "k8s" prefix.
 148      * The blueprint files can specify input parameters and the values of these parameters will be used for configuring parameters in Blueprints.  The values for these input parameters can be supplied in several ways as listed below in the order of precedence (low to high):
 149         * The blueprint files can define default values for the input parameters;
 150         * The blueprint input files can contain static values for input parameters of blueprints.  These input files are provided as config resources under the dcae-bootstrap chart;
 151         * The blueprint input files may contain Helm templates, which are resolved into actual deployment time values following the rules for Helm values.
 152
 153
 154 Now we walk through an example, how to configure the Docker image for the DCAE VESCollector, which is deployed by Cloudify Manager.
 155
 156 In the  `k8s-ves.yaml <https://git.onap.org/dcaegen2/platform/blueprints/tree/blueprints/k8s-ves.yaml>`_ blueprint, the Docker image to use is defined as an input parameter with a default value:
 157
 158 .. code-block:: yaml
 159
 160     tag_version:
 161     type: string
 162     default: "nexus3.onap.org:10001/onap/org.onap.dcaegen2.collectors.ves.vescollector:1.5.4"
 163
 164 The corresponding input file, ``https://git.onap.org/oom/tree/kubernetes/dcaegen2/components/dcae-bootstrap/resources/inputs/k8s-ves-inputs-tls.yaml``,
 165 it is defined again as:
 166
 167 .. code-block:: yaml
 168   {{ if .Values.componentImages.ves }}
 169   tag_version: {{ include "common.repository" . }}/{{ .Values.componentImages.ves }}
 170   {{ end }}
 171
 172
 173 Thus, when ``common.repository`` and ``componentImages.ves`` are defined in the ``values.yaml`` files,
 174 their values will be plugged in here and the resulting ``tag_version`` value
 175 will be passed to the blueprint as the Docker image tag to use instead of the default value in the blueprint.
 176
 177 The ``componentImages.ves`` value is provided in the ``oom/kubernetes/dcaegen2/charts/dcae-bootstrap/values.yaml`` file:
 178
 179 .. code-block:: yaml
 180
 181   componentImages:
 182     ves: onap/org.onap.dcaegen2.collectors.ves.vescollector:1.5.4
 183
 184
 185 The final result is that when DCAE bootstrap calls Cloudify Manager to deploy the DCAE VES collector, the 1.5.4 image will be deployed.
 186
 187 DCAE Service Endpoints
 188 ----------------------
 189
 190 Below is a table of default hostnames and ports for DCAE component service endpoints in Kubernetes deployment:
 191     ==================   =================================   ======================================================
 192     Component            Cluster Internal (host:port)        Cluster external (svc_name:port)
 193     ==================   =================================   ======================================================
 194     VES                  dcae-ves-collector:8443             xdcae-ves-collector.onap:30417
 195     HV-VES               dcae-hv-ves-collector:6061          xdcae-hv-ves-collector.onap:30222
 196     TCA                  dcae-tca-analytics:11011            xdcae-tca-analytics.onap:32010
 197     TCA-Gen2             dcae-tcagen2:9091                   NA
 198     PRH                  dcae-prh:8100                       NA
 199     Policy Handler       policy-handler:25577                NA
 200     Deployment Handler   deployment-handler:8443             NA
 201     Inventory            inventory:8080                      NA
 202     Config binding       config-binding-service:10000/10001  config-binding-service:30415
 203     DCAE Healthcheck     dcae-healthcheck:80                 NA
 204     Cloudify Manager     dcae-cloudify-manager:80            NA
 205     DCAE Dashboard       dcae-dashboard:8443                 xdcae-dashboard:30419
 206     ==================   =================================   ======================================================
 207
 208 In addition, a number of ONAP service endpoints that are used by DCAE components are listed as follows
 209 for reference by DCAE developers and testers:
 210
 211     ====================   ============================      ================================
 212     Component              Cluster Internal (host:port)      Cluster external (svc_name:port)
 213     ====================   ============================      ================================
 214     Consul Server          consul-server:8500                consul-server:30270
 215     Robot                  robot:88                          robot:30209 TCP
 216     Message router         message-router:3904               message-router:30227
 217     Message router         message-router:3905               message-router:30226
 218     Message router Kafka   message-router-kafka:9092         NA
 219     MSB Discovery          msb-discovery:10081               msb-discovery:30281
 220     Logging                log-kibana:5601                   log-kibana:30253
 221     AAI                    aai:8080                          aai:30232
 222     AAI                    aai:8443                          aai:30233
 223     ====================   ============================      ================================
 224
 225 Uninstalling DCAE
 226 -----------------
 227
 228 All of the DCAE components deployed using the OOM Helm charts will be
 229 deleted by the ``helm undeploy`` command.  This command can be used to
 230 uninstall all of ONAP by undeploying the top-level Helm release that was
 231 created by the ``helm deploy`` command.  The command can also be used to
 232 uninstall just DCAE, by having the command undeploy the `top_level_release_name`-``dcaegen2``
 233 Helm sub-release.
 234
 235 Helm will undeploy only the components that were originally deployed using
 236 Helm charts.  Components deployed by Cloudify Manager are not deleted by
 237 the Helm operations.
 238
 239 When uninstalling all of ONAP, it is sufficient to delete the namespace
 240 used for the deployment (typically ``onap``) after running the undeploy
 241 operation.  Deleting the namespace will get rid of any remaining resources
 242 in the namespace, including the components deployed by Cloudify Manager.
 243
 244 When uninstalling DCAE alone, deleting the namespace would delete the
 245 rest of ONAP as well.  To delete DCAE alone, and to make sure all of the
 246 DCAE components deployed by Cloudify Manager are uninstalled:
 247
 248 * Find the Cloudify Manager pod identifier, using a command like:
 249
 250   ``kubectl -n onap get pods | grep dcae-cloudify-manager``
 251 * Execute the DCAE cleanup script on the Cloudify Manager pod, using a command like:
 252
 253   ``kubectl -n onap exec`` `cloudify-manager-pod-id` ``-- /scripts/dcae-cleanup.sh``
 254 * Finally, run ``helm undeploy`` against the DCAE Helm subrelease
 255
 256 The DCAE cleanup script uses Cloudify Manager and the DCAE Kubernetes
 257 plugin to instruct Kubernetes to delete the components deployed by Cloudify
 258 Manager.  This includes the components deployed when the DCAE bootstrap
 259 service ran and any components deployed after bootstrap.