OSM Charms and interfaces

Description: This document describes the high-level view of the OSM Charms and interfaces. An important note is that these charms Kubernetes Charms, so they must be deployed on top of a Kubernetes Cloud using Juju.

Folder tree

In the current directory, there is one folder "interfaces" that has all the interfaces of the OSM components, which are basically two: osm-nbi, and osm-ro.

Additionally, we can see six folders that contain each OSM core components: lcm-k8s, mon-k8s, nbi-k8s, pol-k8s, ro-k8s, and ui-k8s.

Then, we can see a folder "bundle" which has the templates for the OSM bundles in single instance and HA.

The "layers" folder include one common layer for all the osm charms (osm-common)


├── bundles
│   ├── osm
│   └── osm-ha
├── interfaces
│   ├── osm-nbi
│   └── osm-ro
├── layers
│   └── osm-common
├── lcm-k8s
├── mon-k8s
├── nbi-k8s
├── pol-k8s
├── ro-k8s
└── ui-k8s

Charms

All the charms have a very similar structure. This subsection explains the purpose of each file inside the charms, as well as basic steps to get started.

The folder structure for each charm looks like this:

<charm>-k8s/
├── config.yaml
├── icon.svg
├── layer.yaml
├── metadata.yaml
├── reactive
│   ├── <charm>.py
│   └── spec_template.yaml
├── README.md
├── .gitignore
├── .yamllint.yaml
└── tox.ini

Purpose of each file:

config.yaml: YAML file that include all the configurable options for the charm.
icon.svg: SVG icon. This is the icon that will appear in the Charm Store.
layer.yaml: YAML file with the layers that the charm needs. All the OSM Charms need at least the following layers: caas-base, status, leadership, and osm-common. If charms provide or require interfaces, which all of them do, those interfaces should be specified in this file too.
metadata.yaml: YAML file that describe the top level information of the charm: name, description, series, interfaces that provide/require, needed storage, and deployment type.
reactive/<charm>.py: Python file that implements the actual logic to the charm.
reactive/spec_template.yaml: Pod spec template to be used by the pods.
README.md: This file describes how to build the charm, how to prepare the environment to test it with Microk8s.
.gitignore: Typical Git Ignore file, to avoid pushing unwanted files to upstream.
.yamllint.yaml: YAML file to specify the files to exclude from the yamllint test that tox.ini does.
tox.ini: Includes basic functions to build the charms, and check the linting.

Interfaces

Each interface needs at least three files:

interface.yaml: Metadata of the interface: name, maintainer, and summary.
provides.py: Code for the charm that provides the interface.
requires.py: Code for the charm that requires the interface.

Additionally, there are also files for copyright and a README that explains how to use the interface.

Steps for testing

Dependencies

sudo apt install tox -y

Check the syntax of the charms

./lint.sh

Build all the charms

./build.sh

Generate bundle

# Generate bundle from built charms
python3 generate_bundle.py --local --destination osm.yaml
# Help
python3 generate_bundle.py --help

Install VCA

sudo snap install juju --classic
juju bootstrap localhost osm-lxd

Generate overlay

NOTE: This will be removed once the installer is merged.

sudo snap install osmclient
sudo snap alias osmclient.osm osm
sudo snap connect osmclient:juju-client-observe
sudo snap connect osmclient:ssh-public-keys
sudo snap connect osmclient:network-control
osmclient.overlay  # Execute the commands printed by this command to enable native charms

Bootstrap Juju controller in Microk8s

sudo snap install microk8s --classic
sudo usermod -a -G microk8s ubuntu
sudo chown -f -R ubuntu ~/.kube
newgrp microk8s
microk8s.status --wait-ready
microk8s.enable storage dns  # (metallb) is optional
juju bootstrap microk8s osm-k8s

Deploy OSM with charms

juju add-model osm
juju deploy ./osm.yaml --overlay vca-overlay.yaml

Wait until Charms are deployed

watch -c juju status --color  # Wait until every application is in active state
export OSM_HOSTNAME=<ip-nbi>
osm ns-list
# ...