Skip to content

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             OSM NBI endpoint.  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:
  alarm-list                          list all alarms
  alarm-show                          show alarm details
  alarm-update                        Update a alarm
  app-create                          creates an App Instance
  app-delete                          deletes an App Instance cluster
  app-edit                            updates name or description of an App Instance
  app-list                            list all App instances
  app-profile-create                  creates an App Profile
  app-profile-delete                  deletes an App Profile
  app-profile-list                    list all App Profiles
  app-profile-show                    shows the details of an App Profile
  app-profile-update                  updates an App Profile
  app-show                            shows the details of an app instance
  app-update                          updates an App Instance
  attach-profile                      attaches profile to cluster
  cloud-account-add                   adds a new VIM account
  cloud-account-list                  list all VIM accounts
  cloud-account-remove                removes a VIM account
  cloud-account-show                  shows the details of a VIM account
  cloud-account-update                updates a VIM account
  cluster-create                      creates a K8s cluster
  cluster-delete                      deletes a K8s cluster
  cluster-deregister                  deregisters a K8s cluster
  cluster-edit                        updates name or description of a K8s cluster
  cluster-get-credentials             gets kubeconfig of a K8s cluster
  cluster-get-kubeconfig              gets kubeconfig of a K8s cluster
  cluster-list                        list all K8s clusters
  cluster-register                    registers a K8s cluster to OSM
  cluster-scale                       scales a K8s cluster
  cluster-show                        shows the details of a K8s cluster
  cluster-update                      updates the number of nodes, the version, the node size or the config of a K8s cluster
  cluster-upgrade                     changes the version of a K8s cluster
  descriptor-translate                Translate input descriptor file from Rel EIGHT OSM descriptors to SOL006 and prints in standard output
  detach-profile                      detaches profile from cluster
  infra-config-profile-create         creates an Infra Config Profile
  infra-config-profile-delete         deletes an Infra Config Profile
  infra-config-profile-list           list all Infra Config Profiles
  infra-config-profile-show           shows the details of an Infra Config Profile
  infra-config-profile-update         updates an Infra Config Profile
  infra-controller-profile-create     creates an Infra Controller Profile
  infra-controller-profile-delete     deletes an Infra Controller Profile
  infra-controller-profile-list       list all Infra Controller Profiles
  infra-controller-profile-show       shows the details of an Infra Controller Profile
  infra-controller-profile-update     updates an Infra Controller Profile
  install-completion                  print shell completion setup instructions
  k8scluster-add                      adds a K8s cluster to OSM
  k8scluster-delete                   removes a K8s cluster from OSM
  k8scluster-list                     list all K8s clusters
  k8scluster-remove                   removes a K8s cluster from OSM
  k8scluster-show                     shows the details of a K8s cluster
  k8scluster-update                   updates a K8s cluster
  ksu-create                          creates KSUs in OSM
  ksu-delete                          deletes one or several KSU
  ksu-list                            list all Kubernetes SW Units (KSU)
  ksu-show                            shows the details of a KSU
  ksu-update                          updates KSUs in OSM
  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-add                           uploads a new NF package to the catalog
  nfpkg-create                        uploads a new NF package to the catalog
  nfpkg-delete                        removes a NF package from the catalog
  nfpkg-list                          list all xNF packages (VNF, HNF, PNF)
  nfpkg-remove                        removes one or more NF packages from the catalog
  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 NS instances
  ns-heal                             heals (recreates) VNFs or VDUs of 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-cancel                        cancels an ongoing NS operation
  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
  ns-update                           executes an update of a Network Service.
  nsconfig-create                     creates a Ns config template
  nsconfig-delete                     deletes a Ns config template
  nsconfig-list                       list all NS Config Templates
  nsconfig-show                       shows the details of a Ns config template
  nsconfig-update                     update content of Ns config template
  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-add                           uploads a new NS package to the catalog
  nspkg-create                        uploads a new NS package to the catalog
  nspkg-delete                        removes a NS package from the catalog
  nspkg-list                          list all NS packages
  nspkg-remove                        removes one or more NS packages from the catalog
  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-add                             uploads a new Network Slice Template (NST)
  nst-create                          uploads a new Network Slice Template (NST)
  nst-delete                          removes a Network Slice Template (NST)
  nst-list                            list all Network Slice Templates (NST)
  nst-remove                          removes a Network Slice Template (NST)
  nst-show                            shows the content of a Network Slice Template (NST)
  nst-update                          updates a Network Slice Template (NST)
  oka-add                             adds an OSM Kubernetes Application (OKA)
  oka-delete                          deletes an OSM Kubernetes Application (OKA)
  oka-generate                        Generate OKA folder structure and files
  oka-list                            list all OSM Kubernetes Application (OKA)
  oka-show                            shows the details of an OKA
  oka-update                          updates an OSM Kubernetes Application (OKA)
  oka-update-content                  updates the content of an OKA
  package-build                       Build the tar.gz of the package
  package-create                      Create empty VNF or NS package structure
  package-translate                   Translate descriptors given a base directory
  package-validate                    Validate descriptors given a base directory
  pdu-add                             adds a new Physical Deployment Unit to the catalog
  pdu-create                          adds a new Physical Deployment Unit to the catalog
  pdu-delete                          removes a Physical Deployment Unit (PDU)
  pdu-list                            list all Physical Deployment Units (PDU)
  pdu-remove                          removes a Physical Deployment Unit (PDU)
  pdu-show                            shows the content of a Physical Deployment Unit (PDU)
  pdu-update                          updates a Physical Deployment Unit to the catalog
  profile-list                        list all Profiles
  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
  repo-delete                         removes a repo from OSM
  repo-index                          Index a repository from a folder with artifacts
  repo-list                           list all repos
  repo-remove                         removes a repo from OSM
  repo-show                           shows the details of a repo
  repo-update                         updates a repo in OSM
  resource-profile-create             creates an Resource Profile to OSM
  resource-profile-delete             deletes an Resource Profile
  resource-profile-list               list all Resource Profiles
  resource-profile-show               shows the details of an Resource Profile
  resource-profile-update             updates an Resource Profile
  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-add                            adds a new SDN controller
  sdnc-create                         adds a new SDN controller
  sdnc-delete                         removes an SDN controller
  sdnc-list                           list all SDN controllers
  sdnc-remove                         removes an SDN controller
  sdnc-show                           shows the details of an SDN controller
  sdnc-update                         updates an SDN controller
  subscription-create                 creates a new subscription to a specific event
  subscription-delete                 deletes a subscription
  subscription-list                   list all subscriptions
  subscription-show                   shows the details of a subscription
  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-reset-password                 Resetting a user's password
  user-show                           shows the details of a user
  user-update                         updates user information
  vca-add                             adds a VCA (Juju controller) to OSM
  vca-delete                          removes a VCA from OSM
  vca-list                            list VCAs
  vca-remove                          removes a VCA from OSM
  vca-show                            shows the details of a VCA
  vca-update                          updates a VCA
  version                             shows client and server versions
  vim-add                             adds a new VIM account
  vim-create                          adds a new VIM account
  vim-delete                          removes a VIM account
  vim-list                            list all VIM accounts
  vim-remove                          removes a VIM account
  vim-show                            shows the details of a VIM account
  vim-update                          updates a VIM account
  vnf-heal                            heals (recreates) a VNF instance or the VDUs of a VNF instance
  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 one or more 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-add                             adds a new WIM account
  wim-create                          adds a new WIM account
  wim-delete                          removes a WIM account
  wim-list                            list all WIM accounts
  wim-remove                          removes a WIM account
  wim-show                            shows the details of a WIM account
  wim-update                          updates a WIM account

