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 Helm Chart Based DCAE Deployment
   5 ================================
   6
   7 This document describes the details of the Helm Chart based deployment process for R2 ONAP and how DCAE is deployed through this process.
   8
   9
  10 ONAP Deployment Overview
  11 ------------------------
  12
  13 ONAP R2 supports Kubernetes deployment.  Kuberenetes is a container orchestration technology that organizes containers into composites of various patterns for easy deployment, management, and scaling.  R2 ONAP utilizes Kubernetes as the foundation for fulfilling its platform maturity promises.
  14
  15 Further, R2 ONAP manages Kubernetes specifications using Helm Charts, under which all Kuberentes yaml-formatted resource specifications and additional files are organized into a hierarchy of charts, sub-charts, and resources.  These yaml files are further augmented with Helm's templating, which makes dependencies and cross-references of parameters and parameter derivatives among resources manageable for a large and complex Kuberentes system such as ONAP.
  16
  17 At deployment time, with a single **helm install** command, Helm resolves all the templates and compiles the chart hierarchy into Kubernetes resource definitions, and invokes Kubernetes deployment operation for all the resources.
  18
  19 All ONAP Helm Charts are organized under the **kubernetes** directory of the **OOM** project, where roughly each ONAP component occupied a subdirectory.  DCAE charts are placed under the **dcaegen2** directory.  DCAE Kubernetes deployment is based on the same set of Docker containers that the Heat based deployment uses, with the exception of bootstrap container and health check container are only used in Kubernetes deployment.
  20
  21
  22 DCAE Chart Organization
  23 -----------------------
  24
  25 Following Helm conventions, each Helm chart directory usually consists of the following files and subdirectories:
  26
  27 * Chart.yaml: meta data;
  28 * requirements.yaml: dependency charts;
  29 * values.yaml: values for Helm templating engine to expand templates;
  30 * resources: subdirectory for additional resource definitions such as configuration, scripts, etc;
  31 * templates: subdirectory for Kubernetes resource definition templates;
  32 * charts: subdirectory for sub-charts.
  33
  34 The dcaegen2 chart has the following sub-charts:
  35
  36 * dcae-bootstrap: a Kubernetes job that deploys additional DCAE components;
  37 * dcae-cloudify-manager: a Kubernetes deployment of a Cloudify Manager;
  38 * dcae-healthcheck: a Kubernetes deployment that provides a DCAE health check API;
  39 * dcae-redis: a Kubernetes deployment of a Redis cluster.
  40
  41
  42 DCAE Deployment
  43 ---------------
  44
  45 At deployment time, when the **helm install** command is executed, all DCAE resources defined within charts under the OOM Chart hierarchy are deployed.  They are the 1st order components, namely the Cloudify Manager deployment, the Health Check deployment, the Redis cluster deployment, and the Bootstrap job.  In addition, a Postgres database deployment is also launched, which is specified as a dependency of the DCAE Bootstrap job.  These resources will show up as the following, where the name before / indicates resource type and the term "dev" is a tag that **helm install** command uses as "release name":
  46   * deploy/dev-dcae-cloudify-manager;
  47   * deploy/dev-dcae-healthcheck;
  48   * statefulsets/dev-dcae-redis;
  49   * statefulsets/dev-dcae-db;
  50   * job/dev-dcae-bootstrap.
  51
  52 In addition, DCAE operations depends on a Consul server cluster.  For ONAP OOM deployment, since Consul cluster is provided as a shared resource, its charts are defined under the consul direcory, not part of DCAE charts.
  53
  54 The dcae-bootstrap job 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:
  55   * dcae-cloudify-manager;
  56   * consul-server;
  57   * msb-discovery;
  58   * kube2msb.
  59
  60 Once started, the DCAE bootstrap job will call Cloudify Manager to deploy a series of Blueprints which specify the additional DCAE R2 components.  These Blueprints are almost identical to the Docker container Blueprints used by DACE R1 and Heat based R2 deployment, except that they are using the k8splugin instead of dockerplugin.  The k8splugin is a major contribution of DCAE R2.  It is a Cloudify Manager plugin that is capable of expanding a Docker container node definition into a Kubernetes deployment definition, with enhancements such as replica scaling, ONAP logging sidecar, MSB registration, etc.
  61
  62 The additional DCAE components launched into ONAP deployment are:
  63   * deploy/dep-config-binding-service;
  64   * deploy/dep-dcae-tca-analytics;
  65   * deploy/dep-dcae-ves-collector;
  66   * deploy/dep-deployment-handler;
  67   * deploy/dep-holmes-engine-mgmt;
  68   * deploy/dep-holmes-rule-mgmt;
  69   * deploy/dep-inventory;
  70   * deploy/dep-policy-handler;
  71   * deploy/dep-pstg-write;
  72   * deploy/dep-service-change-handler.
  73
  74
  75 DCAE Configuration
  76 ------------------
  77
  78 Deployment time configuration of DCAE components are defined in several places.
  79
  80   * Helm Chart templates:
  81      * Helm/Kubernetes template files can contain static values for configuration parameters;
  82   * Helm Chart resources:
  83      * Helm/Kubernetes resources files can contain static values for configuration parameters;
  84   * Helm values.yaml files:
  85      * The values.yaml files supply the values that Helm templating engine uses to expand any templates defined in Helm templates;
  86      * In a Helm chart hierarchy, values defined in values.yaml files in higher level supersedes values defined in values.yaml files in lower level;
  87      * Helm command line supplied values supersedes values defined in any values.yaml files.
  88
  89 In addition, for DCAE components deployed through Cloudify Manager Blueprints, their configuration parameters are defined in the following places:
  90      * The Blueprint files can contain static values for configuration parameters;
  91         * The Blueprint files are defined under the blueprints directory of the dcaegen2/platform/blueprints repo, named with "k8s" prefix.
  92      * 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):
  93         * The Blueprint files can define default values for the input parameters;
  94         * 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;
  95         * The Blueprint input files may contain Helm templates, which are resolved into actual deployment time values following the rules for Helm values.
  96
  97
  98 Now we walk through an example, how to configure the Docker image for the Policy Handler which is deployed by Cloudify Manager.
  99
 100 In the k8s-policy_handler.yaml Blueprint, the Docker image to use is defined as an input parameter with a default value:
 101   **policy_handler_image**:
 102     description: Docker image for policy_handler
 103     default: 'nexus3.onap.org:10001/onap/org.onap.dcaegen2.platform.policy-handler:2.4.3'
 104
 105 Then in the input file, oom/kubernetes/dcaegen2/charts/dcae-bootstrap/resources/inputs/k8s-policy_handler-inputs.yaml, it is defined again as:
 106   **policy_handler_image**: {{ include "common.repository" . }}/{{ .Values.componentImages.policy_handler }}
 107
 108 Thus, when common.repository and componentImages.policy_handler are defined in the values.yaml files, their values will be plugged in here and the composition policy_handler_image will be passed to Policy Handler Blueprint as the Docker image tag to use instead of the default value in the Blueprint.
 109
 110 Indeed the componentImages.ves value is provided in the oom/kubernetes/dcaegen2/charts/dcae-bootstrap/values.yaml file:
 111   componentImages:
 112     policy_handler: onap/org.onap.dcaegen2.platform.policy-handler:2.4.5
 113
 114 The final result is that when DCAE bootstrap calls Cloudify Manager to deploy Policy Handler, the 2.4.5 image will be deployed.
 115
 116 DCAE Service Endpoints
 117 ----------------------
 118
 119 Below is a table of default hostnames and ports for DCAE component service endpoints in Kuubernetes deployment:
 120     ==================   ============================      ================================
 121     Component            Cluster Internal (host:port)      Cluster external (svc_name:port)
 122     ==================   ============================      ================================
 123     VES                  dcae-ves-collector:8080           xdcae-ves-collector.onap:30235
 124     TCA                  dcae-tca-analytics:11011          xdcae-tca-analytics.onap:32010
 125     Policy Handler       policy-handler:25577              NA
 126     Deployment Handler   deployment-handler:8443           NA
 127     Inventory            inventory:8080                    NA
 128     Config binding       config-binding-service:10000      NA
 129     DCAE Healthcheck     dcae-healthcheck:80               NA
 130     Cloudify Manager     dcae-cloudify-manager:80          NA
 131     ==================   ============================      ================================
 132
 133 In addition, a number of ONAP service endpoints that are used by DCAE components are listed as follows for reference by DCAE developers and testers:
 134     ==================   ============================      ================================
 135     Component            Cluster Internal (host:port)      Cluster external (svc_name:port)
 136     ==================   ============================      ================================
 137     Consul Server        consul-server:8500                consul-server:30270
 138     Robot                robot:88                          robot:30209 TCP
 139     Message router       message-router:3904               message-router:30227
 140     Message router       message-router:3905               message-router:30226
 141     MSB Discovery        msb-discovery:10081               msb-discovery:30281
 142     Logging              log-kibana:5601                   log-kibana:30253
 143     AAI                  aai:8080                          aai:30232
 144     AAI                  aai:8443                          aai:30233
 145     ==================   ============================      ================================
 146