07-knfwalkthrough.md

# KNF Onboarding Walkthrough (Work in Progress)

## 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 the Magma Orchestrator component. It has been documented in a concise way while content keeps being added as K8s support is enhanced in OSM. It is meant to be used for educational purposes and not for a real-life implementation of an EPC. 

In addition to the procedure, here you can find some resources related to it:

* [Resulting packages](http://osm-download.etsi.org/ftp/Packages/vnf-onboarding-tf/)
* Images (upcoming)
* Video presentation (upcoming)

## 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 by Felipe Vicens [here](https://felipevicens.github.io/fb-magma-helm-chart/)

## Building the KNF Descriptor

With the Helm Chart ready, 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>
```

## 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/
...
```

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

![](assets/magma_orc8r_dashboard.png)

Stay tuned for the addition of Day-1 primitives in order to auto-configure the Orc8r !

## Testing functionality

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

The image will be provided here soon (TODO: Share Magma 1.0.1 + tools image)

Steps for testing are:

1. Download the Magma AGW 1.0.1 VNF Packages and upload them to OSM

```
wget http://osm-download.etsi.org/ftp/Packages/vnf-onboarding-tf/magma-agw_vnfd.tar.gz 
wget http://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
```

2. 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'
```

3. Launch the AGW. 

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

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

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

5. 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)