How to install 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 in an Ubuntu 22.04 system, following the procedure below:

OSM_CLIENT_VERSION="v20.0"
OSM_IM_VERSION="v20.0"
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y python3 python3-setuptools python3-dev python3-pip
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y libmagic1
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y make
sudo -H python3 -m pip install -U pip
# Install OSM IM and its dependencies via pip
python3 -m pip install -r "https://osm.etsi.org/gitweb/?p=osm/IM.git;a=blob_plain;f=requirements.txt;hb=${OSM_IM_VERSION}"
# Path needs to include $HOME/.local/bin in order to use pyang
[ "$(which pyang)" = "$HOME/.local/bin/pyang" ] || export PATH=$HOME/.local/bin:${PATH}
python3 -m pip install "git+https://osm.etsi.org/gitlab/osm/IM.git@${OSM_IM_VERSION}#egg=osm-im" --upgrade
python3 -m pip install -r "https://osm.etsi.org/gitweb/?p=osm/osmclient.git;a=blob_plain;f=requirements.txt;hb=${OSM_CLIENT_VERSION}"
python3 -m pip install git+https://osm.etsi.org/gitlab/osm/osmclient.git@${OSM_CLIENT_VERSION}#egg=osmclient

How to install OSM Client in RHEL

# Install dependencies
sudo dnf upgrade -y
sudo dnf install -y libcurl-devel openssl-devel
sudo dnf install -y git wget make patch gcc
sudo dnf install -y python310 python310-devel

