# KNF Onboarding Walkthrough (Work in Progress)

**NOTE: this section uses pre-SOL006 descriptors which need to be converted before trying in Release 9+**

## Introduction

This section uses Facebook's Magma, an open-source software platform that gives network operators an open, flexible and extendable mobile core network solution.

![](assets/magma_overview.png)

This example focuses on deploying the Magma Orchestrator component as a KNF, and then integrating it with a Magma AGW deployed as a VNF. It has been documented in a concise way while content keeps being added as K8s support is enhanced in OSM.

Final packages used throughout this example can be found [here](https://osm-download.etsi.org/ftp/Packages/vnf-onboarding-tf/)

## KNF Requirements

A Helm Chart or Juju Bundle contains already all the characteristics of a Kubernetes Network Function in OSM. It just needs OSM to be connected to a Kubernetes Cluster to run on top.

The Helm Chart in which this KNF is based, has been contributed for OSM [here](https://felipevicens.github.io/fb-magma-helm-chart/)

## Building the KNF Descriptor

With the Helm Chart available, the following KNFD can be built. Put the following contents in a YAML file using the following structure:

```
fb_magma_knf
   |
   --- fb_magma_knfd.yaml
```

The descriptor contents would be:

```
vnfd-catalog:
    schema-version: '3.0'
    vnfd:
    -   connection-point:
        -   name: mgmt
        description: KNF with KDU using a helm-chart for Facebook magma orc8r
        id: fb_magma_knf
        k8s-cluster:
            nets:
            -   external-connection-point-ref: mgmt
                id: mgmtnet
        kdu:
        -   helm-chart: magma/orc8r
            name: orc8r
        mgmt-interface:
            cp: mgmt
        name: fb_magma_knf
        short-name: fb_magma_knf
        version: '1.0'
```

The main modelling is under the "kdu" list. The rest of elements are either descriptive or not connected to a specific feature at this point.

Package your VNF:

```
tar -cvzf fb_magma_knf.tar.gz fb_magma_knf/
```

## Launching the KNF Package

To launch the KNF package, you need to first add the repository that contains the Helm chart.

```
osm repo-add --type helm-chart --description "Repository for Facebook Magma helm Chart" magma https://felipevicens.github.io/fb-magma-helm-chart/
```

Now, include the KNF into a NS Package, let's create one through a YAML file under the following structure.

```
fb_magma_ns
   |
   --- fb_magma_nsd.yaml
```

The descriptor contents would be:

```
nsd-catalog:
    nsd:
    -   constituent-vnfd:
        -   member-vnf-index: orc8r
            vnfd-id-ref: fb_magma_knf
        description: NS consisting of a KNF fb_magma_knf connected to mgmt network
        id: fb_magma_ns
        name: fb_magma_ns
        short-name: fb_magma_ns
        version: '1.0'
        vld:
        -   id: mgmtnet
            mgmt-network: true
            name: mgmtnet
            type: ELAN
            vim-network-name: mgmt
            vnfd-connection-point-ref:
            -   member-vnf-index-ref: orc8r
                vnfd-connection-point-ref: mgmt
                vnfd-id-ref: fb_magma_knf
```

The main modelling is under the "constituent-vnfd" list. The rest of elements are either descriptive or not connected to a specific feature at this point.

Package your NS:

```
tar -cvzf fb_magma_ns.tar.gz fb_magma_ns/
```

With both packages ready, upload them to OSM:

```
osm nfpkg-create fb_magma_knf.tar.gz
osm nspkg-create fb_magma_ns.tar.gz
```

And finally the package can be tested over any given K8s Cluster registed to OSM. For details on how to register a K8s Cluster, visit the [user guide](https://osm.etsi.org/docs/user-guide/05-osm-usage.html#using-kubernetes-based-vnfs-knfs)

```
osm ns-create --ns_name magma_orc8r --nsd_name fb_magma_ns --vim_account <vim_name>
```

Please note that this KNF will need three to four external IPs, which should be available by having previously integrated MetalLB or similar mechanism to your K8 Cluster. If these IPs are not available, the deployment will fail.

## Testing the KNF Package

Monitor with osm ns-list until instantiation is finished, then, execute the following command to check the status of your KDU

```
osm vnf-show <vnf-id> --kdu orc8r
```

Under the services list, you will find all the deployed components and status. Look for your "load balancer" IP addresses for the `nginx-proxy` component (172.21.250.4 in the example below), as it will be used to access this KNF's dashboard.

```
==> v1/Service
NAME                       TYPE           CLUSTER-IP      EXTERNAL-IP    PORT(S)         AGE
bootstrapper-orc8r-proxy   LoadBalancer   10.233.44.125   172.21.250.5   443:30586/TCP   58s
...
nginx-proxy   LoadBalancer   10.233.4.76   172.21.250.4   443:31742/TCP   58s
orc8r-clientcert-legacy   LoadBalancer   10.233.50.131   172.21.250.6   443:30688/TCP   58s
orc8r-configmanager   ClusterIP   10.233.19.191   <none>   9100/TCP,9101/TCP   58s
orc8r-controller   ClusterIP   10.233.22.92   <none>   8080/
...
```

An extra step when your KNF is ready, is to run this command that creates a user for the Magma Orc8r NMS to connect to the Magma Orc8r Controller.
This one has to be executed manually while Day-1/2 primitives are not supported in KNFs:

```
kubectl exec -it -n YOUR_NAMESPACE $(kubectl get pod -n YOUR_NAMESPACE -l app.kubernetes.io/component=controller -o jsonpath="{.items[0].metadata.name}") -- /var/opt/magma/bin/accessc add-existing -admin -cert /var/opt/magma/certs/admin_operator.pem admin_operator
```

Don't forget to replace `YOUR_NAMESPACE` with the namespace where Magma Orc8r was deployed.

Visit the dashboard with HTTPS and access it with user `admin@magma.test` (password: password1234)

![](assets/magma_orc8r_dashboard.png)

## Testing functionality

We have prepared a modified Magma AGW, which is the distributed Packet Core component which runs in a single VM, in order to test it together with its Orchestrator (Orc8r KNF)

You can download the image from [here](https://osm-download.etsi.org/ftp/images/vnf-onboarding-tf/magma101.qcow2.gz). Please "gunzip" it before uploading it to your VIM.

Note: this is a v1.0.1 image built following [Magma AGW installation instructions](https://facebookincubator.github.io/magma/docs/lte/setup_deb), but incorporates extra tools prepared by us, that can communicate with the Orc8r API for self-registering the AGW. These scripts are located in `/home/magma`, and have been built to simplify the Day-1 primitives.

Steps for testing are:

a) Download the Magma AGW 1.0.1 VNF Packages and upload them to OSM

```
wget https://osm-download.etsi.org/ftp/Packages/vnf-onboarding-tf/magma-agw_vnfd.tar.gz
wget https://osm-download.etsi.org/ftp/Packages/vnf-onboarding-tf/magma-agw_nsd.tar.gz
osm nfpkg-create magma-agw_vnfd.tar.gz
osm nspkg-create magma-agw_nsd.tar.gz
```

You may need to change the `vim-network-name` corresponding to the management network, from `osm-ext` to a network that matches your environment.

b) Prepare a ‘params.yaml’ file with instantiation-time parameters to self register the AGW to your Orchestrator. Populate it with your preferred values, except for the Orc8r IP address, which should match the orc8r_proxy exposed service.

```
additionalParamsForVnf:
-  member-vnf-index: '1'
   additionalParams:
     agw_id: 'agw_01'
     agw_name: 'AGW01'
     orch_ip: '172.21.250.10'  ## change this to the MetalLB IP address of your orc8r_proxy service.
     orch_net: 'osmnet'
```

c) Launch the AGW.

```
osm ns-create --ns_name agw01 --nsd_name magma-agw_nsd --vim_account <vim_account> --config_file params.yaml
```

d) Monitor the OSM proxy charms, they take care of auto-registering the AGW with the Orchestrator.

```
juju switch <ns_id>
juju status
```

As mentioned before, the charms run some scripts included in this image, which in this particular example, will: (1) Reset the AGW hardware ID, so that you can deploy multiple AGWs with the same image, (2) Configure a "LTE Network" in the Orc8r (if it exists because you want more than one AGW in the same network, it won't do anything), (3) Register itself at the Orc8r, (4) Add testing domains of the Orc8r to /etc/hosts so that the AGW can reach it by name, (5) Restart the Magma services, so the AGW tries to activate its registration.

e) When finished, the Magma Orchestrator dashboard will show the registered AGW01. You are ready to integrate some eNodeBs! (emulators to be provided soon!)

![](assets/magma_orc8r_dashboard_agw.png)
