..
   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:: yaml

   $ 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:: yaml

   $ 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


Submit 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.