# Upgrade pip to the latest version (with sudo, to install it globally for all users)
sudo -H python3 -m pip install -U pip

# Decide which version to use
export OSM_CLIENT_VERSION=v20.0

# Install OSM IM and its dependencies via pip (installed with sudo, to install it globally for all users)
sudo -H python3 -m pip install -r "https://osm.etsi.org/gitweb/?p=osm/IM.git;a=blob_plain;f=requirements.txt;hb=${OSM_CLIENT_VERSION}"
sudo -H bash -c "PATH=$PATH:/usr/local/bin python3 -m pip install \"git+https://osm.etsi.org/gitlab/osm/IM.git@${OSM_CLIENT_VERSION}#egg=osm-im\" --upgrade"

# Clone osmclient repo and checkut the desired version
git clone https://osm.etsi.org/gitlab/osm/osmclient
git -C osmclient checkout ${OSM_CLIENT_VERSION}

# Install osmclient using pip
sudo -H python3 -m pip install -r osmclient/requirements.txt
sudo -H python3 -m pip install ./osmclient

# Install charm to be able to build OSM packages with charms
wget -O charm.sh "https://osm.etsi.org/gitweb/?p=osm/tests.git;a=blob;f=charm.sh;hb=${OSM_CLIENT_VERSION}"
sudo cp charm.sh /usr/sbin/charm
sudo chmod 755 /usr/sbin/charm

How to install OSM Client for developers in Ubuntu 22.04

# Install dependencies
sudo apt-get update
sudo apt-get install -y git wget make
sudo apt-get install -y python3 python3-setuptools python3-dev python3-pip

# Upgrade pip to the latest version (with sudo, to install it globally for all users)
sudo -H python3 -m pip install -U pip

# Decide which version to use
export OSM_CLIENT_VERSION=v20.0

# Install OSM IM and its dependencies via pip
python3 -m pip install -r "https://osm.etsi.org/gitweb/?p=osm/IM.git;a=blob_plain;f=requirements.txt;hb=${OSM_CLIENT_VERSION}"
python3 -m pip install "git+https://osm.etsi.org/gitlab/osm/IM.git@${OSM_CLIENT_VERSION}#egg=osm-im" --upgrade

# Clone osmclient repo and checkut the desired version
git clone https://osm.etsi.org/gitlab/osm/osmclient
cd osmclient
git checkout ${OSM_CLIENT_VERSION}

# Install osmclient directly from the repo for development purposes
python3 -m pip install --user -e osmclient -r osmclient/requirements.txt -r osmclient/requirements-dev.txt

# Logout and login so that PATH can be updated. Executable osm will be found in /home/ubuntu/.local/bin
which osm

How to install OSM Client in Windows with WSL

OSM client can be easily installed in Windows by installing an Ubuntu distro on Linux with Windows Subsystem for Linux (WSL).

