.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. ===============LICENSE_START=======================================================
-.. Copyright (C) 2019 AT&T Intellectual Property
+.. 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
+.. 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
..
.. http://creativecommons.org/licenses/by/4.0
.. limitations under the License.
.. ===============LICENSE_END=========================================================
-Installing Near Realtime RIC in RIC Cluster
-===========================================
-
Getting and Preparing Deployment Scripts
----------------------------------------
Edit the recipe files RIC_INFRA_RECIPE_EXAMPLE and RIC_PLATFORM_RECIPE_EXAMPLE. In particular the following values often need adaptation to local deployments:
-1. Docker registry URL;
-2. Docker registry credential;
-3. Helm repo credential;
-4. Component docker container image tags.
+#. Docker registry URL;
+#. Docker registry credential;
+#. Helm repo credential;
+#. Component docker container image tags.
Deploying the Infrastructure and Platform Groups
------------------------------------------------
-After the recipes are edited, the Near Realtime RIIC is ready to be deployed.
+After the recipes are edited, the Near Realtime RIC is ready to be deployed.
.. code:: bash
cd dep/bin
./deploy-ric-infra ../RECIPE_EXAMPLE/RIC_INFRA_RECIPE_EXAMPLE
- ./deploy-ric-platform ../RECIPE_EXAMPLE/RIC_PLATFORM_RECIPE_EXAMPLE
+ ./deploy-ric-platform ../RECIPE_EXAMPLE/RIC_PLATFORM_RECIPE_EXAMPLE
Checking the Deployment Status
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. ===============LICENSE_START=======================================================
-.. Copyright (C) 2019 AT&T Intellectual Property
+.. 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
+.. 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
..
.. http://creativecommons.org/licenses/by/4.0
.. limitations under the License.
.. ===============LICENSE_END=========================================================
-.. contents::
- :depth: 3
- :local:
-
===================
Installation Guides
===================
-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.
+This document describes how to install the RIC components deployed by scripts and Helm charts
+under the it/dep repository, including the dependencies and required system resources.
.. contents::
:depth: 3
Overview
========
-The installation of Amber Near Realtime RAN Intelligent Controller is spread onto two separate
+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.
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
+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.
VirtualBox VMs as Installation Hosts
-=======================================
+====================================
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
.. 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.
+This section describes how to set up a one-node Kubernetes cluster onto a VM installation host.
.. include:: ./installation-k8s1node.rst
Installing Near Realtime RIC in RIC Cluster
===========================================
-After the Kubernetes cluster is installed, teh next step is to install the (Near Realtime) RIC Platform.
+After the Kubernetes cluster is installed, the next step is to install the (Near Realtime) RIC Platform.
-.. include:: ./installation-ric.rst
+.. include:: ./installation-ric.rst
Installing Auxiliary Functions in AUX Cluster
Installing RIC Applications
-===========================================
+===========================
.. include:: ./installation-xapps.rst
-
-
-
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. ===============LICENSE_START=======================================================
-.. Copyright (C) 2019 AT&T Intellectual Property
+.. 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
+.. 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
..
.. http://creativecommons.org/licenses/by/4.0
cd bin
./gen-cloud-init.sh
-A file named **k8s-1node-cloud-init.sh** would now appear under the bin directory.
+A file named **k8s-1node-cloud-init.sh** would now appear under the bin directory.
Setting up Kubernetes Cluster
-----------------------------
-The new **k8s-1node-cloud-init.sh** file is now ready for setting up the Kubernetes cluster.
+The new **k8s-1node-cloud-init.sh** file is now ready for setting up the Kubernetes cluster.
It can be run from a root shell of an existing Ubuntu 16.04 or 18.04 VM. Running this script will replace any existing installation of Docker host, Kubernetes, and Helm on the VM.
It can also be used as the user-data (a.k.a. cloud-init script) supplicated to Open Stack when launching a new Ubuntu 16.04 or 18.04 VM.
-Upon successful execution of the script, when integrated by the kubectl command, the VM should display information similar to below:
+Upon successful execution of the script, when integrated by the kubectl command, the VM should display information similar to below:
::
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. ===============LICENSE_START=======================================================
-.. Copyright (C) 2019 AT&T Intellectual Property
+.. 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
+.. 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
..
.. http://creativecommons.org/licenses/by/4.0
Edit the recipe files RIC_INFRA_RECIPE_EXAMPLE and RIC_PLATFORM_RECIPE_EXAMPLE. In particular the following values often need adaptation to local deployments:
-1. Docker registry URL;
-2. Docker registry credential;
-3. Helm repo credential;
-4. Component docker container image tags.
+#. Docker registry URL;
+#. Docker registry credential;
+#. Helm repo credential;
+#. Component docker container image tags.
Deploying the Infrastructure and Platform Groups
cd dep/bin
./deploy-ric-infra ../RECIPE_EXAMPLE/RIC_INFRA_RECIPE_EXAMPLE
- ./deploy-ric-platform ../RECIPE_EXAMPLE/RIC_PLATFORM_RECIPE_EXAMPLE
+ ./deploy-ric-platform ../RECIPE_EXAMPLE/RIC_PLATFORM_RECIPE_EXAMPLE
Checking the Deployment Status
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. ===============LICENSE_START=======================================================
-.. Copyright (C) 2019 AT&T Intellectual Property
+.. 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
+.. 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
..
.. http://creativecommons.org/licenses/by/4.0
Networking
----------
-The set up requires two VMs connected by a private network. With VirtualBox, this can be done by going under its "Preferences" menu and set up a private NAT network.
+The set up requires two VMs connected by a private network. With VirtualBox, this can be
+done by going under its "Preferences" menu and setting up a private NAT network.
-1. "Preference", then select the "Network" tab;
-2. Clicking on the "+" icon to create a new NAT network. A new entry will appear in the NAT networks list;
-3. Double clicking on the new network to edit its details, including giving int a name such as "RICNetwork";
-4. On the next page, make sure to check: "Enable Network", uncheck the "Supports DHCP" box, and make a note of the "Network CIDR" (for this example, it is 10.0.2.0/24);
-5. Click on the "Port Forwarding" button to create the following rules:
+#. "Preference", then select the "Network" tab;
+#. Click on the "+" icon to create a new NAT network. A new entry will appear in the NAT networks list
+#. Double click on the new network to edit its details; give it a name such as "RICNetwork"
+#. On the next page, make sure to check: "Enable Network", uncheck the "Supports DHCP" box, and make a note of the "Network CIDR" (for this example, it is 10.0.2.0/24);
+#. Click on the "Port Forwarding" button to create the following rules:
- 1. "ssh to ric", TCP, 127.0.0.1, 22222, 10.0.2.100, 22;
- 2. "ssh to aux", TCP, 127.0.0.1, 22223, 10.0.2.101, 22;
- 3. "entry to ric", TCP, 127.0.0.1, 22224, 10.0.2.100, 32080;
- 4. "entry to aux", TCP, 127.0.0.1, 22225, 10.0.2.101, 32080.
+ #. "ssh to ric", TCP, 127.0.0.1, 22222, 10.0.2.100, 22;
+ #. "ssh to aux", TCP, 127.0.0.1, 22223, 10.0.2.101, 22;
+ #. "entry to ric", TCP, 127.0.0.1, 22224, 10.0.2.100, 32080;
+ #. "entry to aux", TCP, 127.0.0.1, 22225, 10.0.2.101, 32080.
-6. "Ok" all the way back to create the network.
+#. "Ok" all the way back to create the network.
Creating VMs
--------------
+------------
Create a VirtualBox VM:
-1. "New", then enter the following in the pop-up: Name it for example **myric**, of "Linux" type, and at least 4G RAM and 10G disk;
-2. "Create" to create the VM. It will appear in the list of VMs.
-3. Highlight the new VM entry, right click on it, select "Settings".
+#. "New", then enter the following in the pop-up: Name it for example **myric**, of "Linux" type, and at least 4G RAM and 10G disk;
+#. "Create" to create the VM. It will appear in the list of VMs.
+#. Highlight the new VM entry, right click on it, select "Settings".
- 1. Under the "System" tab, then "Processor" tab, make sure to give the VM at least 2 vCPUs.
- 2. Under the "Storage" tab, point the CD to a Ubuntu 18.04 server ISO file;
- 3. Under the "Network" tab, then "Adapter 1" tab, make sure to:
+ #. Under the "System" tab, then "Processor" tab, make sure to give the VM at least 2 vCPUs.
+ #. Under the "Storage" tab, point the CD to a Ubuntu 18.04 server ISO file;
+ #. Under the "Network" tab, then "Adapter 1" tab, make sure to:
- 1. Check "Enable Network Adapter";
- 2. Attached to "NAT Network";
- 3. Network name for what was created in the previous section: "RICNetwork".
+ #. Check "Enable Network Adapter";
+ #. Attached to "NAT Network";
+ #. Network name for what was created in the previous section: "RICNetwork".
Repeat the process and create the second VM named **myaux**.
Booting VM and OS Installation
------------------------------
-Follow the OS installation steps to install OS to the VM virtual disk media. Make sure to install openssh server.
+Follow the OS installation steps to install OS to the VM virtual disk media. Make sure to install openssh server.
VM Network Configuration
--------------------------
+------------------------
-Depending on the version of the OS, the networking may be configured during the OS installation or after. The network interface is configured with static IP address:
+Depending on the version of the OS, the networking may be configured during the OS installation or after.
+The network interface is configured with a static IP address:
- IP Address: 10.0.2.100 for myric or 10.0.2.101 for myaux;
- Network: 10.0.2.10/24, or network mask 255.255.255.0
- Name server: 8.8.8.8
-Accessing the VMs
+Accessing the VMs
-----------------
-Because of the port forwarding configurations, the VMs are accessible from the VirtualBox host via ssh.
+Because of the port forwarding configurations, the VMs are accessible from the VirtualBox host via ssh.
- To access **myric**: ssh {{USERNAME}}@127.0.0.1 -p 22222
- To access **myaux**: ssh {{USERNAME}}@127.0.0.1 -p 22223
-
-
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. ===============LICENSE_START=======================================================
-.. Copyright (C) 2019 AT&T Intellectual Property
+.. 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
+.. 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
..
.. http://creativecommons.org/licenses/by/4.0
.. limitations under the License.
.. ===============LICENSE_END=========================================================
-Running the Near Realtime RIC
-==================================================================
-
Loading xApp Helm Charts
---------------------------
+------------------------
+
+The RIC Platform App Manager deploys RIC applications (a.k.a. xApps) using Helm charts stored in a private Helm repo.
+In the dev testing deployment described in this documentation, this private Helm repo is the Chart Museum pod that is deployed within the ric infrastructure group into the RIC cluster.
-The RIC Platform App Manager deploys RIC applications (a.k.a. xApps) using Helm charts stored in a private Helm repo. In the dev testing deployment described in this documentation, this private Helm repo is the Chart Museum pod that is deployed within the ric infrastructure group into the RIC cluster.
+The Helm repo location and credential for access the repo are specified in both the infrastructure and platform recipe files.
-The Helm repo location and credential for access the repo are specified in both the infrastructure and platform recipe files.
+Before any xApp can be deployed, its Helm chart must be loaded into this private Helm repo before the App manager can deploy them.
+The example below show a command sequence that completes:
-Before any xApp can be deployed, its Helm chart must be loaded into this private Helm repo before the App manager can deploy them. The example below show a command sequence that completes:
-1. Add the Helm repo at the Helm client running on the RIC cluster host VM (via Kong Ingress Controller);
-2. Load the xApp Helm chart into the Helm repo;
-3. Update the local cache for the Helm repo and check the Helm chart is loaded;
-4. Calling App Manager to deploy the xApp;
-5. Calling App Manager to delete the xApp;
-6. Delete the xApp helm chart from the private Helm repo.
+#. Add the Helm repo at the Helm client running on the RIC cluster host VM (via Kong Ingress Controller);
+#. Load the xApp Helm chart into the Helm repo;
+#. Update the local cache for the Helm repo and check the Helm chart is loaded;
+#. Calling App Manager to deploy the xApp;
+#. Calling App Manager to delete the xApp;
+#. Delete the xApp helm chart from the private Helm repo.
.. code:: bash
curl -L -u helm:helm --data-binary "@admin-xapp-1.0.7.tgz" \
http://10.0.2.100:32080/helm/api/charts
- # check the local cache of repo cm
+ # check the local cache of repo cm
helm repo update cm
# verify that the Helm chart is loaded and accessible
helm search cm/
# to delete a chart
curl -L -X DELETE -u helm:helm http://10.0.2.100:32080/api/charts/admin-xapp/0.0.5
-For more xApp deployment and usage examples, please see documentations for the it/test repositooory.
-
-
+For more xApp deployment and usage examples, please see the documentation for the it/test repository.
Code Review / it / dep.git / commitdiff