Enhance documentation
Change-Id: I4e5cff50e32f7fd47c7d6533f14502147d1001f3
Signed-off-by: wrider <lji@research.att.com>
diff --git a/docs/installation-guides.rst b/docs/installation-guides.rst
index 05231f5..cfd0b1f 100644
--- a/docs/installation-guides.rst
+++ b/docs/installation-guides.rst
@@ -19,109 +19,94 @@
:depth: 3
:local:
-========
-Abstract
-========
+===================
+Installation Guides
+===================
-This document describes how to install <Component>, it's dependencies and required system resources.
+This document describes how to install the components deployed by scripts and Helm charts
+under the it/dep repository, it's dependencies and required system resources.
.. contents::
:depth: 3
:local:
Version history
----------------------
+===============
+--------------------+--------------------+--------------------+--------------------+
| **Date** | **Ver.** | **Author** | **Comment** |
| | | | |
+--------------------+--------------------+--------------------+--------------------+
-| 20XX-XX-XX | 0.1.0 | | First draft |
-| | | | |
-+--------------------+--------------------+--------------------+--------------------+
-| | 0.1.1 | | |
-| | | | |
-+--------------------+--------------------+--------------------+--------------------+
-| | 1.0 | | |
-| | | | |
+| 2019-11-25 | 0.1.0 |Lusheng Ji | First draft |
| | | | |
+--------------------+--------------------+--------------------+--------------------+
-Introduction
-============
-.. <INTRODUCTION TO THE SCOPE AND INTENTION OF THIS DOCUMENT AS WELL AS TO THE SYSTEM TO BE INSTALLED>
+Overview
+========
-.<EXAMPLE>:
+The installation of Amber Near Realtime RAN Intelligent Controller is spread onto two separate
+Kubernetes clusters. The first cluster is used for deploying the Near Realtime RIC (platform and
+applications), and the other is for deploying other auxiliary functions. They are referred to as
+RIC cluster and AUX cluster respectively.
-This document describes the supported software and hardware configurations for the reference component as well as providing guidelines on how to install and configure such reference system.
+The following diagram depicts the installation architecture.
-The audience of this document is assumed to have good knowledge in RAN network nd Linux system.
+.. image:: images/nrtric-amber.png
+ :width: 600
+
+Within the RIC cluster, Kubernetes resources are deployed using three name spaces: ricinfra, ricplt, and ricxapp. Similarly, within the AUX cluster, Kubernetes resources are deployed using two name spaces: ricinfra, and ricaux.
+
+For each cluster, there is a Kong ingress controller that proxies incoming API calls into the cluster.
+With Kong, service APIs provided by Kubernetes resources can be accessed at the cluster node IP and
+port via a URL path. For cross-cluster communication, in addition to Kong, each Kubernetes namespace
+has a special Kubernetes service defined with endpoint pointing to the other cluster's Kong. This
+way any pod can access services exposed at the other cluster via the internal service hostname and port of
+this special service. The figure below illustrates the details of how Kong and external services work
+together to realize cross-cluster communication.
+
+.. image:: images/kong-extservice.png
+ :width: 600
-Preface
-=======
-.. <DESCRIBE NEEDED PREREQUISITES, PLANNING, ETC.>
+VirtualBox VMs as Installation Hosts
+=======================================
-<EXAMPLE>:
+The deployment of Amber Near Realtime RIC can be done on a wide range of hosts, including
+bare metal servers, OpenStack VMs, and VirtualBox VMs. This section provides detailed instructions
+for setting up Oracle VirtualBox VMs to be used as installation hosts.
-Before starting the installation of <project name>, some planning must preceed.
-
-.. note:any preperation you need before setting up sotfware and hardware
-
-
-Hardware requirements
-=====================
-.. <PROVIDE A LIST OF MINIMUM HARDWARE REQUIREMENTS NEEDED FOR THE INSTALL>
-
-<EXAMPLE>:
-
-Following minimum hardware requirements must be met for installation of <project name>:
-
-+--------------------+----------------------------------------------------+
-| **HW Aspect** | **Requirement** |
-| | |
-+--------------------+----------------------------------------------------+
-| **# of servers** | |
-+--------------------+----------------------------------------------------+
-| **CPU** | |
-| | |
-+--------------------+----------------------------------------------------+
-| **RAM** | |
-| | |
-+--------------------+----------------------------------------------------+
-| **Disk** | |
-| | |
-+--------------------+----------------------------------------------------+
-| **NICs** | |
-| | |
-| | |
-| | |
-| | |
-| | |
-+--------------------+----------------------------------------------------+
+.. include:: ./installation-virtualbox.rst
+One-Node Kubernetes Cluster
+============================
+
+This sectioin descriibes how to set up a one-node Kubernetes cluster onto a VM installation host.
+
+.. include:: ./installation-k8s1node.rst
-Software installation and deployment
-==========================================
-.. <DESCRIBE THE FULL PROCEDURES FOR THE INSTALLATION OF THE O-RAN COMPONENT INSTALLATION AND DEPLOYMENT>
+Installing Near Realtime RIC in RIC Cluster
+===========================================
-<EXAMPLE>:
+After the Kubernetes cluster is installed, teh next step is to install the (Near Realtime) RIC Platform.
-This section describes the installation of the <project name> installation on the reference hardware.
+.. include:: ./installation-ric.rst
+Installing Auxiliary Functions in AUX Cluster
+=============================================
-References
-==========
-.. <PROVIDE NEEDED/USEFUL REFERENCES>
+.. include:: ./installation-aux.rst
-<EXAMPLES>:
-OpenStack
-^^^^^^^^^^^
+Installing RIC Applications
+===========================================
+
+.. include:: ./installation-xapps.rst
+
+