.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
-.. ===============LICENSE_START=======================================================
+.. ---------------LICENSE_START-------------------------------------------------------
.. Copyright (C) 2019-2020 AT&T Intellectual Property
-.. ===================================================================================
+.. -----------------------------------------------------------------------------------
.. This documentation file is distributed under the Creative Commons Attribution
.. 4.0 International License (the "License"); you may not use this file except in
.. compliance with the License. You may obtain a copy of the License at
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.
-.. ===============LICENSE_END=========================================================
-
-
-Getting and Preparing Deployment Scripts
-----------------------------------------
-
-Clone the it/dep git repository that has deployment scripts and support files on the target VM.
-(You might have already done this in a previous step.)
-
-::
-
- % git clone https://gerrit.o-ran-sc.org/r/it/dep
-
-Check out the appropriate branch of the repository with the release you want to deploy.
-For example:
-
-::
+.. ---------------LICENSE_END---------------------------------------------------------
- % git checkout Amber
-In the RECIPE_EXAMPLE directory, edit the recipe files RIC_INFRA_RECIPE_EXAMPLE and
-RIC_PLATFORM_RECIPE_EXAMPLE. In particular the following values often need adaptation
-to local deployments:
-
-#. Docker registry URL (property "repository"). This is the default source for
- container images. For example,
- nexus3.o-ran-sc.org:10004/o-ran-sc is the staging registry and has freshly built images;
- nexus3.o-ran-sc.org:10002/o-ran-sc is the release registry and has stable images.
-#. Docker registry credential. This is a name of a Kubernetes credential. Some registries
- allow anonymous read access, including nexus3.o-ran-sc.org.
-#. Helm repo and credential. The xApp Manager deploys xApps from charts in this repo.
- No changes are required here for basic dev testing of platform components.
-#. Component docker container image repository override and tag. The recipes specify
- the docker image to use in terms of name and tag. These entries also allow override
- of the default docker registry URL (see above); for example, the default might be the
- releases registry and then a component under test is deployed from the staging registry.
-
-
-Deploying the Infrastructure and Platform Groups
-------------------------------------------------
-
-After the recipes are edited, the Near Realtime RIC is ready to be deployed.
-Perform the following steps in a root shell.
-
-.. code:: bash
-
- % sudo -i
- # cd dep/bin
- # ./deploy-ric-infra ../RECIPE_EXAMPLE/RIC_INFRA_RECIPE_EXAMPLE
- # ./deploy-ric-platform ../RECIPE_EXAMPLE/RIC_PLATFORM_RECIPE_EXAMPLE
-
-
-Checking the Deployment Status
-------------------------------
+Installing Near-realtime RIC
+============================
-Now check the deployment status after a short wait. Results similar to the
-output shown below indicate a complete and successful deployment. Check the
-STATUS column from both kubectl outputs to ensure that all are either
-"Completed" or "Running", and that none are "Error" or "ImagePullBackOff".
-
-.. code::
-
- # helm list
- NAME REVISION UPDATED STATUS CHART APP VERSION NAMESPACE
- r1-a1mediator 1 Tue Nov 26 00:47:12 2019 DEPLOYED a1mediator-2.0.0 1.0 ricplt
- r1-appmgr 1 Tue Nov 26 00:47:09 2019 DEPLOYED appmgr-1.1.0 1.0 ricplt
- r1-chartmuseum 1 Tue Nov 26 03:16:42 2019 DEPLOYED chartmuseum-0.0.1 0.1 ricinfra
- r1-dbaas1 1 Tue Nov 26 00:47:10 2019 DEPLOYED dbaas1-1.1.0 1.0 ricplt
- r1-e2mgr 1 Tue Nov 26 00:47:10 2019 DEPLOYED e2mgr-1.1.0 1.0 ricplt
- r1-e2term 1 Tue Nov 26 00:47:11 2019 DEPLOYED e2term-1.1.0 1.0 ricplt
- r1-extsvcplt 1 Tue Nov 26 00:47:17 2019 DEPLOYED extsvcplt-0.2.0 1.0 ricplt
- r1-jaegeradapter 1 Tue Nov 26 00:47:16 2019 DEPLOYED jaegeradapter-0.1.0 1.0 ricplt
- r1-kong 1 Tue Nov 26 00:45:36 2019 DEPLOYED kong-1.0.0 1.0 ricinfra
- r1-ricaux-credential 1 Tue Nov 26 00:45:42 2019 DEPLOYED credential-1.1.0 1.0 ricaux
- r1-ricinfra-credential 1 Tue Nov 26 00:45:43 2019 DEPLOYED credential-1.1.0 1.0 ricinfra
- r1-ricplt-credential 1 Tue Nov 26 00:45:42 2019 DEPLOYED credential-1.1.0 1.0 ricplt
- r1-ricxapp-credential 1 Tue Nov 26 00:45:42 2019 DEPLOYED credential-1.1.0 1.0 ricxapp
- r1-rsm 1 Tue Nov 26 00:47:15 2019 DEPLOYED rsm-2.0.6 1.0 ricplt
- r1-rtmgr 1 Tue Nov 26 00:47:09 2019 DEPLOYED rtmgr-1.1.0 1.0 ricplt
- r1-submgr 1 Tue Nov 26 00:47:13 2019 DEPLOYED submgr-1.1.0 1.0 ricplt
- r1-vespamgr 1 Tue Nov 26 00:47:14 2019 DEPLOYED vespamgr-0.0.1 1.0 ricplt
- r1-xapp-tiller 1 Tue Nov 26 00:45:44 2019 DEPLOYED xapp-tiller-0.1.0 1.0 ricinfra
-
- # kubectl get pods -n ricinfra
- NAME READY STATUS RESTARTS AGE
- deployment-ricinfra-chartmuseum-7d97f4b995-gkxsq 1/1 Running 0 133m
- deployment-tiller-ricxapp-65f9cbc8d7-qcr5t 1/1 Running 0 133m
- job-ricinfra-chartmuseum-save-certs-5ntnk 0/1 Completed 0 133m
- r1-kong-kong-84695ff65d-9sjwg 2/2 Running 2 133m
- tiller-secret-generator-w6bnd 0/1 Completed 0 133m
-
- # kubectl get pods -n ricplt
- NAME READY STATUS RESTARTS AGE
- deployment-ricplt-a1mediator-5c4df477f9-6zxxx 1/1 Running 0 132m
- deployment-ricplt-appmgr-65bc8b958c-tggg7 1/1 Running 0 132m
- deployment-ricplt-dbaas-74bf584449-k484v 1/1 Running 0 132m
- deployment-ricplt-e2mgr-74cd9865bc-hpn6b 1/1 Running 0 132m
- deployment-ricplt-e2term-cc7b5d99-pkctr 1/1 Running 0 132m
- deployment-ricplt-jaegeradapter-cc49c64dc-vj622 1/1 Running 0 131m
- deployment-ricplt-rsm-599cd4d6c8-4jhft 1/1 Running 0 131m
- deployment-ricplt-rtmgr-85d89868d6-58wvl 1/1 Running 1 132m
- deployment-ricplt-submgr-7cbd697c7f-p9x4x 1/1 Running 0 132m
- deployment-ricplt-vespamgr-7bb4c7585f-9z6qm 1/1 Running 0 132m
-
-
-Checking Container Health
--------------------------
-
-Check the health of the application manager platform component by querying it
-via the ingress controller using the following command.
-
-.. code:: bash
-
- % curl -v http://localhost:32080/appmgr/ric/v1/health/ready
-
-The output should look as follows.
-
-.. code::
-
- * Trying 10.0.2.100...
- * TCP_NODELAY set
- * Connected to 10.0.2.100 (10.0.2.100) port 32080 (#0)
- > GET /appmgr/ric/v1/health/ready HTTP/1.1
- > Host: 10.0.2.100:32080
- > User-Agent: curl/7.58.0
- > Accept: */*
- >
- < HTTP/1.1 200 OK
- < Content-Type: application/json
- < Content-Length: 0
- < Connection: keep-alive
- < Date: Wed, 22 Jan 2020 20:55:39 GMT
- < X-Kong-Upstream-Latency: 0
- < X-Kong-Proxy-Latency: 2
- < Via: kong/1.3.1
- <
- * Connection #0 to host 10.0.2.100 left intact
-
-
-Undeploying the Infrastructure and Platform Groups
---------------------------------------------------
-
-To undeploy all the containers, perform the following steps in a root shell
-within the it-dep repository.
-
-.. code:: bash
-
- # cd bin
- # ./undeploy-ric-platform
- # ./undeploy-ric-infra
-
-Results similar to below indicate a complete and successful cleanup.
-
-.. code::
-
- # ./undeploy-ric-platform
- Undeploying RIC platform components [appmgr rtmgr dbaas1 e2mgr e2term a1mediator submgr vespamgr rsm jaegeradapter]
- release "r1-appmgr" deleted
- release "r1-rtmgr" deleted
- release "r1-dbaas1" deleted
- release "r1-e2mgr" deleted
- release "r1-e2term" deleted
- release "r1-a1mediator" deleted
- release "r1-submgr" deleted
- release "r1-vespamgr" deleted
- release "r1-rsm" deleted
- release "r1-jaegeradapter" deleted
- Undeploying RIC platform components [extsvcplt]
- release "r1-extsvcplt" deleted
-
- # ./undeploy-ric-infra
- Please reset your kubernetes cluster manually.
- Undeploying RIC infra components [chartmuseum]
- release "r1-chartmuseum" deleted
- Undeploying RIC infra components [elfkp]
- Undeploying RIC infra components [kong]
- release "r1-kong" deleted
- Undeploying RIC infra components [credential]
- release "r1-ricaux-credential" deleted
- release "r1-ricinfra-credential" deleted
- release "r1-ricplt-credential" deleted
- release "r1-ricxapp-credential" deleted
- Undeploying RIC infra components [xapp-tiller]
- release "r1-xapp-tiller" deleted
-
-
-Restarting the VM
------------------
-
-After a reboot of the VM, and a suitable delay for initialization,
-all the containers should be running again as shown above.
+The installation of 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.
+
+The following diagram depicts the installation architecture.
+
+.. image:: images/nrtric-amber.png
+ :width: 600
+
+Within the RIC cluster, Kubernetes resources are deployed using three name spaces: ricinfra, ricplt,
+and ricxapp by default. 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 an 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
+
+
+
+Prerequisites
+-------------
+
+Both RIC and AUX clusters need to fulfill the following prerequisites.
+
+- Kubernetes v.1.16.0 or above
+- helm v2.12.3/v3.5.x or above
+- Read-write access to directory /mnt
+
+The following two sections show two example methods to create an environment for installing RIC.
+
+VirtualBox VMs as Installation Hosts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The deployment of 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.
+
+.. include:: ./ric/installation-virtualbox.rst
+
+
+One-Node Kubernetes Cluster
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+This section describes how to set up a one-node Kubernetes cluster onto a VM installation host.
+
+.. include:: ./ric/installation-k8s1node.rst
+
+
+RIC Platform
+-------------------------------------------
+
+After the Kubernetes cluster is installed, the next step is to install the (Near Realtime) RIC Platform.
+
+See instructions in ric-plt/ric-dep: https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-ric-dep/en/latest/installation-guides.html
+
+
+AUX Functionalities (Optional)
+---------------------------------------------
+
+.. include:: ./ric/installation-aux.rst
+
+
+RIC Applications
+---------------------------
+
+See instructions in ric-plt/ric-dep: https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-ric-dep/en/latest/installation-guides.html
Code Review / it / dep.git / blobdiff