Creating your VNF Charm

Introduction to Juju and charms in OSM

A charm is a collection of scripts and metadata that encapsulate the distilled DevOps knowledge of experts in a particular product. Charms make it easy to reliably and repeatedly deploy applications, then scale them as required with minimal effort.

In the context of OSM, Juju, through the use of charms, is responsible for VNF configuration and life-cycle management, excluding resource operations (instantiation, termination). This is called "manual provider" mode in Juju.

OSM supports a limited version of charms that we call "proxy charms", this charms are installed into an LXD container, and is only responsible for day-1 and day-2 configuration, executed remotely (typically via ssh).

Configurations are mapped to Juju Actions which manage configuration within the VNF. In the case of the proxy charm, the configuration might be done via SSH, via RESTful API, etc.

Here is a simple diagram showing how a proxy charm fits into the OSM workflow:

-A VNF package is instantiated via the LCM 
-The LCM requests a virtual machine from the RO
-The RO instantiates a VM with your VNF image 
-The LCM instructs N2VC, using the VCA, to deploy a VNF proxy charm, and tells it how to access your VM (hostname, user name, and password)

Setup

We recommend that you are running Ubuntu 16.04 or newer, or install snapd on the Linux distribution of your choice.

Install the charm snap, which provides the charm command and libraries necessary to compile your charm:

snap install charm

Setup your workspace for writing layers and building charms:

mkdir -p ~/charms/layers
export JUJU_REPOSITORY=~/charms
export LAYER_PATH=$JUJU_REPOSITORY/layers
cd $LAYER_PATH

Creating a charm

Charms must be created in the layers folder ($LAYER_PATH).

Layers

Layers are individual components that, when combined, result in a finished product, they have individual components that, when combined, result in a finished product.

The Base layer contains the core code needed for other layers to function.

Some of the most used layers in the context of OSM are:

layer:basic -> imports the reactive framework, contains the core code needed for other layers to function.
layer:vnfproxy -> imports the required functions to run actions in the VNF via SSH. This layer has been designed to aid in the development of proxy charms.
layer:metrics -> imports the required functions to get metrics from the VNF.
layer:restapi -> imports the required functions to run actions in the VNF via REST API.
layer:netconf -> imports the required functions to run actions in the VNF via Netconf primitives.

The diagram below describes an example of some of the layers contained in a charm, the completed charm is available in the juju-charms repository :

The command "charm create" will create the layer for your proxy charm:

$ cd $JUJU_REPOSITORY/layers
$ charm create 'charmName'
$ cd 'charmName'

This will create a charm layer ready for customization:

$JUJU_REPOSITORY/layers 
└── 'charmName' 
	├── config.yaml 
	├── icon.svg 
	├── layer.yaml 
	├── metadata.yaml 
	├── reactive 
		└── 'charmName'.py 
	├── README.ex 
	└── tests 
		  └── 00-setup
		  └── 10-deploy

When you create the charm, you will have to modify different files:

layer.yaml: specify which layers should be "imported" as part of the charm.
metadata.yaml: describes what your charm is and sets certain properties used by Juju.

     Typically you should specify at least:
        name: the name of the charm
        maintainer: contact info for the charm
        provides: what interfaces are provided by the charm
        requires: what interfaces are used by the charm
        peers: what peer relations exist
        series: which base image to use for the container running the charm

metrics.yaml: if the VNF wants to expose some metrics, a new file metrics.yaml has to be created to specify which metrics should be collected.

$JUJU_REPOSITORY/layers 
└── 'charmName' 
	├── metrics.yaml

actions.yaml: let’s create `actions.yaml` in the root of the simple charm. Actions are functions that can be called automatically when a VNF is initialized (day-1 configuration) or on-demand by the operator (day2 configuration). In OSM terminology, we know these as config primitives.

$JUJU_REPOSITORY/layers 
└── 'charmName' 
	├── actions.yaml

For each action, we need to create a script to invoke the reactive framework. This is a boilerplate script that will be used for every action.

$JUJU_REPOSITORY/layers 
└── 'charmName' 
	├── actions 
		└── action1
		└── action2
		       .
		       .
		       .
	├── actions.yaml

reactive/'charmName.py' : this is where all reactive states are handled. The reactive framework, coupled with the script in the actions/ directory, maps the SO's invocation of the action to the block of code with the matching @when decorator.

Building

Be sure that you are in the charm folder (e.g.: $LAYER_PATH/'charmName') and you have Internet connectivity before building the charm.

$ charm build

This combines all layers that you included, and those that they include, into a charm called 'charmName', located in the ~/charms/builds directory.

Updating VNF Descriptor and VNF Package

In your Virtual Network Function Descriptor (VNFD), you specify the name of the charm as demonstrated below:

vnfd:vnfd-catalog:
    vnfd:vnfd:
     -  vnfd:id: idvnfExample
        vnfd:name: vnfExample
        vnfd:vnf-configuration:
            vnfd:juju:
                vnfd:charm: 'charmName'

Then the compiled charm (from the builds directory) has to be packaged with the descriptor package under the charm directory. So the VNF with the charm would be:

<nowiki>

vnfExample ├── charms │ └── 'charmName' ├── checksums.txt ├── icons ├── images ├── vnfExample.yaml ├── README └── scripts