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, add 'initial-config-primitive' and 'config-primitive' parameters if needed:

vnfd:vnfd-catalog:
    vnfd:vnfd:
     -  vnfd:id: idvnfExample
        vnfd:name: vnfExample
        vnfd:vnf-configuration:
            vnfd:juju:
                vnfd:charm: 'charmName'
            vnfd:initial-config-primitive:
                         .
                         .
                         .
            vnfd:config-primitive:
                         .
                         .
                         .

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:

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

Example VNF Charms

This section is intended to be an index to VNF charms written by members of the OSM community.

Simple Charm

You can find all the material for execute Simple-charm:

• VNF package: hackfest_simplecharm_vnf
• NS package: hackfest_simplecharm_ns
• Image : hackfest3-mgmt
• Reference material::
  • How to generate VNF package from command line
  • Adding day-1/day-2 configuration to your VNF. Creating a charm for your VNF
  • Adding charms to your VNF Descriptor

Simple Charm provides different capacities through three layers:

• The Base layer contains the core code needed for other layers to function.
• Vnfproxy is a runtime layer providing common functionality to interoperate with a VNF.
• Simple is the charm layer containing code to manage your vnf.

Edit layer.yaml to include the vnfproxy layer:

includes: ['layer:basic', 'layer:vnfproxy']
options:
    basic:
        use_venv: false

Edit metadata.yaml with the name and description of your charm:

name:simple
summary:A simple VNF proxy charm
maintainer:Name<user@domain.tld>
subordinate:false
series:['xenial']

Let´s create 'actions.yaml' in the root of the simple charm:

touch:
  description: "Touch a file on the VNF."
  params:
    filename:
        description: "The name of the file to touch."
        type: string
        default: ""
  required:
    - filename

$ mkdir actions

Create `actions/touch` with the following content:

#!/usr/bin/env python3
import sys
sys.path.append('lib')
from charms.reactive import main, set_flag
from charmhelpers.core.hookenv import action_fail, action_name

set_flag('actions.{}'.format(action_name()))

try:
   main()
except Exception as e:
   action_fail(repr(e))

When you’re done, mark the script executable:

$ chmod +x actions/touch

Note: The same content has to be used for every action in the charm layer. It is only a boilerplate script to invoke the reactiveframework

Edit 'reactive/simple.py', this is where all reactives states are handled

from charmhelpers.core.hookenv import ( 
     action_get, 
     action_fail, 
     action_set, 
     status_set, 
) 
from charms.reactive import ( 
     clear_flag, 
     set_flag, 
     when, 
     when_not,
) 
import charms.sshproxy
# Set the charm’s state to active so the LCM knows
# it’s ready to work.
@when_not('simple.installed') 
def install_simple_proxy_charm():     
     set_flag('simple.installed') 
     status_set('active', 'Ready!')
# Define what to do when the `touch` primitive is invoked. 
@when('actions.touch')
def touch(): 
     err = ''
     try: 
          filename = action_get('filename') 
          cmd = ['touch {}'.format(filename)]
          result, err = charms.sshproxy._run(cmd) 
     except: 
         action_fail('command failed:' + err) 
     else: 
         action_set({'output': result})
      finally: 
          clear_flag('actions.touch')

We’re ready to compile the charm with our new action:

$ charm build

Finally, you have to update VNF Descriptor and VNF Package.

vnfd:vnfd-catalog:
    vnfd:
    -   id: hackfest3charmed-vnf
        name: hackfest3charmed-vnf
        vnf-configuration:
            juju:
                charm: simple
            initial-config-primitive:
            -   seq: '1'
                name: config
                parameter:
                -   name: ssh-hostname
                    value: <rw_mgmt_ip>
                -   name: ssh-username
                    value: ubuntu
                -   name: ssh-password
                    value: osm4u
            -   seq: '2'
                name: touch
                parameter:
                -   name: filename
                    value: '/home/ubuntu/first-touch'
            config-primitive:
            -   name: touch
                parameter:
                -   name: filename
                    data-type: STRING
                    default-value: '/home/ubuntu/touched'

Ansible

Under the scope of a H2020 project, 5GinFIRE has developed a charm that enables the configuration of a VNF, instantiated through OSM, using an Ansible playbook. The charm builds off of the base vnfproxy and ansible-base layers, and provides a template ready for customization that supports the execution of an Ansible playbook within the Juju framework used by OSM.

You can find here all files about ansible-charm.

Step by step instructions to use the base charm layer:

-Include playbook.yaml under the playbook folder of the base charm layer:

$JUJU_REPOSITORY/layers 
└── ansible-charm 
	├── playbook 
		└── playbook.yaml

-The base charm layer already implements a Juju action, ansible-playbook, which runs the playbook. You can define additional actions, if needed by your VNF.

$JUJU_REPOSITORY/layers 
└── ansible-charm 
	├── actions 
		└── ansible-playbook
		└── action1
		       .
		       .
		       .
	├── actions.yaml		

-We are ready to build the charm:

$ charm build

-Update the VNF descriptor (VNFD) to use the charm: a) specify the name of the Juju charm in in the VNF configuration; b) Include the action “ansible-playbook” with no arguments as a service primitive and as an initial configuration primitive.

-Include the compiled charm in the VNF package.