Once WSL is installed with an Ubuntu 22.04 distro, you can install OSM following the instruccions in (#how-to-install-osm-client-in-ubuntu-2204)

How to install OSM Client directly in Windows with Conda and Git

OSM can also be installed in Windows with Miniconda and Git

You can install both programs with Chocolatey, the package manager for Windows. Open a CMD window and run the following commands:

choco install -y git make wget
choco install -y miniconda3

Then, open Windows environment variables > User environment variables, and add the following entries to the Path user environment variable in order to make Conda executables reachable from all terminals:

  • C:\tools\miniconda3
  • C:\tools\miniconda3\Scripts
  • C:\tools\miniconda3\Library\bin

Make sure that aliases for Python are disabled in Windows Configuration. Go to Settings > Apps > Apps & features, and click on "Manage app execution aliases". Then disable aliases for Python.

Open Git Bash and run the following commands to create a Conda environment with Python 3.8 and initialize all shells to work with Conda:

conda create -n osm-env python=3.10
conda init --all
# Logout

Then install OSM client as follows:

# Install conda and install some packages via conda (which will install dependent libraries)
conda activate osm-env

# Upgrade pip to the latest version (with sudo, to install it globally for all users)
python -m pip install -U pip

# Decide which version to use
export OSM_CLIENT_VERSION=v20.0

# Clone IM repo and checkut the desired version
git clone https://osm.etsi.org/gitlab/osm/IM
git -C IM checkout ${OSM_CLIENT_VERSION}

# Install OSM IM using pip
python -m pip install -r IM/requirements.txt
# make -C IM clean
python -m pip install ./IM

# Clone osmclient repo and checkut the desired version
git clone https://osm.etsi.org/gitlab/osm/osmclient
git -C osmclient checkout ${OSM_CLIENT_VERSION}

# Install osmclient using pip
python -m pip install -r osmclient/requirements.txt
# Required DLLs for python-magic
python -m pip install python-magic-bin
python -m pip install ./osmclient

# Try OSM client
python -m osmclient.scripts.osm
# Logout from Git Bash

Open Git Bash again and edit .bash_profile to activate the Conda environment persistently. If desired, add an alias to osm executable:

conda activate osm-env
alias 'osm=python -m osmclient.scripts.osm'

That will complete OSM client installation for Windows.

Getting help

Options -h or --helpcan 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             OSM NBI endpoint.  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 cloud-account-add -h
Usage: osm cloud-account-add [OPTIONS]

  adds 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.

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.

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.

Shell tab completion

The osm CLI supports tab completion for commands, subcommands, options, and resource names in bash and zsh.

Run osm install-completion to print setup instructions for the detected shell. Then add one of the following snippets to your shell profile:

bash — add to ~/.bashrc:

# Option 1: eval-based (always reflects the installed version)
eval "$(_OSM_COMPLETE=bash_source osm)"

# Option 2: file-based (faster shell startup)
_OSM_COMPLETE=bash_source osm > ~/.osm-complete.bash
source ~/.osm-complete.bash

zsh — add to ~/.zshrc:

# Option 1: eval-based (always reflects the installed version)
eval "$(_OSM_COMPLETE=zsh_source osm)"

# Option 2: file-based (faster shell startup)
_OSM_COMPLETE=zsh_source osm > ~/.osm-complete.zsh
source ~/.osm-complete.zsh

After adding the snippet, reload your shell (source ~/.bashrc or source ~/.zshrc) or open a new terminal.

Dynamic completion of resource names (for example, completing NS instance names or cluster names) requires OSM_HOSTNAME to be set.

RBAC

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.

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.

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 repo
  • osm nfpkg-repo-listand osm nspkg-repo-list: lists NF/NS packages from OSM repositories
  • osm nfpkg-repo-show|nspkg-repo-show --repo <REPO_NAME>: shows a specific NF/NS package in a repo
  • osm 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.etsi.org/vnf-catalog/Stable
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.

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 package
  • osm package-validate PKG_FOLDER: validates descriptors given a base directory
  • osm 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.

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.

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>

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.

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

Bulk delete

The following commands accept multiple names or IDs in a single invocation, sending a single API request to OSM:

  • ns-delete: deletes multiple NS instances in one call (up to 25). Each instance is processed independently; a failure on one does not prevent the others from being processed. With --force (sent as the FORCE query string), the instances are removed immediately without running the termination, as with the single-instance --force; it requires the same permission as forcing the deletion of a single instance (force:delete).
osm ns-delete <name-or-id-1> <name-or-id-2> ...
  • nspkg-remove (or its alias nspkg-delete): removes multiple NS packages (NSD) in one call.
osm nspkg-remove <name-or-id-1> <name-or-id-2> ...
  • nfpkg-remove (or its aliases nfpkg-delete and vnfpkg-delete): removes multiple VNF packages (VNFD) in one call.
osm nfpkg-remove <name-or-id-1> <name-or-id-2> ...

The result of each item is printed (Accepted/Deleted or the error), and the command exits with an error if any item failed. --force is not supported when deleting several packages. The legacy commands vnfd-delete and nsd-delete accept a single package only. All names or IDs are resolved before anything is deleted, so an unknown name aborts the whole command.

The REST endpoints (POST /nslcm/v1/ns_instances_delete, POST /vnfpkgm/v1/vnf_packages_delete and POST /nsd/v1/ns_descriptors_delete) return a results list with the status of each ID. Although they are POST requests, they require the same permission as deleting a single item (ns_instances:id:delete, vnfds:id:delete and nsds:id:delete), so a role that can only create these resources cannot delete them through the bulk endpoints.

Aliases

The following are command aliases with identical behaviour:

  • For registering or uploading existing resources, the preferred verbs are add/register and remove, since these operations manage references to existing resources rather than creating or destroying them. The previous create/delete names are kept as backward-compatible aliases. The preferred commands are:
  • vim-add (alias vim-create): adds a new VIM account
  • vim-remove (alias vim-delete): removes a VIM account
  • wim-add (alias wim-create): adds a new WIM account
  • wim-remove (alias wim-delete): removes a WIM account
  • sdnc-add (alias sdnc-create): adds a new SDN controller
  • sdnc-remove (alias sdnc-delete): removes an SDN controller
  • pdu-add (alias pdu-create): adds a new Physical Deployment Unit to the catalog
  • pdu-remove (alias pdu-delete): removes a Physical Deployment Unit (PDU)
  • k8scluster-remove (alias k8scluster-delete): removes a K8s cluster from OSM (legacy API)
  • repo-remove (alias repo-delete): removes a repo from OSM
  • vca-remove (alias vca-delete): removes a VCA from OSM
  • For VIM accounts, the cloud-account-* commands are aliases of the vim-* ones, since the same command manages any type of cloud account (VIM or Kubernetes cluster provider):
  • vim-add|vim-create|cloud-account-add: adds a new VIM account
  • vim-remove|vim-delete|cloud-account-remove: removes a VIM account
  • vim-list|cloud-account-list: list all VIM accounts
  • vim-show|cloud-account-show: shows the details of a VIM account
  • vim-update|cloud-account-update: updates a VIM account
  • For CRUD operations over NF packages, there are different command aliases. The preferred commands are nfpkg-add/nfpkg-remove and nfpkg-* for the rest. The commands nfpkg-create/nfpkg-delete and vnfd-* might be deprecated in the future.
  • nfpkg-add|nfpkg-create|vnfpkg-create|vnfd-create: uploads a new NF package to the catalog
  • nfpkg-remove|nfpkg-delete|vnfpkg-delete|vnfd-delete: removes a NF package from the catalog
  • nfpkg-list|vnfpkg-list|vnfd-list: list all xNF packages (VNF, HNF, PNF)
  • nfpkg-show|vnfpkg-show|vnfd-show: shows the details of a NF package
  • nfpkg-update|vnfpkg-update|vnfd-update: updates a NFpkg
  • For CRUD operations over NS packages, there are different command aliases. The preferred commands are nspkg-add/nspkg-remove and nspkg-* for the rest. The commands nspkg-create/nspkg-delete and nsd-* might be deprecated in the future.
  • nspkg-add|nsd-create|nspkg-create: uploads a new NS package to the catalog
  • nspkg-remove|nsd-delete|nspkg-delete: removes a NS package from the catalog
  • nsd-list|nspkg-list: list all NS packages
  • nsd-show|nspkg-show: shows the details of a NS package
  • nsd-update|nspkg-update: updates a NSD/NSpkg
  • For CRUD operations over Network Slice Templates, the following command aliases exist. The preferred commands are nst-add/nst-remove:
  • nst-add|nst-create|netslice-template-create: uploads a new Network Slice Template (NST)
  • nst-remove|nst-delete|netslice-template-delete: removes 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 Instance
  • netslice-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 repositories
  • nfpkg-repo-show|vnfpkg-repo-show: shows the details of a NF package in an OSM repository
  • nsd-repo-list|nspkg-list: list all NS from OSM repositories
  • nsd-repo-show|nspkg-show: shows the details of a NS package in an OSM repository

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

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.

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)
resp = myclient.nsd.list()
print yaml.safe_dump(resp)

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)

