diff options
Diffstat (limited to 'docs/oom_developer_guide.rst')
| -rw-r--r-- | docs/oom_developer_guide.rst | 617 |
1 files changed, 465 insertions, 152 deletions
diff --git a/docs/oom_developer_guide.rst b/docs/oom_developer_guide.rst index 1c18044b70..70e2a7253a 100644 --- a/docs/oom_developer_guide.rst +++ b/docs/oom_developer_guide.rst @@ -4,6 +4,7 @@ .. Links .. _Helm: https://docs.helm.sh/ +.. _Helm Charts: https://github.com/kubernetes/charts .. _Kubernetes: https://Kubernetes.io/ .. _Docker: https://www.docker.com/ .. _Nexus: https://nexus.onap.org/#welcome @@ -14,6 +15,7 @@ .. _Kubernetes Storage Class: https://Kubernetes.io/docs/concepts/storage/storage-classes/ .. _Assigning Pods to Nodes: https://Kubernetes.io/docs/concepts/configuration/assign-pod-node/ + .. _developer-guide-label: OOM Developer Guide @@ -64,16 +66,336 @@ ONAP on a single laptop computer. Helm Charts =========== +A Helm chart is a collection of files that describe a related set of Kubernetes +resources. A simple chart might be used to deploy something simple, like a +memcached pod, while a complex chart might contain many micro-service arranged +in a hierarchy as found in the `aai` ONAP component. -Standard Chart Format ---------------------- +Charts are created as files laid out in a particular directory tree, then they +can be packaged into versioned archives to be deployed. There is a public +archive of `Helm Charts`_ on GitHub that includes many technologies applicable +to ONAP. Some of these charts have been used in ONAP and all of the ONAP charts +have been created following the guidelines provided. -Helm charts are available in the open-source community for a wide variety of -common software components which are used in ONAP and where possible. +The top level of the ONAP charts is shown below: +.. graphviz:: -Chart Hierarchy ---------------- + digraph onap_top_chart { + rankdir="LR"; + { + node [shape=folder] + oValues [label="values.yaml"] + oChart [label="Chart.yaml"] + dev [label="dev.yaml"] + prod [label="prod.yaml"] + crb [label="clusterrolebindings.yaml"] + secrets [label="secrets.yaml"] + } + { + node [style=dashed] + vCom [label="component"] + } + + onap -> oValues + onap -> oChart + onap -> templates + onap -> resources + oValues -> vCom + resources -> environments + environments -> dev + environments -> prod + templates -> crb + templates -> secrets + } + +Within the `values.yaml` file at the `onap` level, one will find a set of +boolean values that control which of the ONAP components get deployed as shown +below: + +.. code-block:: yaml + + aaf: # Application Authorization Framework + enabled: false + <...> + so: # Service Orchestrator + enabled: true + +By setting these flags a custom deployment can be created and used during +deployment by using the `-f` Helm option as follows:: + + > helm install local/onap -name development -f dev.yaml + +Note that there are one or more example deployment files in the +`onap/resources/environments/` directory. It is best practice to create a unique +deployment file for each environment used to ensure consistent behaviour. + +To aid in the long term supportability of ONAP, a set of common charts have +been created (and will be expanded in subsequent releases of ONAP) that can be +used by any of the ONAP components by including the common component in its +`requirements.yaml` file. The common components are arranged as follows: + +.. graphviz:: + + digraph onap_common_chart { + rankdir="LR"; + { + node [shape=folder] + mValues [label="values.yaml"] + ccValues [label="values.yaml"] + comValues [label="values.yaml"] + comChart [label="Chart.yaml"] + ccChart [label="Chart.yaml"] + mChart [label="Chart.yaml"] + + mReq [label="requirements.yaml"] + mService [label="service.yaml"] + mMap [label="configmap.yaml"] + ccName [label="_name.tpl"] + ccNS [label="_namespace.tpl"] + } + { + cCom [label="common"] + mTemp [label="templates"] + ccTemp [label="templates"] + } + { + more [label="...",style=dashed] + } + + common -> comValues + common -> comChart + common -> cCom + common -> mysql + common -> more + + cCom -> ccChart + cCom -> ccValues + cCom -> ccTemp + ccTemp -> ccName + ccTemp -> ccNS + + mysql -> mValues + mysql -> mChart + mysql -> mReq + mysql -> mTemp + mTemp -> mService + mTemp -> mMap + } + +The common section of charts consists of a set of templates that assist with +parameter substitution (`_name.tpl` and `_namespace.tpl`) and a set of charts +for components used throughout ONAP. Initially `mysql` is in the common area but +this will expand to include other databases like `mariadb-galera`, `postgres`, +and `cassandra`. Other candidates for common components include `redis` and +`kafka`. When the common components are used by other charts they are +instantiated each time. In subsequent ONAP releases some of the common +components could be a setup as services that are used by multiple ONAP +components thus minimizing the deployment and operational costs. + +All of the ONAP components have charts that follow the pattern shown below: + +.. graphviz:: + + digraph onap_component_chart { + rankdir="LR"; + { + node [shape=folder] + cValues [label="values.yaml"] + cChart [label="Chart.yaml"] + cService [label="service.yaml"] + cMap [label="configmap.yaml"] + cFiles [label="config file(s)"] + } + { + cCharts [label="charts"] + cTemp [label="templates"] + cRes [label="resources"] + + } + { + sCom [label="component",style=dashed] + } + + component -> cValues + component -> cChart + component -> cCharts + component -> cTemp + component -> cRes + cTemp -> cService + cTemp -> cMap + cRes -> config + config -> cFiles + cCharts -> sCom + } + +Note that the component charts may include a hierarchy of components and in +themselves can be quite complex. + +Configuration of the components varies somewhat from component to component but +generally follows the pattern of one or more `configmap.yaml` files which can +directly provide configuration to the containers in addition to processing +configuration files stored in the `config` directory. It is the responsibility +of each ONAP component team to update these configuration files when changes +are made to the project containers that impact configuration. + +The following section describes how the hierarchical ONAP configuration system is +key to management of such a large system. + +Configuration Management +======================== + +ONAP is a large system composed of many components - each of which are complex +systems in themselves - that needs to be deployed in a number of different +ways. For example, within a single operator's network there may be R&D +deployments under active development, pre-production versions undergoing system +testing and production systems that are operating live networks. Each of these +deployments will differ in significant ways, such as the version of the +software images deployed. In addition, there may be a number of application +specific configuration differences, such as operating system environment +variables. The following describes how the Helm configuration management +system is used within the OOM project to manage both ONAP infrastructure +configuration as well as ONAP components configuration. + +One of the artifacts that OOM/Kubernetes uses to deploy ONAP components is the +deployment specification, yet another yaml file. Within these deployment specs +are a number of parameters as shown in the following mariadb example: + +.. code-block:: yaml + + apiVersion: extensions/v1beta1 + kind: Deployment + metadata: + name: mariadb + spec: + <...> + template: + <...> + spec: + hostname: mariadb + containers: + - args: + image: nexus3.onap.org:10001/mariadb:10.1.11 + name: "mariadb" + env: + - name: MYSQL_ROOT_PASSWORD + value: password + - name: MARIADB_MAJOR + value: "10.1" + <...> + imagePullSecrets: + - name: onap-docker-registry-key + +Note that within the deployment specification, one of the container arguments +is the key/value pair image: nexus3.onap.org:10001/mariadb:10.1.11 which +specifies the version of the mariadb software to deploy. Although the +deployment specifications greatly simplify deployment, maintenance of the +deployment specifications themselves become problematic as software versions +change over time or as different versions are required for different +deployments. For example, if the R&D team needs to deploy a newer version of +mariadb than what is currently used in the production environment, they would +need to clone the deployment specification and change this value. Fortunately, +this problem has been solved with the templating capabilities of Helm. + +The following example shows how the deployment specifications are modified to +incorporate Helm templates such that key/value pairs can be defined outside of +the deployment specifications and passed during instantiation of the component. + +.. code-block:: yaml + + apiVersion: extensions/v1beta1 + kind: Deployment + metadata: + name: mariadb + namespace: "{{ .Values.nsPrefix }}-mso" + spec: + <...> + template: + <...> + spec: + hostname: mariadb + containers: + - args: + image: {{ .Values.image.mariadb }} + imagePullPolicy: {{ .Values.pullPolicy }} + name: "mariadb" + env: + - name: MYSQL_ROOT_PASSWORD + value: password + - name: MARIADB_MAJOR + value: "10.1" + <...> + imagePullSecrets: + - name: "{{ .Values.nsPrefix }}-docker-registry-key"apiVersion: extensions/v1beta1 + kind: Deployment + metadata: + name: mariadb + namespace: "{{ .Values.nsPrefix }}-mso" + spec: + <...> + template: + <...> + spec: + hostname: mariadb + containers: + - args: + image: {{ .Values.image.mariadb }} + imagePullPolicy: {{ .Values.pullPolicy }} + name: "mariadb" + env: + - name: MYSQL_ROOT_PASSWORD + value: password + - name: MARIADB_MAJOR + value: "10.1" + <...> + imagePullSecrets: + - name: "{{ .Values.nsPrefix }}-docker-registry-key" + +This version of the deployment specification has gone through the process of +templating values that are likely to change between deployments. Note that the +image is now specified as: image: {{ .Values.image.mariadb }} instead of a +string used previously. During the deployment phase, Helm (actually the Helm +sub-component Tiller) substitutes the {{ .. }} entries with a variable defined +in a values.yaml file. The content of this file is as follows: + +.. code-block:: yaml + + nsPrefix: onap + pullPolicy: IfNotPresent + image: + readiness: oomk8s/readiness-check:2.0.0 + mso: nexus3.onap.org:10001/openecomp/mso:1.0-STAGING-latest + mariadb: nexus3.onap.org:10001/mariadb:10.1.11 + +Within the values.yaml file there is an image section with the key/value pair +mariadb: nexus3.onap.org:10001/mariadb:10.1.11 which is the same value used in +the non-templated version. Once all of the substitutions are complete, the +resulting deployment specification ready to be used by Kubernetes. + +Also note that in this example, the namespace key/value pair is specified in +the values.yaml file. This key/value pair will be global across the entire +ONAP deployment and is therefore a prime example of where configuration +hierarchy can be very useful. + +When creating a deployment template consider the use of default values if +appropriate. Helm templating has built in support for DEFAULT values, here is +an example: + +.. code-block:: yaml + + imagePullSecrets: + - name: "{{ .Values.nsPrefix | default "onap" }}-docker-registry-key" + +The pipeline operator ("|") used here hints at that power of Helm templates in +that much like an operating system command line the pipeline operator allow +over 60 Helm functions to be embedded directly into the template (note that the +Helm template language is a superset of the Go template language). These +functions include simple string operations like upper and more complex flow +control operations like if/else. + + +ONAP Application Configuration +------------------------------ Dependency Management --------------------- @@ -177,17 +499,32 @@ Nodes ~~~~~ OOM works with both physical and virtual worker machines. -* Virtual Machine Deployments - If ONAP is to be deployed onto a set of virtual machines, the creation of the VMs is outside of the scope of OOM and could be done in many ways, such as +* Virtual Machine Deployments - If ONAP is to be deployed onto a set of virtual + machines, the creation of the VMs is outside of the scope of OOM and could be + done in many ways, such as - * manually, for example by a user using the OpenStack Horizon dashboard or AWS EC2, or - * automatically, for example with the use of a OpenStack Heat Orchestration Template which builds an ONAP stack, Azure ARM template, AWS CloudFormation Template, or - * orchestrated, for example with Cloudify creating the VMs from a TOSCA template and controlling their life cycle for the life of the ONAP deployment. + * manually, for example by a user using the OpenStack Horizon dashboard or + AWS EC2, or + * automatically, for example with the use of a OpenStack Heat Orchestration + Template which builds an ONAP stack, Azure ARM template, AWS CloudFormation + Template, or + * orchestrated, for example with Cloudify creating the VMs from a TOSCA + template and controlling their life cycle for the life of the ONAP + deployment. -* Physical Machine Deployments - If ONAP is to be deployed onto physical machines there are several options but the recommendation is to use Rancher along with Helm to associate hosts with a Kubernetes cluster. +* Physical Machine Deployments - If ONAP is to be deployed onto physical + machines there are several options but the recommendation is to use Rancher + along with Helm to associate hosts with a Kubernetes cluster. Pods ~~~~ -A group of containers with shared storage and networking can be grouped together into a Kubernetes pod. All of the containers within a pod are co-located and co-scheduled so they operate as a single unit. Within ONAP Amsterdam release, pods are mapped one-to-one to docker containers although this may change in the future. As explained in the Services section below the use of Pods within each ONAP component is abstracted from other ONAP components. +A group of containers with shared storage and networking can be grouped +together into a Kubernetes pod. All of the containers within a pod are +co-located and co-scheduled so they operate as a single unit. Within ONAP +Amsterdam release, pods are mapped one-to-one to docker containers although +this may change in the future. As explained in the Services section below the +use of Pods within each ONAP component is abstracted from other ONAP +components. Services ~~~~~~~~ @@ -328,10 +665,10 @@ machines). For example: nodeSelector: failure-domain.beta.Kubernetes.io/region: {{ .Values.location }} -- "location: West" is specified in the values.yaml file used to deploy - one DCAE cluster and "location: East" is specified in a second values.yaml +- "location: West" is specified in the `values.yaml` file used to deploy + one DCAE cluster and "location: East" is specified in a second `values.yaml` file (see OOM Configuration Management for more information about - configuration files like the values.yamlfile). + configuration files like the `values.yaml` file). Node affinity can also be used to achieve geographic redundancy if pods are assigned to multiple failure domains. For more information refer to `Assigning @@ -461,166 +798,142 @@ the database components of each of the projects and the same technique can be used for all persistent state information. -Configuration Management -======================== -ONAP is a large system composed of many components - each of which are complex -systems in themselves - that needs to be deployed in a number of different -ways. For example, within a single operator's network there may be R&D -deployments under active development, pre-production versions undergoing system -testing and production systems that are operating live networks. Each of these -deployments will differ in significant ways, such as the version of the -software images deployed. In addition, there may be a number of application -specific configuration differences, such as operating system environment -variables. The following describes how the Helm configuration management -system is used within the OOM project to manage both ONAP infrastructure -configuration as well as ONAP components configuration. +Environment Files +~~~~~~~~~~~~~~~~~ -One of the artifacts that OOM/Kubernetes uses to deploy ONAP components is the -deployment specification, yet another yaml file. Within these deployment specs -are a number of parameters as shown in the following mariadb example: +MSB Integration +=============== -.. code-block:: yaml +The \ `Microservices Bus +Project <https://wiki.onap.org/pages/viewpage.action?pageId=3246982>`__ provides +facilities to integrate micro-services into ONAP and therefore needs to +integrate into OOM - primarily through Consul which is the backend of +MSB service discovery. The following is a brief description of how this +integration will be done: - apiVersion: extensions/v1beta1 - kind: Deployment - metadata: - name: mariadb - spec: - <...> - template: - <...> - spec: - hostname: mariadb - containers: - - args: - image: nexus3.onap.org:10001/mariadb:10.1.11 - name: "mariadb" - env: - - name: MYSQL_ROOT_PASSWORD - value: password - - name: MARIADB_MAJOR - value: "10.1" - <...> - imagePullSecrets: - - name: onap-docker-registry-key +A registrator to push the service endpoint info to MSB service +discovery. -Note that within the deployment specification, one of the container arguments -is the key/value pair image: nexus3.onap.org:10001/mariadb:10.1.11 which -specifies the version of the mariadb software to deploy. Although the -deployment specifications greatly simplify deployment, maintenance of the -deployment specifications themselves become problematic as software versions -change over time or as different versions are required for different -deployments. For example, if the R&D team needs to deploy a newer version of -mariadb than what is currently used in the production environment, they would -need to clone the deployment specification and change this value. Fortunately, -this problem has been solved with the templating capabilities of Helm. +- The needed service endpoint info is put into the kubernetes yaml file + as annotation, including service name, Protocol,version, visual + range,LB method, IP, Port,etc. -The following example shows how the deployment specifications are modified to -incorporate Helm templates such that key/value pairs can be defined outside of -the deployment specifications and passed during instantiation of the component. +- OOM deploy/start/restart/scale in/scale out/upgrade ONAP components + +- Registrator watch the kubernetes event + +- When an ONAP component instance has been started/destroyed by OOM, + Registrator get the notification from kubernetes + +- Registrator parse the service endpoint info from annotation and + register/update/unregister it to MSB service discovery + +- MSB API Gateway uses the service endpoint info for service routing + and load balancing. + +Details of the registration service API can be found at \ `Microservice +Bus API +Documentation <https://wiki.onap.org/display/DW/Microservice+Bus+API+Documentation>`__. + +ONAP Component Registration to MSB +---------------------------------- +The charts of all ONAP components intending to register against MSB must have +an annotation in their service(s) template. A `sdc` example follows: .. code-block:: yaml - apiVersion: extensions/v1beta1 - kind: Deployment - metadata: - name: mariadb - namespace: "{{ .Values.nsPrefix }}-mso" - spec: - <...> - template: - <...> - spec: - hostname: mariadb - containers: - - args: - image: {{ .Values.image.mariadb }} - imagePullPolicy: {{ .Values.pullPolicy }} - name: "mariadb" - env: - - name: MYSQL_ROOT_PASSWORD - value: password - - name: MARIADB_MAJOR - value: "10.1" - <...> - imagePullSecrets: - - name: "{{ .Values.nsPrefix }}-docker-registry-key"apiVersion: extensions/v1beta1 - kind: Deployment + apiVersion: v1 + kind: Service metadata: - name: mariadb - namespace: "{{ .Values.nsPrefix }}-mso" - spec: - <...> - template: - <...> - spec: - hostname: mariadb - containers: - - args: - image: {{ .Values.image.mariadb }} - imagePullPolicy: {{ .Values.pullPolicy }} - name: "mariadb" - env: - - name: MYSQL_ROOT_PASSWORD - value: password - - name: MARIADB_MAJOR - value: "10.1" - <...> - imagePullSecrets: - - name: "{{ .Values.nsPrefix }}-docker-registry-key" + labels: + app: sdc-be + name: sdc-be + namespace: "{{ .Values.nsPrefix }}" + annotations: + msb.onap.org/service-info: '[ + { + "serviceName": "sdc", + "version": "v1", + "url": "/sdc/v1", + "protocol": "REST", + "port": "8080", + "visualRange":"1" + }, + { + "serviceName": "sdc-deprecated", + "version": "v1", + "url": "/sdc/v1", + "protocol": "REST", + "port": "8080", + "visualRange":"1", + "path":"/sdc/v1" + } + ]' + ... -This version of the deployment specification has gone through the process of -templating values that are likely to change between deployments. Note that the -image is now specified as: image: {{ .Values.image.mariadb }} instead of a -string used previously. During the deployment phase, Helm (actually the Helm -sub-component Tiller) substitutes the {{ .. }} entries with a variable defined -in a values.yaml file. The content of this file is as follows: -.. code-block:: yaml +MSB Integration with OOM +------------------------ +A preliminary view of the OOM-MSB integration is as follows: - nsPrefix: onap - pullPolicy: IfNotPresent - image: - readiness: oomk8s/readiness-check:1.0.0 - mso: nexus3.onap.org:10001/openecomp/mso:1.0-STAGING-latest - mariadb: nexus3.onap.org:10001/mariadb:10.1.11 +.. figure:: MSB-OOM-Diagram.png -Within the values.yaml file there is an image section with the key/value pair -mariadb: nexus3.onap.org:10001/mariadb:10.1.11 which is the same value used in -the non-templated version. Once all of the substitutions are complete, the -resulting deployment specification ready to be used by Kubernetes. +A message sequence chart of the registration process: -Also note that in this example, the namespace key/value pair is specified in -the values.yaml file. This key/value pair will be global across the entire -ONAP deployment and is therefore a prime example of where configuration -hierarchy can be very useful. +.. uml:: -When creating a deployment template consider the use of default values if -appropriate. Helm templating has built in support for DEFAULT values, here is -an example: + participant "OOM" as oom + participant "ONAP Component" as onap + participant "Service Discovery" as sd + participant "External API Gateway" as eagw + participant "Router (Internal API Gateway)" as iagw -.. code-block:: yaml + box "MSB" #LightBlue + participant sd + participant eagw + participant iagw + end box - imagePullSecrets: - - name: "{{ .Values.nsPrefix | default "onap" }}-docker-registry-key" + == Deploy Servcie == -The pipeline operator ("|") used here hints at that power of Helm templates in -that much like an operating system command line the pipeline operator allow -over 60 Helm functions to be embedded directly into the template (note that the -Helm template language is a superset of the Go template language). These -functions include simple string operations like upper and more complex flow -control operations like if/else. + oom -> onap: Deploy + oom -> sd: Register service endpoints + sd -> eagw: Services exposed to external system + sd -> iagw: Services for internal use + == Component Life-cycle Management == -ONAP Application Configuration ------------------------------- + oom -> onap: Start/Stop/Scale/Migrate/Upgrade + oom -> sd: Update service info + sd -> eagw: Update service info + sd -> iagw: Update service info -Environment Files -~~~~~~~~~~~~~~~~~ + == Service Health Check == + + sd -> onap: Check the health of service + sd -> eagw: Update service status + sd -> iagw: Update service status + + +MSB Deployment Instructions +--------------------------- +MSB is helm installable ONAP component which is often automatically deployed. +To install it individually enter:: + + > helm install <repo-name>/msb + +.. note:: + TBD: Vaidate if the following procedure is still required. + +Please note that Kubernetes authentication token must be set at +*kubernetes/kube2msb/values.yaml* so the kube2msb registrator can get the +access to watch the kubernetes events and get service annotation by +Kubernetes APIs. The token can be found in the kubectl configuration file +*~/.kube/config* + +More details can be found here `MSB installation <http://onap.readthedocs.io/en/latest/submodules/msb/apigateway.git/docs/platform/installation.html>`__. -MSB Integration -=============== .. MISC .. ==== .. Note that although OOM uses Kubernetes facilities to minimize the effort |