10. ANNEX 2: Reference of OSM Client commands and library
The OSM Client is a client library and a command-line tool (based on Python) to operate OSM, which accesses OSM’s Northbound Interface (NBI) and lets you manage descriptors, VIMs, Network Services, Slices, etc. along with their whole lifecycle. In other words, the OSM Client is a sort of Swiss knife that provides a convenient access to all the functionality that OSM’s NBI offers.
Usage:
osm [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGS]...
Options:
--hostname TEXT hostname of server. Also can set OSM_HOSTNAME in environment
--user TEXT user (defaults to admin). Also can set OSM_USER in environment
--password TEXT password (defaults to admin). Also can set OSM_PASSWORD in environment
--project TEXT project (defaults to admin). Also can set OSM_PROJECT in environment
-v, --verbose increase verbosity (-v INFO, -vv VERBOSE, -vvv DEBUG)
--all-projects include all projects
--public / --no-public flag for public items (packages, instances, VIM accounts, etc.)
--project-domain-name TEXT project domain name for keystone authentication (default to None). Also can set OSM_PROJECT_DOMAIN_NAME in environment
--user-domain-name TEXT user domain name for keystone authentication (default to None). Also can set OSM_USER_DOMAIN_NAME in environment
-h, --help Show this message and exit.
Commands:
k8scluster-add adds a K8s cluster to OSM NAME: name of the K8s cluster
k8scluster-delete deletes a K8s cluster NAME: name or ID of the K8s cluster to be deleted
k8scluster-list list all K8s clusters
k8scluster-show shows the details of a K8s cluster NAME: name or ID of the K8s cluster
k8scluster-update updates a K8s cluster
netslice-instance-create creates a new Network Slice Instance
netslice-instance-delete deletes a Network Slice Instance (NSI)
netslice-instance-list list all Network Slice Instances (NSI)
netslice-instance-op-list shows the history of operations over a Network Slice Instance (NSI)
netslice-instance-op-show shows the info of an operation over a Network Slice Instance(NSI)
netslice-instance-show shows the content of a Network Slice Instance (NSI)
netslice-template-create creates a new Network Slice Template (NST)
netslice-template-delete deletes a Network Slice Template (NST)
netslice-template-list list all Network Slice Templates (NST)
netslice-template-show shows the content of a Network Slice Template (NST)
netslice-template-update updates a Network Slice Template (NST)
nf-list list all NF instances
nfpkg-create creates a new NFpkg
nfpkg-delete deletes a NFpkg
nfpkg-list list all xNF packages (VNF, HNF, PNF)
nfpkg-repo-list list all xNF from OSM repositories
nfpkg-repo-show shows the details of a NF package in an OSM repository
nfpkg-show shows the details of a NF package
nfpkg-update updates a NFpkg
ns-action executes an action/primitive over a NS instance
ns-alarm-create creates a new alarm for a NS instance
ns-create creates a new Network Service instance
ns-delete deletes a NS instance
ns-list list all NS instances
ns-metric-export exports a metric to the internal OSM bus, which can be read by other apps
ns-op-list shows the history of operations over a NS instance
ns-op-show shows the info of a NS operation
ns-show shows the info of a NS instance
nsd-create creates a new NSD/NSpkg
nsd-delete deletes a NSD/NSpkg
nsd-list list all NS packages
nsd-repo-list list all NS from OSM repositories
nsd-repo-show shows the details of a NS package in an OSM repository
nsd-show shows the details of a NS package
nsd-update updates a NSD/NSpkg
nsi-create creates a new Network Slice Instance
nsi-delete deletes a Network Slice Instance (NSI)
nsi-list list all Network Slice Instances (NSI)
nsi-op-list shows the history of operations over a Network Slice Instance (NSI)
nsi-op-show shows the info of an operation over a Network Slice Instance(NSI)
nsi-show shows the content of a Network Slice Instance (NSI)
nspkg-create creates a new NSD/NSpkg
nspkg-delete deletes a NSD/NSpkg
nspkg-list list all NS packages
nspkg-repo-list list all NS from OSM repositories
nspkg-repo-show shows the details of a NS package in an OSM repository
nspkg-show shows the details of a NS package
nspkg-update updates a NSD/NSpkg
nst-create creates a new Network Slice Template (NST)
nst-delete deletes a Network Slice Template (NST)
nst-list list all Network Slice Templates (NST)
nst-show shows the content of a Network Slice Template (NST)
nst-update updates a Network Slice Template (NST)
package-build Build the tar.gz of the package
package-create Create a package descriptor
package-validate Validate a package descriptor
pdu-create adds a new Physical Deployment Unit to the catalog
pdu-delete deletes a Physical Deployment Unit (PDU)
pdu-list list all Physical Deployment Units (PDU)
pdu-show shows the content of a Physical Deployment Unit (PDU)
project-create creates a new project
project-delete deletes a project
project-list list all projects
project-show shows the details of a project
project-update updates a project (only the name can be updated)
repo-add adds a repo to OSM NAME: name of the repo URI: URI of the repo
repo-delete deletes a repo NAME: name or ID of the repo to be deleted
repo-list list all repos
repo-show shows the details of a repo NAME: name or ID of the repo
repo-update updates a repo in OSM NAME: name of the repo
role-create creates a new role
role-delete deletes a role
role-list list all roles
role-show show specific role
role-update updates a role
sdnc-create creates a new SDN controller
sdnc-delete deletes an SDN controller
sdnc-list list all SDN controllers
sdnc-show shows the details of an SDN controller
sdnc-update updates an SDN controller
upload-package uploads a VNF package or NS package
user-create creates a new user
user-delete deletes a user
user-list list all users
user-show shows the details of a user
user-update updates user information
version
vim-create creates a new VIM account
vim-delete deletes a VIM account
vim-list list all VIM accounts
vim-show shows the details of a VIM account
vim-update updates a VIM account
vnf-list list all NF instances
vnf-scale executes a VNF scale (adding/removing VDUs)
vnf-show shows the info of a VNF instance
vnfd-create creates a new VNFD/VNFpkg
vnfd-delete deletes a VNFD/VNFpkg
vnfd-list list all xNF packages (VNF, HNF, PNF)
vnfd-show shows the details of a NF package
vnfd-update updates a new VNFD/VNFpkg
vnfpkg-create creates a new VNFD/VNFpkg
vnfpkg-delete deletes a VNFD/VNFpkg
vnfpkg-list list all xNF packages (VNF, HNF, PNF)
vnfpkg-repo-list list all xNF from OSM repositories
vnfpkg-repo-show shows the details of a NF package in an OSM repository
vnfpkg-show shows the details of a NF package
vnfpkg-update updates a VNFD/VNFpkg
wim-create creates a new WIM account
wim-delete deletes a WIM account
wim-list list all WIM accounts
wim-show shows the details of a WIM account
wim-update updates a WIM account
10.1. Installing standalone OSM Client
OSM client is installed by default in the host where OSM is installed, but it can be also installed as a standalone client.
10.1.1. Installing with debian package
In order to install the OSM Client in your local Linux machine, you should follow this procedure:
# Clean the previous repos that might exist
sudo sed -i "/osm-download.etsi.org/d" /etc/apt/sources.list
wget -qO - https://osm-download.etsi.org/repository/osm/debian/ReleaseELEVEN/OSM%20ETSI%20Release%20Key.gpg | sudo apt-key add -
sudo add-apt-repository -y "deb [arch=amd64] https://osm-download.etsi.org/repository/osm/debian/ReleaseELEVEN stable devops IM osmclient"
sudo apt-get update
sudo apt-get install -y python3-pip
sudo -H python3 -m pip install -U pip
sudo -H python3 -m pip install python-magic pyangbind verboselogs
sudo apt-get install python3-osmclient
10.1.2. Installing from git repo
# Ubuntu 18.04 pre-requirements
sudo apt-get install python3-pip libcurl4-openssl-dev libssl-dev
# CentOS pre-requirements
# sudo yum install python3-pip libcurl-devel gnutls-devel
sudo -H python3 -m pip install python-magic
# Install OSM Information model
sudo -H python3 -m pip install git+https://osm.etsi.org/gerrit/osm/IM --upgrade
# Install OSM client from the git repo.
# You can install the latest client from master branch in this way:
sudo -H python3 -m pip install git+https://osm.etsi.org/gerrit/osm/osmclient
# You could also install a specific tag/version in this way
sudo -H python3 -m pip install git+https://osm.etsi.org/gerrit/osm/osmclient@v8.0.0rc1
10.1.3. Installing from cloned repo (for developers)
# Ubuntu 18.04 pre-requirements
sudo apt-get install python3-pip libcurl4-openssl-dev libssl-dev
# Centos pre-requirements
# sudo yum install python3-pip libcurl-devel gnutls-devel
sudo -H python3 -m pip install python-magic pyangbind verboselogs
# Install OSM Information model
sudo -H python3 -m pip install git+https://osm.etsi.org/gerrit/osm/IM --upgrade
# Clone the osmclient repo and install OSM client from the git repo.
git clone https://osm.etsi.org/gerrit/osm/osmclient
cd osmclient
python3 -m pip install --user -e .
# logout and login so that PATH can be updated. Executable osm will be found in /home/ubuntu/.local/bin
To uninstall, just:
python3 -m pip uninstall osmclient
10.2. Getting help
Options -h
or --help
can be used globally to know the global options and commands, or after a command to know the specific options and args of a command
$ osm -h
Usage: osm [OPTIONS] COMMAND [ARGS]...
Options:
--hostname TEXT hostname of server. Also can set OSM_HOSTNAME in environment
--user TEXT user (defaults to admin). Also can set OSM_USER in environment
--password TEXT password (defaults to admin). Also can set OSM_PASSWORD in environment
--project TEXT project (defaults to admin). Also can set OSM_PROJECT in environment
-v, --verbose increase verbosity (-v INFO, -vv VERBOSE, -vvv DEBUG)
--all-projects include all projects
--public / --no-public flag for public items (packages, instances, VIM accounts, etc.)
--project-domain-name TEXT project domain name for keystone authentication (default to None). Also can set OSM_PROJECT_DOMAIN_NAME in environment
--user-domain-name TEXT user domain name for keystone authentication (default to None). Also can set OSM_USER_DOMAIN_NAME in environment
-h, --help Show this message and exit.
Commands:
k8scluster-add adds a K8s cluster to OSM
...
$osm vim-create -h
Usage: osm vim-create [OPTIONS]
creates a new VIM account
Options:
--name TEXT Name to create datacenter
--user TEXT VIM username
--password TEXT VIM password
--auth_url TEXT VIM url
--tenant TEXT VIM tenant name
--config TEXT VIM specific config parameters
--account_type TEXT VIM type
--description TEXT human readable description
--sdn_controller TEXT Name or id of the SDN controller associated to this VIM account
--sdn_port_mapping TEXT File describing the port mapping between compute nodes' ports and switch ports
--wait do not return the control immediately, but keep it until the operation is completed, or timeout
-h, --help Show this message and exit.
The following video illustrates how it works.
10.3. Interaction from the OSM client to an OSM in a different location
When using the OSM Client from a host different from OSM’s, at a minimum you will need to specify the OSM host, either via an environment variable or via the option --hostname
. For instance, you can set your client to access an OSM host running at 10.80.80.5
by using:
export OSM_HOSTNAME="10.80.80.5"
The following video shows how it works.
10.4. Getting OSM version
You can obtain server and client versions, by using the command osm version
. Server version corresponds to OSM NBI module.
$ osm version
Server version: 7.0.1.post23 2020-04-17
Client version: 7.0.1rc1.post52+gbcb7833
The following video shows how it works.
10.5. RBAC
10.5.1. Configuring RBAC
OSM supports Role-Based Access Control, so that it’s possible to use users and projects, and each user will have a role in a project. OSM provides CRUD operations (*-create
, *-list
, *-show
, *-update
, *-delete
) over users, roles and projects
The following video demonstrates how it works.
10.5.2. Using RBAC
When using users and projects, the following environment variables can be used to authenticate against the system:
OSM_USER
OSM_PASSWORD
OSM_PROJECT
OSM_PROJECT_DOMAIN_NAME
OSM_USER_DOMAIN_NAME
Or instead the command line options --user
, --password
, --project
, --project-domain-name
and --user-domain-name
can be used:
--user TEXT user (defaults to admin). Also can set OSM_USER in environment
--password TEXT password (defaults to admin). Also can set OSM_PASSWORD in environment
--project TEXT project (defaults to admin). Also can set OSM_PROJECT in environment
--project-domain-name TEXT project domain name for keystone authentication (default to None). Also can set OSM_PROJECT_DOMAIN_NAME in environment
--user-domain-name TEXT user domain name for keystone authentication (default to None). Also can set OSM_USER_DOMAIN_NAME in environment
In addition, the option --all-projects
allow users to perform operations in all the projects they belong to (e.g. osm --all-projects nfpkg-list
will show all the NF packages in all projects the user belongs to). Finally, the option --public
allows to create public items, making them available in all projects; visibility from the client of those public items in *-list
and *-show
operations requires the use of the option --public
.
--all-projects include all projects
--public / --no-public flag for public items (packages, instances, VIM accounts, etc.)
The following video shows a complete demo using different users and projects, and some of these options, illustrating the different project visibility.
10.6. OSM repositories
OSM support repositories where NF and NS packages can be retrieved. The following commands can be used to add a repo, list the packages in a repo, show their details or onboard them in OSM:
osm repo-add NAME URI
: adds a VNF/NS catalog repoosm nfpkg-repo-list
andosm nspkg-repo-list
: lists NF/NS packages from OSM repositoriesosm nfpkg-repo-show|nspkg-repo-show --repo <REPO_NAME>
: shows a specific NF/NS package in a repoosm nfpkg-create|nspkg-create --repo <REPO_NAME> <OSM_PKG>
: onboards a package from a repo into OSM
osm repo-add --description "OSM VNF and NS repository" vnfrepo https://osm-download.etsi.org/ftp/vnf-catalog/
osm nfpkg-repo-list
osm nfpkg-repo-show --repo vnfrepo fb_magma_knf
osm nfpkg-create --repo vnfrepo fb_magma_knf
osm nspkg-repo-list
osm nspkg-repo-show --repo vnfrepo fb_magma_ns
osm nspkg-create --repo vnfrepo fb_magma_ns
The following video demonstrates how these commands work.
10.7. Package creation tools
There are several utilities in the OSM client to simplify VNF and NS package creation:
osm package-create PACKAGE_TYPE PACKAGE_NAME
: creates an OSM VNF, NS or NST packageosm package-validate PKG_FOLDER
: validates descriptors given a base directoryosm package-build PKG_FOLDER
: builds the package NS, VNF given the package_folder (descriptor validation, charm build, checksum generation, tar.gz creation)osm nfpkg-create|nspkg-create PKG_FOLDER
: validates the package, builds it and onboards it into OSM
The following video illustrates the previous commands.
10.8. Advanced onboarding
Commands for onboarding NF, NS and NST (nfpkg-create
, nspkg-create
and nst-create
) have the option --override
to override the fields in the descriptor whem uploading the package to OSM. The format of the option is the following:
--override TEXT overrides fields in descriptor, format: "key1.key2...=value[;key3...=value;...]"
In addition, VNF onboarding allows these additional options:
--override-epa
: adds guest-epa parameters to all VDU. Useful to onboard packages to be deployed in an EPA-only VIM--override-nonepa
: removes all guest-epa parameters from all VDU. Useful to onboard EPA-based VNF packages to be deployed in a non-EPA VIM--override-paravirt
: overrides all VDU interfaces to PARAVIRT. Useful if packages are going to be deployed in a VIM that does not support SR-IOV or PCI-PASSTHROUGH interfaces.
The following video demonstrates how these options work.
10.9. Filtering requests
Some commands have the option --filter
that allows to filter Read operations (*-list
, *-show
) to restric the output to the items matching de filter. Below an example for osm ns-list
:
$ osm ns-list -h
Usage: osm ns-list [OPTIONS]
list all NS instances
Options:
--filter filterExpr Restricts the list to the NS instances matching the filter
filterExpr consists of one or more strings formatted according to "simpleFilterExpr",
concatenated using the "&" character:
filterExpr := <simpleFilterExpr>["&"<simpleFilterExpr>]*
simpleFilterExpr := <attrName>["."<attrName>]*["."<op>]"="<value>[","<value>]*
op := "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "cont" | "ncont"
attrName := string
value := scalar value
where:
* zero or more occurrences
? zero or one occurrence
[] grouping of expressions to be used with ? and *
"" quotation marks for marking string constants
<> name separator
"AttrName" is the name of one attribute in the data type that defines the representation
of the resource. The dot (".") character in "simpleFilterExpr" allows concatenation of
<attrName> entries to filter by attributes deeper in the hierarchy of a structured document.
"Op" stands for the comparison operator. If the expression has concatenated <attrName>
entries, it means that the operator "op" is applied to the attribute addressed by the last
<attrName> entry included in the concatenation. All simple filter expressions are combined
by the "AND" logical operator. In a concatenation of <attrName> entries in a <simpleFilterExpr>,
the rightmost "attrName" entry in a "simpleFilterExpr" is called "leaf attribute". The
concatenation of all "attrName" entries except the leaf attribute is called the "attribute
prefix". If an attribute referenced in an expression is an array, an object that contains a
corresponding array shall be considered to match the expression if any of the elements in the
array matches all expressions that have the same attribute prefix.
Filter examples:
--filter admin-status=ENABLED
--filter nsd-ref=<NSD_NAME>
--filter nsd.vendor=<VENDOR>
--filter nsd.vendor=<VENDOR>&nsd-ref=<NSD_NAME>
--filter nsd.constituent-vnfd.vnfd-id-ref=<VNFD_NAME>
10.10. Debugging
Option -v
can be used to debug OSM client. There are different verbosity levels:
-v
: log level INFO, shows API calls-vv
: log level VERBOSE, shows API calls and content response-vvv
: log level DEBUG, shows the different methods the client is going through
The following video illustrates the log detail for each verbosity level.
10.11. Other useful options
Some commands present useful options:
--literal
: shows output in YAML format. It might be deprecated in the future in favour of a new option-o OUTPUT_FORMAT
.--wait
: makes the command synchronous--long
: shows more info
10.12. Aliases
The following are command aliases with identical behaviour:
For CRUD operations over NF packages, there are different command aliases. The preferred commands is
nfpkg-*
. The commandvnfd-*
might be deprecated in the future.nfpkg-create|vnfpkg-create|vnfd-create
: creates a new NFpkgnfpkg-delete|vnfpkg-delete|vnfd-delete
: deletes a NFpkgnfpkg-list|vnfpkg-list|vnfd-list
: list all xNF packages (VNF, HNF, PNF)nfpkg-show|vnfpkg-show|vnfd-show
: shows the details of a NF packagenfpkg-update|vnfpkg-update|vnfd-update
: updates a NFpkg
For CRUD operations over NS packages, there are different command aliases. The preferred commands is
nspkg-*
. The commandnsd-*
might be deprecated in the future.nsd-create|nspkg-create
: creates a new NSD/NSpkgnsd-delete|nspkg-delete
: deletes a NSD/NSpkgnsd-list|nspkg-list
: list all NS packagesnsd-show|nspkg-show
: shows the details of a NS packagensd-update|nspkg-update
: updates a NSD/NSpkg
For CRUD operations over Network Slice Templates, the following command aliases exist:
netslice-template-create|nst-create
: creates a new Network Slice Template (NST)netslice-template-delete|nst-delete
: deletes a Network Slice Template (NST)netslice-template-list|nst-list
: list all Network Slice Templates (NST)netslice-template-show|nst-show
: shows the content of a Network Slice Template (NST)netslice-template-update|nst-update
: updates a Network Slice Template (NST)
For CRUD operations over Network Slice Instances, the following command aliases exist:
netslice-instance-create|nsi-create
: creates a new Network Slice Instancenetslice-instance-delete|nsi-delete
: deletes a Network Slice Instance (NSI)netslice-instance-list|nsi-list
: list all Network Slice Instances (NSI)netslice-instance-op-list|nsi-op-list
: shows the history of operations over a Network Slice Instance (NSI)netslice-instance-op-show|nsi-op-show
: shows the info of an operation over a Network Slice Instance(NSI)netslice-instance-show|nsi-show
: shows the content of a Network Slice Instance (NSI)
For Read operations over OSM repositories, the following command aliases exist:
nfpkg-repo-list|vnfpkg-repo-list
: list all xNF from OSM repositoriesnfpkg-repo-show|vnfpkg-repo-show
: shows the details of a NF package in an OSM repositorynsd-repo-list|nspkg-list
: list all NS from OSM repositoriesnsd-repo-show|nspkg-show
: shows the details of a NS package in an OSM repository
10.13. Enable autocompletion
You can enable autocompletion in OSM client by creating a file osm-complete.sh in the following way:
mkdir -p $HOME/.bash_completion.d
_OSM_COMPLETE=bash_source osm > $HOME/.bash_completion.d/osm-complete.sh
Then you can add the following to your $HOME/.bashrc file:
. .bash_completion.d/osm-complete.sh
10.14. Using osmclient as a library to interact with OSM
Assuming that you have installed python-osmclient package, it’s pretty simple to write some Python code to interact with OSM.
10.14.1. Simple Python code to get the list of NS packages
from osmclient import client
from osmclient.common.exceptions import ClientException
hostname = "127.0.0.1"
myclient = client.Client(host=hostname, sol005=True)
resp = myclient.nsd.list()
print yaml.safe_dump(resp)
10.14.2. Simple Python code to get the list of VNF packages from a specific user and project
The code will print for each package a pretty table, then the full details in yaml
from osmclient import client
from osmclient.common.exceptions import ClientException
import yaml
from prettytable import PrettyTable
hostname = "127.0.0.1"
user = admin
password = admin
project = admin
kwargs = {}
if user is not None:
kwargs['user']=user
if password is not None:
kwargs['password']=password
if project is not None:
kwargs['project']=project
myclient = client.Client(host=hostname, sol005=True, **kwargs)
resp = myclient.vnfd.list()
print yaml.safe_dump(resp)