Kubernetes cluster management

OSM can create and manage Kubernetes clusters through cloud accounts (VIM accounts). These commands use the declarative orchestration pipeline and are distinct from the legacy k8scluster-* commands, which register pre-existing clusters.

cluster-create

Creates a new K8s cluster via a VIM account.

osm cluster-create [OPTIONS] NAME

Options:
  -n, --node-count INTEGER    number of worker nodes  [required]
  --node-size TEXT            size / flavour of worker nodes  [required]
  --version TEXT              Kubernetes version  [required]
  --vim-account TEXT          VIM / cloud account  [required]
  --description TEXT          human readable description
  --region-name TEXT          region in the VIM account
  --resource-group TEXT       resource group in the VIM account
  --bootstrap / --no-bootstrap  bootstrap with Flux for GitOps (default: True)
  --config TEXT               cluster-specific YAML configuration (inline)
  --config_file PATH          cluster-specific YAML configuration file

Example:

osm cluster-create my-cluster \
  --node-count 3 \
  --node-size m1.medium \
  --version 1.29 \
  --vim-account my-openstack

cluster-register

Registers an existing cluster (already running, not created by OSM) by providing its kubeconfig.

osm cluster-register [OPTIONS] NAME

Options:
  --vim-account TEXT          VIM / cloud account  [required]
  --creds PATH                path to a valid kubeconfig file  [required]
  --description TEXT          human readable description
  --bootstrap / --no-bootstrap  bootstrap with Flux for GitOps (default: True)
  --openshift                 flag for OpenShift-based clusters

