diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/MSB-OOM-MSC.png | bin | 108096 -> 0 bytes | |||
-rw-r--r-- | docs/oom_cloud_setup_guide.rst | 51 | ||||
-rw-r--r-- | docs/oom_developer_guide.rst | 617 | ||||
-rw-r--r-- | docs/oom_quickstart_guide.rst | 2 | ||||
-rw-r--r-- | docs/oom_user_guide.rst | 53 |
5 files changed, 551 insertions, 172 deletions
diff --git a/docs/MSB-OOM-MSC.png b/docs/MSB-OOM-MSC.png Binary files differdeleted file mode 100644 index 7c1e076ada..0000000000 --- a/docs/MSB-OOM-MSC.png +++ /dev/null diff --git a/docs/oom_cloud_setup_guide.rst b/docs/oom_cloud_setup_guide.rst index 9cccc91431..f967931234 100644 --- a/docs/oom_cloud_setup_guide.rst +++ b/docs/oom_cloud_setup_guide.rst @@ -2,6 +2,16 @@ .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2018 Amdocs, Bell Canada +.. Links +.. _Microsoft Azure: https://wiki.onap.org/display/DW/ONAP+on+Kubernetes+on+Microsoft+Azure +.. _Amazon AWS: https://wiki.onap.org/display/DW/ONAP+on+Kubernetes+on+Amazon+EC2 +.. _Google GCE: https://wiki.onap.org/display/DW/ONAP+on+Kubernetes+on+Google+Compute+Engine +.. _VMware VIO: https://wiki.onap.org/display/DW/ONAP+on+VMware+Integrated+OpenStack+-+Container+Orchestration +.. _OpenStack: https://wiki.onap.org/display/DW/ONAP+on+Kubernetes+on+OpenStack?src=contextnavpagetreemode +.. _Setting Up Kubernetes with Rancher: https://wiki.onap.org/display/DW/ONAP+on+Kubernetes+on+Rancher +.. _Setting Up Kubernetes with Kubeadm: https://wiki.onap.org/display/DW/Deploying+Kubernetes+Cluster+with+kubeadm +.. _Setting Up Kubernetes with Cloudify: https://wiki.onap.org/display/DW/ONAP+on+Kubernetes+on+Cloudify + .. figure:: oomLogoV2-medium.png :align: right @@ -21,11 +31,14 @@ environment, the Kubernetes environment may be used for an extended period of time, possibly spanning multiple ONAP releases. .. note:: - Inclusion of a cloud technology or provider in this guide does not imply any - endorsement of this technology. + Inclusion of a cloud technology or provider in this guide does not imply an + endorsement. .. _Kubernetes: https://kubernetes.io/ +Software Requirements +===================== + The versions of Kubernetes that are supported by OOM are as follows: .. table:: OOM Software Requirements @@ -34,12 +47,23 @@ The versions of Kubernetes that are supported by OOM are as follows: Release Kubernetes Helm kubectl Docker ============== ========== ===== ======= ======== amsterdam 1.7.x 2.3.x 1.7.x 1.12.x - beijing/master 1.8.5 2.7.x 1.8.5 1.12.x + beijing/master 1.8.10 2.7.x 1.8.10 17.03.x ============== ========== ===== ======= ======== -Minimum Hardware Requirements -============================= +Minimum Hardware Configuration +============================== + +The minimum hardware requirements are provided below. Note that although ONAP +may operate on a single node as described production deployments will need at +least three if not six nodes to ensure there is no single point of failure. +.. table:: OOM Hardware Requirements + + ===== ===== ====== ==================== + RAM HD vCores Ports + ===== ===== ====== ==================== + 128GB 160GB 16 0.0.0.0/0 (all open) + ===== ===== ====== ==================== Cloud Installation ================== @@ -47,18 +71,17 @@ Cloud Installation #. OOM supports deployment on major public clouds. The following guides provide instructions on how to deploy ONAP on these clouds: - - Microsoft Azure, - - Amazon AWS, - - Google GCD, - - VMware VIO, + - `Microsoft Azure`_, + - `Amazon AWS`_, + - `Google GCE`_, + - `VMware VIO`_, - IBM, and - - Openstack + - `Openstack`_. #. Alternatively, OOM can be deployed on a private set of physical hosts or VMs (or even a combination of the two). The following guides describe how to create a Kubernetes cluster with popular tools: - - Setting up Kubernetes with Rancher (recommended) - - Setting up Kubernetes with Kubeadm - - Setting up Kubernetes with Cloudify - + - `Setting up Kubernetes with Rancher`_ (recommended) + - `Setting up Kubernetes with Kubeadm`_ + - `Setting up Kubernetes with Cloudify`_ 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 diff --git a/docs/oom_quickstart_guide.rst b/docs/oom_quickstart_guide.rst index 879bbb923d..eb5d373721 100644 --- a/docs/oom_quickstart_guide.rst +++ b/docs/oom_quickstart_guide.rst @@ -166,7 +166,7 @@ follows:: **Step 7.** Once the repo is setup, installation of ONAP can be done with a single command:: - > helm install local/onap -name dev --namespace onap + > helm install local/onap -n dev --namespace onap .. note:: The requirement for the use of the `onap` namespace will be lifted once the OOM team completes their Beijing deveivers. diff --git a/docs/oom_user_guide.rst b/docs/oom_user_guide.rst index 97b2fde01a..6b0c00e25a 100644 --- a/docs/oom_user_guide.rst +++ b/docs/oom_user_guide.rst @@ -48,7 +48,48 @@ The OOM team with assistance from the ONAP project teams, have built a comprehensive set of Helm charts, yaml files very similar to TOSCA files, that describe the composition of each of the ONAP components and the relationship within and between components. Using this model Helm is able to deploy all of -ONAP this simple command:: +ONAP with a few simple commands. + +Pre-requisites +-------------- +Your environment must have both the Kubernetes `kubectl` and Helm setup as a one time activity. + +Install Kubectl +~~~~~~~~~~~~~~~ +Enter the following to install kubectl (on Ubuntu, there are slight differences on other O/Ss), the Kubernetes command line interface used to manage a Kubernetes cluster:: + + > curl -LO https://storage.googleapis.com/kubernetes-release/release/v1.8.10/bin/linux/amd64/kubectl + > chmod +x ./kubectl + > sudo mv ./kubectl /usr/local/bin/kubectl + > mkdir ~/.kube + +Paste kubectl config from Rancher (see the :ref:`cloud-setup-guide-label` for alternative Kubenetes environment setups) into the `~/.kube/config` file. + +Verify that the Kubernetes config is correct:: + + > kubectl get pods --all-namespaces + +At this point you should see six Kubernetes pods running. + +Install Helm +~~~~~~~~~~~~ +Helm is used by OOM for package and configuration management. To install Helm, enter the following:: + + > wget http://storage.googleapis.com/kubernetes-helm/helm-v2.7.2-linux-amd64.tar.gz + > tar -zxvf helm-v2.7.2-linux-amd64.tar.gz + > sudo mv linux-amd64/helm /usr/local/bin/helm + +Verify the Helm version with:: + + > helm version + +Install the Helm Tiller application and initialize with:: + + > helm init + +Install the Helm Repo +--------------------- +Once kubectl and Helm are setup, one needs to setup a local Helm server to server up the ONAP charts:: > helm install osn/onap @@ -68,10 +109,12 @@ stable which should be removed to avoid confusion:: To prepare your system for an installation of ONAP, you'll need to:: > git clone http://gerrit.onap.org/r/oom - > cd kubernetes + > cd oom/kubernetes + To setup a local Helm server to server up the ONAP charts:: + > helm init > helm serve & Note the port number that is listed and use it in the Helm repo add as follows:: @@ -104,13 +147,13 @@ In any case, setup of the Helm repository is a one time activity. Once the repo is setup, installation of ONAP can be done with a single command:: - > helm install local/onap -name development + > helm install local/onap --name development This will install ONAP from a local repository in a 'development' Helm release. As described below, to override the default configuration values provided by OOM, an environment file can be provided on the command line as follows:: - > helm install local/onap -name development -f onap-development.yaml + > helm install local/onap --name development -f onap-development.yaml To get a summary of the status of all of the pods (containers) running in your deployment:: @@ -127,7 +170,7 @@ deployment:: was created for each of the ONAP components. .. note:: - The Helm `-name` option refers to a release name and not a Kubernetes namespace. + The Helm `--name` option refers to a release name and not a Kubernetes namespace. To install a specific version of a single ONAP component (`so` in this example) |