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:
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:
alarm-list list alarms
alarm-show shows the details of an alarm
alarm-update updates an alarm threshold or state
app-create creates an App Instance
app-delete deletes an App Instance
app-edit updates name or description of an App Instance
app-list list all App Instances
app-profile-create creates an App Profile (OKA blueprint)
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 a profile to a K8s cluster
cluster-create creates a K8s cluster
cluster-delete deletes a K8s cluster
cluster-deregister deregisters a K8s cluster from OSM
cluster-edit updates name or description of a K8s cluster
cluster-get-credentials gets the kubeconfig of a K8s cluster
cluster-get-kubeconfig alias for cluster-get-credentials
cluster-list list all K8s clusters
cluster-register registers an existing K8s cluster to OSM
cluster-scale scales the number of nodes of a K8s cluster
cluster-show shows the details of a K8s cluster
cluster-update updates node count, version or size of a K8s cluster
cluster-upgrade changes the Kubernetes version of a K8s cluster
descriptor-translate translates a descriptor to a different format
detach-profile detaches a profile from a K8s cluster
infra-config-profile-create creates an Infrastructure Configuration Profile
infra-config-profile-delete deletes an Infrastructure Configuration Profile
infra-config-profile-list list all Infrastructure Configuration Profiles
infra-config-profile-show shows the details of an Infrastructure Configuration Profile
infra-config-profile-update updates an Infrastructure Configuration Profile
infra-controller-profile-create creates an Infrastructure Controller Profile
infra-controller-profile-delete deletes an Infrastructure Controller Profile
infra-controller-profile-list list all Infrastructure Controller Profiles
infra-controller-profile-show shows the details of an Infrastructure Controller Profile
infra-controller-profile-update updates an Infrastructure Controller Profile
k8scluster-add adds an existing K8s cluster to OSM (legacy)
k8scluster-delete removes a K8s cluster from OSM (legacy) (alias of k8scluster-remove)
k8scluster-list list all K8s clusters registered via legacy API
k8scluster-remove removes a K8s cluster from OSM (legacy)
k8scluster-show shows the details of a K8s cluster (legacy)
k8scluster-update updates a K8s cluster (legacy)
ksu-create creates a K8s Service Unit (KSU)
ksu-delete deletes a K8s Service Unit (KSU)
ksu-list list all K8s Service Units (KSUs)
ksu-show shows the details of a KSU
ksu-update updates a KSU
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 NSI
netslice-instance-op-show shows the info of an operation over a 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 (alias of nfpkg-add)
nfpkg-delete removes a NF package from the catalog (alias of nfpkg-remove)
nfpkg-list list all xNF packages (VNF, HNF, PNF)
nfpkg-remove removes a NF package 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 a NS instance
ns-heal triggers healing of a NS instance
ns-list list all NS instances
ns-metric-export exports a metric to the internal OSM bus
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 updates a NS instance
nsconfig-create creates a NS configuration
nsconfig-delete deletes a NS configuration
nsconfig-list list all NS configurations
nsconfig-show shows the details of a NS configuration
nsconfig-update updates a NS configuration
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 NSI
nsi-op-show shows the info of an operation over a 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 (alias of nspkg-add)
nspkg-delete removes a NS package from the catalog (alias of nspkg-remove)
nspkg-list list all NS packages
nspkg-remove removes a NS package 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) (alias of nst-add)
nst-delete removes a Network Slice Template (NST) (alias of nst-remove)
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) to OSM
oka-delete deletes an OKA from OSM
oka-generate generates an OKA folder structure and template files
oka-list list all OKAs
oka-show shows the details of an OKA
oka-update updates name or description of an OKA
oka-update-content updates the content (files) of an OKA
package-build builds the tar.gz of a package
package-create creates a package descriptor scaffold
package-translate translates a package to a different format
package-validate validates a package descriptor
pdu-add adds a new Physical Deployment Unit to the catalog
pdu-create adds a new Physical Deployment Unit to the catalog (alias of pdu-add)
pdu-delete removes a Physical Deployment Unit (PDU) (alias of pdu-remove)
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 (PDU)
profile-list list all profiles (all types)
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
repo-add adds a repo to OSM
repo-delete removes a repo from OSM (alias of repo-remove)
repo-index generates a repo index from a folder of packages
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 a Resource Profile
resource-profile-delete deletes a Resource Profile
resource-profile-list list all Resource Profiles
resource-profile-show shows the details of a Resource Profile
resource-profile-update updates a Resource Profile
role-create creates a new role
role-delete deletes a role
role-list list all roles
role-show shows the details of a specific role
role-update updates a role
sdnc-add adds a new SDN controller
sdnc-create adds a new SDN controller (alias of sdnc-add)
sdnc-delete removes an SDN controller (alias of sdnc-remove)
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 subscription to NS lifecycle events
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 resets the password of a user
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 (alias of vca-remove)
vca-list list all VCAs
vca-remove removes a VCA from OSM
vca-show shows the details of a VCA
vca-update updates a VCA
version shows OSM client and server versions
vim-add adds a new VIM account
vim-create adds a new VIM account (alias of vim-add)
vim-delete removes a VIM account (alias of vim-remove)
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 triggers healing 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 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-add adds a new WIM account
wim-create adds a new WIM account (alias of wim-add)
wim-delete removes a WIM account (alias of wim-remove)
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¶
How to install OSM Client in Ubuntu 22.04 (RECOMMENDED)¶
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="v19.0"
OSM_IM_VERSION="v19.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=v19.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=v19.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:
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\miniconda3C:\tools\miniconda3\ScriptsC:\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:
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=v19.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:
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 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.
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:
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.
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_USEROSM_PASSWORDOSM_PROJECTOSM_PROJECT_DOMAIN_NAMEOSM_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 repoosm nfpkg-repo-listandosm 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.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 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.
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:
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
Aliases¶
The following are command aliases with identical behaviour:
- For registering or uploading existing resources, the preferred verbs are
add/registerandremove, since these operations manage references to existing resources rather than creating or destroying them. The previouscreate/deletenames are kept as backward-compatible aliases. The preferred commands are: vim-add(aliasvim-create): adds a new VIM accountvim-remove(aliasvim-delete): removes a VIM accountwim-add(aliaswim-create): adds a new WIM accountwim-remove(aliaswim-delete): removes a WIM accountsdnc-add(aliassdnc-create): adds a new SDN controllersdnc-remove(aliassdnc-delete): removes an SDN controllerpdu-add(aliaspdu-create): adds a new Physical Deployment Unit to the catalogpdu-remove(aliaspdu-delete): removes a Physical Deployment Unit (PDU)k8scluster-remove(aliask8scluster-delete): removes a K8s cluster from OSM (legacy API)repo-remove(aliasrepo-delete): removes a repo from OSMvca-remove(aliasvca-delete): removes a VCA from OSM- For CRUD operations over NF packages, there are different command aliases. The preferred commands are
nfpkg-add/nfpkg-removeandnfpkg-*for the rest. The commandsnfpkg-create/nfpkg-deleteandvnfd-*might be deprecated in the future. nfpkg-add|nfpkg-create|vnfpkg-create|vnfd-create: uploads a new NF package to the catalognfpkg-remove|nfpkg-delete|vnfpkg-delete|vnfd-delete: removes a NF package from the catalognfpkg-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 are
nspkg-add/nspkg-removeandnspkg-*for the rest. The commandsnspkg-create/nspkg-deleteandnsd-*might be deprecated in the future. nspkg-add|nsd-create|nspkg-create: uploads a new NS package to the catalognspkg-remove|nsd-delete|nspkg-delete: removes a NS package from the catalognsd-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. 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 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
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:
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¶
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]
osm cluster-edit NAME [--newname NAME] [--description TEXT]
cluster-get-credentials¶
Prints the kubeconfig for a cluster (also available as cluster-get-kubeconfig).
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¶
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¶
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¶
ksu-update¶
ksu-delete¶
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¶
app-update / app-edit¶
osm app-update NAME [--model YAML_FILE] [--params YAML_FILE]
osm app-edit NAME [--newname NAME] [--description TEXT]
app-delete¶
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.
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:
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.
NS update¶
Updates the configuration of a running NS instance.
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¶
Package translation¶
Translates a VNF/NS package or descriptor between different format versions.