cluster-list / cluster-show

osm cluster-list [--filter EXPR] [-o FORMAT]
osm cluster-show NAME [-o FORMAT]

cluster-scale / cluster-upgrade / cluster-update / cluster-edit

osm cluster-scale  NAME -n NODE_COUNT
osm cluster-upgrade NAME --version K8S_VERSION
osm cluster-update  NAME [--version K8S_VERSION] [-n NODE_COUNT] [--node-size SIZE] [--config YAML | --config_file PATH]
osm cluster-edit    NAME [--newname NAME] [--description TEXT]

cluster-update --config / --config_file accept a YAML configuration, for instance capi-openstack: {security-group-id: <SG_UUID>} or capi-openstack: {security-group-name: <SG_NAME>} to set an additional Network Security Group on the VMs of an OpenStack (CAPI) cluster. The two options are mutually exclusive.

cluster-get-credentials

Prints the kubeconfig for a cluster (also available as cluster-get-kubeconfig).

osm cluster-get-credentials NAME

cluster-deregister / cluster-delete

osm cluster-deregister NAME [--force]   # removes from OSM, leaves cloud resources
osm cluster-delete     NAME [--force]   # removes from OSM and destroys cloud resources

OSM Kubernetes Applications (OKA)

An OKA is a reusable Helm-chart-based application blueprint stored in the OSM software catalog. OKAs are the building blocks that KSUs and App Instances deploy.

oka-generate

Scaffolds an OKA folder structure locally before uploading.

osm oka-generate [OPTIONS] NAME

Options:
  --base-directory PATH       base location for the OKA folder (default: ".")
  --profile-type CHOICE       app-profile | infra-controller-profile |
                              infra-config-profile | resource-profile
                              (default: app-profile)
  --helm-repo-name TEXT       Helm repository name  [required]
  --helm-repo-url TEXT        Helm repository URL  [required]
  --helm-chart TEXT           Helm chart name  [required]
  --version TEXT              chart version (default: latest)
  --namespace TEXT            default deployment namespace  [required]

oka-add

Uploads a local OKA folder or tar.gz to OSM.

osm oka-add [OPTIONS] NAME PATH

Options:
  --profile-type CHOICE       app-profile | infra-controller-profile |
                              infra-config-profile | resource-profile
  --description TEXT

oka-list / oka-show

osm oka-list [--filter EXPR] [-o FORMAT]
osm oka-show NAME [-o FORMAT]

oka-update / oka-update-content

osm oka-update       NAME [--newname NAME] [--description TEXT]
osm oka-update-content NAME PATH   # replace the OKA content with a new folder/tar.gz

oka-delete

osm oka-delete NAME [--force]

K8s Service Units (KSU)

A KSU defines a deployment of one or more OKAs onto a cluster, parameterised with a profile. KSUs are the primary mechanism for deploying applications via the declarative pipeline.

ksu-create

osm ksu-create [OPTIONS] NAME

Options:
  --description TEXT
  --cluster TEXT              target K8s cluster name or ID
  (KSU composition is provided via YAML file; see ksu-show for the data model)

ksu-list / ksu-show

