AETHER-2090 Add system applications and bess-upf deployment guide
Change-Id: Ie456057f1a9652c02634221009ee5cebe63d8098
diff --git a/edge_deployment/bess_upf_deployment.rst b/edge_deployment/bess_upf_deployment.rst
new file mode 100644
index 0000000..21adb1e
--- /dev/null
+++ b/edge_deployment/bess_upf_deployment.rst
@@ -0,0 +1,141 @@
+..
+ SPDX-FileCopyrightText: © 2021 Open Networking Foundation <support@opennetworking.org>
+ SPDX-License-Identifier: Apache-2.0
+
+BESS UPF Deployment
+===================
+
+This section describes how to configure and install BESS UPF.
+
+
+Network Plans
+-------------
+
+BESS UPF requires three networks, **enb**, **access**, and **core**, and all
+three networks must use different subnets. To help your understanding,
+the following example ACE environment will be used in the rest of the guide.
+
+.. image:: images/bess-upf-example-network.png
+
++-----------+-----------+------------------------------------+------------+---------------+
+| Network | VLAN | Subnet | Interface | IP address |
++-----------+-----------+------------------------------------+------------+---------------+
+| enb | 2 | 192.168.2.0/24 (gw: 192.168.2.254) | mgmt vlan2 | 192.168.2.254 |
+| | | +------------+---------------+
+| | | | enb | 192.168.2.10 |
++-----------+-----------+------------------------------------+------------+---------------+
+| access | 3 | 192.168.3.0/24 (gw: 192.168.3.254) | mgmt vlan3 | 192.168.3.254 |
+| | | +------------+---------------+
+| | | | upf access | 192.168.3.1 |
++-----------+-----------+------------------------------------+------------+---------------+
+| core | 4 | 192.168.4.0/24 (gw: 192.168.4.254) | mgmt vlan4 | 192.168.4.254 |
+| | | +------------+---------------+
+| | | | upf core | 192.168.4.1 |
++-----------+-----------+------------------------------------+------------+---------------+
+
+.. note::
+
+ Management plane and out-of-band network are not depicted in the diagram.
+
+
+Note that the management server has the only external routable address and acts as a router for
+all networks in the Aether pod.
+So in order for UE to access the Internet, two things need to be done in the managmenet server.
+
+* Masquerade UE pool with the external address of the management server.
+* For the response traffic to be delivered to UE, forward them to UPF's **core** interface.
+
+
+Check Cluster Resources
+-----------------------
+
+Before proceeding with the deployment, make sure the cluster has enough resources to run BESS UPF.
+
+* 2 dedicated cores (``"cpu"``)
+* 2 1Gi HugePages (``"hugepages-1Gi"``)
+* 2 SRIOV Virtual Functions bound to **vfio-pci** driver (``"intel.com/intel_sriov_vfio"``)
+
+In fact, these requirements are not mandatory to run BESS UPF, but are recommended for best performance.
+You can use the following command to check allocatable resources in the cluster nodes.
+
+.. code-block:: shell
+
+ $ kubectl get nodes -o json | jq '.items[].status.available'
+ {
+ "cpu": "95",
+ "ephemeral-storage": "1770223432846",
+ "hugepages-1Gi": "32Gi",
+ "intel.com/intel_sriov_netdevice": "32",
+ "intel.com/intel_sriov_vfio": "32",
+ "memory": "360749956Ki",
+ "pods": "110"
+ }
+
+
+Configure BESS UPF
+------------------
+
+Download ``aether-app-configs`` if you don't have it already in your development machine.
+
+.. code-block:: shell
+
+ $ cd $WORKDIR
+ $ git clone "ssh://[username]@gerrit.opencord.org:29418/aether-app-configs"
+
+Move the directory to ``apps/bess-upf`` and create Helm values file for the new cluster.
+The configuration below is for the example environment.
+Don't forget to replace the IP addresses in the example configuration with the addresses of the actual cluster.
+
+.. code-block:: shell
+
+ $ cd $WORKDIR/aether-app-configs/apps/bess-upf/upf1
+ $ mkdir overlays/prd-ace-test
+ $ vi overlays/prd-ace-test/values.yaml
+ # SPDX-FileCopyrightText: 2020-present Open Networking Foundation <info@opennetworking.org>
+
+ config:
+ upf:
+ enb:
+ subnet: "192.168.2.0/24"
+ access:
+ ip: "192.168.3.1/24"
+ gateway: "192.168.3.254"
+ core:
+ ip: "192.168.4.1/24"
+ gateway: "192.168.4.254"
+ # Below is required only when connecting to 5G core
+ cfgFiles:
+ upf.json:
+ cpiface:
+ dnn: "8internet"
+ hostname: "upf"
+
+
+Update ``fleet.yaml`` in the same directory to let Fleet know the custom configuration.
+
+.. code-block:: shell
+
+ $ vi fleet.yaml
+ # add following block at the end
+ - name: prd-ace-test
+ clusterSelector:
+ matchLabels:
+ management.cattle.io/cluster-display-name: ace-test
+ helm:
+ valuesFiles:
+ - overlays/prd-ace-test/values.yaml
+
+
+Commit your changes.
+
+.. code-block:: shell
+
+ $ cd $WORKDIR/aether-app-configs
+ $ git status
+ $ git add .
+ $ git commit -m "Add BESS UPF configs for test ACE"
+ $ git review
+
+
+Go to Fleet dashboard and wait until the cluster status becomes **Active**.
+Note that it can take up to 1 min for Fleet to fetch the configuration updates.