# Quickstarts

This sections uses some of the [OSM Community examples](https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages) to provide quick examples of onboarding and instantiation.

1. [Single VDU Router with Ansible](#router)
1. [Single VDU Virtual Desktop with Native Charms](#desktop)


## Single VDU router with SNMP Metrics and Ansible Playbook <a name="router">

This example implements a VyOS-based virtual machine with routing/firewall functions, packaged with an Ansible Playbook that is applied automatically after instantiation (Day-1 operation), using Helm-based execution environments, which are documented [here](https://osm.etsi.org/docs/vnf-onboarding-guidelines/03-day1.html#creating-helm-based-execution-environments).

### Onboarding

#### Onboarding requirements

- OSM Client installed in linux
- Internet access to clone packages

#### Step 1: Clone the OSM packages to your local machine

If you don't have the OSM Packages folder cloned yet, proceed with cloning it:

```
git clone --recursive https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages
```

#### Step 2: Explore the packages

First, explore the folder `snmp_setcomm_ee_vnf`, in particular, the file `snmp_setcomm_ee_vnfd.yaml`. This is the SOL006-compliant VNF descriptor, which models a single VDU with the specified image (named `vyos-1.1.7` here), three connection-points (internal, external, management), certain computing resources (which you can adapt) and a day-1 primitive named "monitor", specified under the `initial-config-primitive` section, which runs the following primitives:

1. "config" primitive: defines the credentials that the VyOS VM already has (predefined with cloud-init at the `cloud_init/vyos-userdata` file), so it can be configured.
2. "generate_snmp" primitive: activates the SNMP monitoring as explained [here](https://osm.etsi.org/docs/vnf-onboarding-guidelines/04-day2.html#collecting-vnf-indicators)
3. "ansible_playbook" primitive: runs a playbook, in this case named `community.yaml`, which is included in the `helm-charts/eechart/source` folder of the package.

Then, explore the folder `snmp_setcomm_ee_nsd`, in particular, the file `snmp_setcomm_ee_nsd.yaml`. This is the SOL006-compliant NS descriptor, which models a Network Service containing the VNF specified above. It basically maps the VNF connection points with VIM-level networks.

#### Step 3: Upload the packages to the catalogue

Using the folders above, you can directly validate, compress and upload the contents to the OSM catalogues as packages, in this way:

```
# Upload the VNF package first
osm nfpkg-create snmp_setcomm_ee_vnf

# Then, upload the NS package that refers to the VNF package
osm nspkg-create snmp_setcomm_ee_ns
```

With this last step, the onboarding process has finished.

### Instantiation

#### Instantiation requirements

- Full OSM installation (Release 9+)
- Access to a VIM with [this VyOS image](http://osm-download.etsi.org/ftp/osm-5.0-five/6th-hackfest/images/vyos-1.1.7-cloudinit.qcow2.tgz) (needs to be uncompressed first), named as `vyos-1.1.7` in your images catalogue.

#### Step 1: Ensure your infrastructure is ready

Ensure you have a VIM created, for example, for OpenStack we would use the following command:

```
osm vim-create --name MY_VIM --tenant MY_VIM_TENANT --user MY_TENANT_USER --password MY_TENANT_PASSWORD --auth_url 'http://MY_KEYSTONE_URL' --account_type openstack
```

Then, identify your management network, which should exist already in your VIM and should be reachable from the OSM machine. In this case, we will use the name "osm-ext".

#### Step 2: Instantiate the Network Service

Launch the Network Service with the following command (in this example we are using "osm-ext" as the network name)

```
osm ns-create --ns_name ee-ansible --nsd_name snmp_setcomm_ee-ns --vim_account vim-name --config "{vld: [{name: mgmtnet, vim-network-name: osm-ext}]}"
```

Note that the management network defined at the NSD as "mgmtnet", is replaced at instantiation time with "osm-ext" as our real management network name.

#### Step 3: Visualize the results

Once instantiated, you can see the NS status with the `osm ns-list` command or visiting the GUI.
Furthermore, you can check:

- The SNMP metrics at the Prometheus dashboard (which usually runs at port 9091), which can be then integrated to the Grafana Dashboard.
- The primitives execution result, which with the Helm-based execution environments can be seen by exploring the POD's log. For example: `kubectl logs -n osm eechart-0016281061-0 -f`

### Possible quick customizations

Some common customizations that make this package easily reusable are:

- Modify the VDU's image, computing resources and/or interfaces at the VNFD.
- Add more VDUs, with different characteristics at the VNFD.
- Modify the SNMP variables or MIBs to use for metrics collection, at the `snmp_setcomm_ee_vnf/helm-charts/eechart/snmp` folder.
- Modify the playbook contents at the `snmp_setcomm_ee_vnf/helm-charts/eechart/source/community.yaml` folder.
- Modify the day-0 (cloud_init) configurations, with the `snmp_setcomm_ee_vnf/cloud_init/vyos-userdata` file and the "config" primitive contents at the VNFD.

## Single VDU Virtual Desktop with Native Charms <a name="desktop">

This example implements an Ubuntu Mate virtual machine with XRDP, created from a stock Ubuntu Cloud image (https://cloud-images.ubuntu.com/focal/current/).  On instantiation, a native charm is run, installing all the required packages and configuring the VM to run as a desktop.

### Onboarding

#### Onboarding requirements

- OSM Client installed in linux
- Internet access to clone packages

#### Step 1: Clone the OSM packages to your local machine

If you don't have the OSM Packages folder cloned yet, proceed with cloning it:

```
git clone --recursive https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages
```

#### Step 2: Explore the packages

The file `hackfest_virtual-pc_ns/hackfest_virtual-pc_nsd.yaml` is the SOL006-compliant network service descriptor, which maps the VNF to VIM-level networks.  There are two networks that this service will use:

1. "mgmtnet": the management network, which represents the internal, private management network that is used for controlling the VM
2. "private": a secondary network that should only expose the RDP port, providing the point of presence for remote workers.  This network can be created by OSM on demand

The vnf directory `hackfest_virtual-pc_vnfd` contains:

1. the SOL006-compliant virtual network function descriptor `virtual-pc_vnfd.yaml`
2. a cloud-init folder where some day 0 operations can take place
3. a charms folder, where the remainder of the day 0, day 1 and day 2 operations code is stored

###### Explore Day 0 Actions

Actions that are encoded in files before the VNF starts are known as day 0 actions.  In this package, we set a password for the ubuntu user so that it is immediately available for use.  This is done via the Openstack cloud-init mechanism.  The VNFD has the following entry, which instructs OSM to use the file `virtual-pc_init` from the `cloud-init` directory as the cloud init file when launching the vm.

```
vdu:
- cloud-init-file: virtual-pc_init
```

Further information on cloud-init can be found here: https://cloudinit.readthedocs.io/en/latest/topics/modules.html

The use of day 0 is not required for native charms to work.  It is used as an example in this VNFD.

##### Explore Day 1 Actions

When using native charms, day 1 actions are performed by the charms themselves.  First, the VNFD contains information about the execution environment:

```
execution-environment-list:
- id: virtual-pc-ee
  juju:
    charm: virtual-pc
    proxy: false
```

Where:
* `id` is an arbitrary identifier
* `juju` indicates that this will be a charm running under Juju
* `charm` is the name of the folder in the package where the compiled charm is located
* `proxy` is a flag that tells OSM to create an execution environment for the charm (`true`), or that the charm will execute within the scope of the NF itself (`false`)

Now that we know this is a Juju charm, we can look at the folder structure:

```
hackfest_virtual-pc_vnfd
| - charms
|   | - virtual-pc
|   | - virtual-pc-src
```

There are two directories present: virtual-pc, which contains the compiled and ready to execute charm code, and virtual-pc-src, which is where all the source code to prepare the charms is placed.  The source does not need to be present in the package for deployment; it is just a convenient way of keeping them together for demonstration purposes.  Also the name of the source code directory does not need to match the `charm` name, as source is never used at deployment time.

As an operator, Juju itself uses an observer pattern, where there are lifecycle events that the charm can listen to and perform actions.  

From https://juju.is/docs/sdk/events, we can see the install event is emitted once at the beginning of a charm’s lifecycle, so this is the best place for us to implement our day 1 actions.  Looking at the source code of the charm from `virtual-pc-src/src/charm.py`, there is an _on_install method which was set up to be called on the install lifecycle action.  This is where we install the base APT packages that we require for the virtual desktop to function.


##### Explore Day 2 Actions

While Juju provides specific lifecycle actions, it is not restricted to just those actions.  For day 2 operations, we can define any action we need, along with additional parameters to pass into the action.  For example, in the VNFD, we can see:

```
config-primitive:
- name: add-package
  execution-environment-ref: virtual-pc-ee
  parameter:
  - data-type: STRING
    name: package
```

Where:
* `name` is the name of the action that we tell OSM to perform with the `osm ns-action` command
* `execution-environment-ref` points to the name of the execution environment, which is where we defined the name of the charm and that this was run using Juju
* `parameter` provides optional parameters by name for `osm ns-action` to pass to the charm on execution

The charm code was told to listen for the `add-package` event:
```
self.framework.observe(self.on["add-package"].action, self._add_package)
```

And the `_add_package` method can fetch the parameters from the event itself:
```
packages=event.params["package"]
```

#### Step 3: Upload the packages to the catalogue

Using the folders above, you can directly validate, compress and upload the contents to the OSM catalogues as packages, in this way:

```
# Upload the VNF package first
osm nfpkg-create hackfest_virtual-pc_vnfd

# Then, upload the NS package that refers to the VNF package
osm nfpkg-create hackfest_virtual-pc_ns
```

With this last step, the onboarding process has finished.

### Instantiation

#### Instantiation requirements

- Full OSM installation (Release 9+)
- Access to a VIM with Ubuntu 20.04 image loaded and named ubuntu20.04 in the images catalogue.

#### Step 1: Ensure your infrastructure is ready

Ensure you have a VIM created, for example, for OpenStack we would use the following command:

```
osm vim-create --name MY_VIM --tenant MY_VIM_TENANT --user MY_TENANT_USER --password MY_TENANT_PASSWORD --auth_url 'http://MY_KEYSTONE_URL' --account_type openstack
```

Then, identify your management network, which should exist already in your VIM and should be reachable from the OSM machine. In this case, we will use the name "osm-ext".

#### Step 2: Instantiate the Network Service

Launch the Network Service with the following command (in this example we are using "osm-ext" as the network name)

```
osm ns-create --ns_name virtual-desktop \
    --nsd_name hackfest_virtual-pc_ns \
    --vim_account vim-name \
    --config \
    '{vld: [ {name: mgmtnet, vim-network-name: osm-ext},
             {name: private, vim-network-name: private} ] }'
```

This shows how to provide an override to the name of the management network and private network in the NS:

* `mgmtnet` is mapped to a network in the VIM called `osm-ext`
* `private` is mapped to a network in the VIM called `private`

These can be changed to match your VIM as needed.

#### Step 3: Visualize the results

Once instantiated, you can see the NS status with the `osm ns-list` command or visiting the GUI.  You can also get the IP address of the VNF using Openstack, or OSM commands:

```
osm ns-show virtual-desktop --literal | \
   yq e '.vcaStatus.*.machines.0.network_interfaces.ens3.ip_addresses.0' -
```

With the IP address, you can SSH or RDP to the server and log in as ubuntu with password osm2021 or as set in the cloud-init file.  Actions can be performed on the virtual desktop as follows:

* `osm ns-action virtual-desktop --vnf_name 1 --action_name update-system` to trigger the update-system function in the charm, which calls apt to update the software on the system
* `osm ns-action virtual-desktop --vnf_name 1 --action_name reboot` to reboot the system
* `osm ns-action virtual-desktop --vnf_name 1 --action_name announce --params '{message: "Hello from OSM!"}'` to display a notice to the logged in user's desktop

### Possible quick customizations

Some common customizations that make this package easily reusable are:

- Modify the VDU's image, computing resources and/or interfaces at the VNFD.  Right now the memory and CPU requirements are fairly high.  Minimum recommended are 2 CPUS and 2GB RAM
- Modify the software installed by default
- Modify the use of an Apt cache that is set up during the day 1 action
- Add actions to add/remove users, or change passwords