osm ksu-list [--filter EXPR] [-o FORMAT]
osm ksu-show NAME [-o FORMAT]

ksu-update

osm ksu-update NAME [OPTIONS]

ksu-delete

osm ksu-delete NAME [--force]

App Instances

App Instances are lightweight deployments of a single OKA, created directly from an OKA without a KSU. They are intended for simple, single-application deployments.

app-create

osm app-create [OPTIONS] NAME

Options:
  --description TEXT
  --oka TEXT                  OKA name or ID to deploy
  --sw-catalog-path TEXT      software catalog path (alternative to --oka)

app-list / app-show

osm app-list [--filter EXPR] [-o FORMAT]
osm app-show NAME [-o FORMAT]

app-update / app-edit

osm app-update NAME [--model YAML_FILE] [--params YAML_FILE]
osm app-edit   NAME [--newname NAME] [--description TEXT]

app-delete

osm app-delete NAME [--force]

Profile management

Profiles parameterise how OKAs are deployed on clusters. There are four profile types:

Type Purpose
app-profile Application-level values and configuration
infra-controller-profile Infrastructure controller settings (e.g. ingress)
infra-config-profile Infrastructure configuration (e.g. network policies)
resource-profile Resource limits and requests

All four types share the same CRUD command pattern:

osm <type>-create NAME [--description TEXT]
osm <type>-delete NAME [--force]
osm <type>-list   [--filter EXPR] [-o FORMAT]
osm <type>-show   NAME [-o FORMAT]
osm <type>-update NAME [--newname NAME] [--description TEXT]

Where <type> is one of: app-profile, infra-config-profile, infra-controller-profile, resource-profile.

profile-list

Lists all profiles of all types in a single table.

osm profile-list [--filter EXPR]

attach-profile / detach-profile

Associates or dissociates a profile with a cluster so that KSUs deployed on that cluster inherit the profile settings.

osm attach-profile PROFILE CLUSTER --profile-type CHOICE
osm detach-profile PROFILE CLUSTER --profile-type CHOICE

Where --profile-type is one of: app-profile, infra-config-profile, infra-controller-profile, resource-profile.

Example:

osm attach-profile my-app-profile my-cluster --profile-type app-profile

VCA management

VCA (VNF Configuration and Abstraction) refers to Juju controllers used for VNF configuration in NFV scenarios.

osm vca-add    NAME --endpoints HOST1,HOST2 --user USER --secret SECRET \
               --cacert CACERT_FILE [--description TEXT]
osm vca-update NAME [--endpoints HOSTS] [--user USER] [--secret SECRET]
               [--newname NAME] [--description TEXT]
osm vca-remove NAME [--force]   # vca-delete is kept as a backward-compatible alias
osm vca-list   [--filter EXPR]
osm vca-show   NAME [--literal]

Alarm management

Alarms monitor NS and VNF metrics and trigger notifications when thresholds are crossed.

osm alarm-list  [--filter EXPR]
osm alarm-show  ALARM_ID
osm alarm-update ALARM_ID [--threshold VALUE] [--is-enabled BOOL]

Note: To create an alarm, use osm ns-alarm-create (associated with a specific NS instance).

NS healing

Healing triggers recovery of failed VDUs or VNFs within a Network Service.

osm ns-heal  NS_NAME [OPTIONS]
osm vnf-heal NS_NAME [--vnf-name VNF_NAME] [OPTIONS]

NS update

Updates the configuration of a running NS instance.

osm ns-update NS_NAME [OPTIONS]

NS configuration (nsconfig)

NS configurations store persistent configuration overrides for NS instances.

osm nsconfig-create NAME [--description TEXT]
osm nsconfig-delete NAME [--force]
osm nsconfig-list   [--filter EXPR] [-o FORMAT]
osm nsconfig-show   NAME [-o FORMAT]
osm nsconfig-update NAME [OPTIONS]

Subscriptions

Subscriptions allow external systems to receive event notifications for NS lifecycle operations.

osm subscription-create [OPTIONS]   # event type: ns
osm subscription-delete NAME
osm subscription-list   [--filter EXPR]
osm subscription-show   NAME

User password reset

osm user-reset-password USERNAME

Package translation

Translates a VNF/NS package or descriptor between different format versions.

osm package-translate PKG_FOLDER_OR_FILE
osm descriptor-translate DESCRIPTOR_FILE