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)
   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
  25
  26 With DCAE Transformation to Helm completed in Jakarta/R10 release, all DCAE components deployment is supported only via helm.  Charts for individual MS are available under **dcaegen2-services** directory under OOM project (https://git.onap.org/oom/tree/kubernetes/dcaegen2-services/components). With ONAP deployment, four DCAE services (HV VES collector, VES collector, PNF Registration Handler, and TCA (Gen2) analytics service) are bootstrapped via Helm charts.
  27
  28 Other DCAE Services can be deployed on-demand via their independent helm-charts. For on-demand helm chart, refer to steps described in :ref:`Helm install/upgrade section <dcae-service-deployment>`.
  29
  30
  31 .. note::
  32   DCAE platform components deployments is optionally available through Helm charts under the **dcaegen2** directory however this mode is not supported with Jakarta release. These charts will be removed in subsequent release.
  33
  34
  35
  36 DCAE Chart Organization
  37 -----------------------
  38
  39 Following Helm conventions, the DCAE Helm chart directory (``oom/kubernetes/dcaegen2-services`` & ``oom/kubernetes/dcaegen2``) consists of the following files and subdirectories:
  40
  41 * ``Chart.yaml``: metadata.
  42 * ``requirements.yaml``: dependency charts.
  43 * ``values.yaml``: values for Helm templating engine to expand templates.
  44 * ``resources``: subdirectory for additional resource definitions such as configuration, scripts, etc.
  45 * ``Makefile``: make file to build DCAE charts
  46 * ``components``: subdirectory for DCAE sub-charts.
  47
  48
  49 The dcaegen2-services chart has the following sub-charts:
  50
  51 * ``dcae-datafile-collector``: deploys the DCAE DataFile Collector service.
  52 * ``dcae-hv-ves-collector``: deploys the DCAE High-Volume VES collector service.
  53 * ``dcae-ms-healthcheck``: deploys a health check component that tests the health of the 4 DCAE services deployed via Helm.
  54 * ``dcae-pm-mapper``: deploys the DCAE PM-Mapper service.
  55 * ``dcae-prh``: deploys the DCAE PNF Registration Handler service.
  56 * ``dcae-tcagen2``: deploys the DCAE TCA analytics service.
  57 * ``dcae-ves-collector``: deploys the DCAE VES collector service.
  58 * ``dcae-datafile-collector``: deploys the DCAE Datafile collector service.
  59 * ``dcae-datalake-admin-ui``: deploys the Datalake Admin UI service.
  60 * ``dcae-datalake-des``: deploys the Datalake Data Extraction service.
  61 * ``dcae-datalake-feeder``: deploys the Datalake Feeder service.
  62 * ``dcae-heartbeat``: deploys the DCAE Heartbeat microservice.
  63 * ``dcae-kpi-ms``: deploys the DCAE KPI computation microservice.
  64 * ``dcae-ms-healthcheck``: deploys the DCAE healthcheck service that provides API to check health of bootstrapped DCAE service deployed via helm
  65 * ``dcae-pm-mapper``: deploys the DCAE PM-Mapper service.
  66 * ``dcae-pmsh``: deploys the DCAE PM Subscription Handler service.
  67 * ``dcae-restconf-collector``: deploys the DCAE RESTConf collector service.
  68 * ``dcae-slice-analysis-ms``: deploys the DCAE Slice Analysis service.
  69 * ``dcae-snmptrap-collector``: deploys the DCAE SNMPTRAP collector service.
  70 * ``dcae-son-handler``: deploys the DCAE SON-Handler microservice.
  71 * ``dcae-ves-mapper``: deploys the DCAE VES Mapper microservice.
  72 * ``dcae-ves-openapi-manager``: deploys the DCAE service validator of VES_EVENT type artifacts from distributed services.
  73
  74
  75 The dcaegen2-services sub-charts depend on a set of common templates, found under the ``common`` subdirectory under ``dcaegen2-services``.
  76
  77 Information about using the common templates to deploy a microservice can be
  78 found in :doc:`Using Helm to deploy DCAE Microservices <./dcaeservice_helm_template>`.
  79
  80
  81 DCAE Deployment
  82 ---------------
  83
  84 At deployment time for ONAP, when the **helm deploy** command is executed,
  85 only the DCAE resources defined within the subcharts - "dcaegen2-services" above are deployed
  86 (based on override file configuration defined in `values.yaml <https://git.onap.org/oom/tree/kubernetes/dcaegen2-services/values.yaml>`_
  87
  88 These include:
  89
  90 * DCAE Service components:
  91   * VES Collector
  92   * HV-VES Collector
  93   * PNF-Registration Handler Service
  94   * Threshold Crossing Analysis (TCA-gen2)
  95 * DCAE-Services healthcheck
  96 * VES OpenAPI Manager
  97
  98 Some of the DCAE subcharts include an initContainer that checks to see if
  99 other services that they need in order to run have become ready.  The installation
 100 of these subcharts will pause until the needed services are available.
 101
 102 Since Istanbul release, DCAE bootstrapped Microservice deployment are managed completely under Helm.
 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 As majority of DCAE services rely on DMAAP (MR and DR) interfaces, ONAP/DMAAP must also be enabled under OOM deployment configuration.
 108
 109 DCAE Configuration
 110 ------------------
 111
 112 Deployment time configuration of DCAE components are defined in several places.
 113
 114   * Helm Chart templates:
 115      * Helm/Kubernetes template files can contain static values for configuration parameters;
 116   * Helm Chart resources:
 117      * Helm/Kubernetes resources files can contain static values for configuration parameters;
 118   * Helm values.yaml files:
 119      * The values.yaml files supply the values that Helm templating engine uses to expand any templates defined in Helm templates;
 120      * In a Helm chart hierarchy, values defined in values.yaml files in higher level supersedes values defined in values.yaml files in lower level;
 121      * Helm command line supplied values supersedes values defined in any values.yaml files.
 122
 123
 124 .. _dcae-service-deployment:
 125
 126 On-demand deployment/upgrade through Helm
 127 -----------------------------------------
 128
 129 Under DCAE Transformation to Helm, all DCAE components has been delivered as helm charts under
 130 OOM repository (https://git.onap.org/oom/tree/kubernetes/dcaegen2-services).
 131
 132
 133 All DCAE component charts follows standard Helm structure. Each Microservice charts has predefined configuration defined under
 134 ``applicationConfig`` which can be modified or overridden at deployment time.
 135
 136 Using helm, any of DCAE microservice can be deployed/upgraded/uninstalled on-demand.
 137
 138 ``Pre-Install``
 139
 140 .. note::
 141   This step is only required when helm install should be done on different releasename/prefix from rest of ONAP deployment
 142
 143 With Istanbul release, OOM team included support for ServiceAccount in ONAP deployment to limit the pod access to API server.
 144
 145 Following packages has been added under oom/common to support pre-provisioning of cluster roles and ServiceAccount management
 146
 147   * `ServiceAccount <https://git.onap.org/oom/tree/kubernetes/common/serviceAccount/values.yaml>`_
 148   * `RoleWrapper <https://git.onap.org/oom/tree/kubernetes/common/roles-wrapper>`_
 149
 150 When deployed, these chart will create the ServiceAccount and Role (based on override) and required Rolebinding (to associate the Serviceaccount to a role).
 151
 152 ONAP deployment by default includes the required provisioning of roles under release name (such as "dev") under which ONAP is deployed. For subsequent
 153 helm installation under same release name prefix (i.e dev-) no further action is required.
 154
 155 When Helm install is required under different releasename prefix, then execute following command prior to running helm install.
 156
 157    .. code-block:: bash
 158
 159         helm install <DEPLOYMENT_PREFIX>-role-wrapper local/roles-wrapper -n <namespace>
 160
 161
 162 Followed by install of required service/chart
 163
 164     .. code-block:: bash
 165
 166         helm -n <namespace> install <DEPLOYMENT_PREFIX>-dcaegen2-services oom/kubernetes/dcaegen2-services
 167
 168
 169 ``Installation``
 170
 171 Review and update local copy of dcaegen2-service ``values.yaml`` oom/kubernetes/dcaegen2-services/values.yaml
 172 to ensure component is enabled for deployment (or provide as command line override)
 173
 174     .. code-block:: bash
 175
 176         helm -n <namespace> install <DEPLOYMENT_PREFIX>-dcaegen2-services oom/kubernetes/dcaegen2-services
 177
 178
 179 Service component can also be installed individually from oom/kubernetes/dcaegen2-services/components/<dcae-ms-chart>
 180
 181     .. code-block:: bash
 182
 183         helm -n onap install dev-dcaegen2-services-ves-mapper oom/kubernetes/dcaegen2-services/components/dcae-ves-mapper -f values.yaml
 184
 185 Using -f flag override file can be specified which will take precedence over default configuration.
 186 When commandline override is not provided, default (values.yaml) provided in chart-directory will be used.
 187
 188 ``Upgrade``
 189
 190 Helm support upgrade of charts already deployed; using ``upgrade``  component deployment can be modified
 191
 192     .. code-block:: bash
 193
 194         helm -n <namespace> upgrade <DEPLOYMENT_PREFIX>-dcaegen2-services --reuse-values --values <updated values.yaml path> <dcaegen2-services helm charts path>
 195
 196
 197 For minor configuration updates, helm also supports new values to be provided inline to the upgrade command. Example below -
 198
 199     .. code-block:: bash
 200
 201         helm -n onap upgrade dev-dcaegen2-services oom/kubernetes/dcaegen2-services --reuse-values --set dcae-ves-collector.applicationConfig.auth.method="noAuth"
 202
 203 ``Uninstall``
 204
 205 Components can be uninstalled using delete command.
 206
 207     .. code-block:: bash
 208
 209         helm -n <namespace> delete <DEPLOYMENT_PREFIX>-dcaegen2-services
 210
 211 DCAE Service Endpoints
 212 ----------------------
 213
 214 Below is a table of default hostnames and ports for DCAE component service endpoints in Kubernetes deployment:
 215     ===================  ==================================   =======================================================
 216     Component            Cluster Internal (host:port)         Cluster external (svc_name:port)
 217     ===================  ==================================   =======================================================
 218     VES                  dcae-ves-collector:8443              dcae-ves-collector.onap:30417
 219     HV-VES               dcae-hv-ves-collector:6061           dcae-hv-ves-collector.onap:30222
 220     TCA-Gen2             dcae-tcagen2:9091                    NA
 221     PRH                  dcae-prh:8100                        NA
 222     DCAE MS Healthcheck  dcae-ms-healthcheck:8080             NA
 223     ===================  ==================================   =======================================================
 224
 225 In addition, a number of ONAP service endpoints that are used by DCAE components are listed as follows
 226 for reference by DCAE developers and testers:
 227
 228     ====================   ============================      ================================
 229     Component              Cluster Internal (host:port)      Cluster external (svc_name:port)
 230     ====================   ============================      ================================
 231     Robot                  robot:88                          robot:30209 TCP
 232     Message router         message-router:3904               NA
 233     Message router         message-router:3905               message-router-external:30226
 234     Message router Kafka   message-router-kafka:9092         NA
 235     ====================   ============================      ================================
 236
 237 Uninstalling DCAE
 238 -----------------
 239
 240 All of the DCAE components deployed using the OOM Helm charts will be
 241 deleted by the ``helm undeploy`` command.  This command can be used to
 242 uninstall all of ONAP by undeploying the top-level Helm release that was
 243 created by the ``helm deploy`` command.  The command can also be used to
 244 uninstall just DCAE, by having the command undeploy the `top_level_release_name`-``dcaegen2-services``
 245 Helm sub-release.
 246
 247 Helm will undeploy only the components that were originally deployed using
 248 Helm charts. When uninstalling all of ONAP, it is sufficient to delete the namespace
 249 used for the deployment (typically ``onap``) after running the undeploy
 250 operation.  Deleting the namespace will get rid of any remaining resources
 251 in the namespace.
 252
 253
 254 To undeploy the DCAE services deployed via Helm (the hv-ves-collector, ves-collector, tcagen2,
 255 and prh), use the ``helm undeploy`` command against the `top_level_release_name`-``dcaegen2-services``
 256 Helm sub-release.