OSM Hands-On Tutorial

This tutorial provides a comprehensive walkthrough of OSM’s capabilities, covering both the declarative cloud-native and imperative NFV operational tracks. It is based on the OSM tutorial presented at SNS4SNS 2026.

Prerequisites:

• A running OSM installation. See Getting Started.

• The osm CLI configured with OSM_HOSTNAME pointing to your OSM NBI endpoint.

• A VIM/Cloud account registered in OSM.

export OSM_HOSTNAME=$(kubectl get -n osm -o jsonpath="{.spec.rules[0].host}" ingress nbi-ingress)

---

Part 1: Cloud-Native Operations

This part demonstrates OSM’s declarative GitOps framework for managing Kubernetes clusters and applications.

1.1 Register a Cloud Account

Before creating clusters, register a cloud account (VIM) in OSM. The example below uses Azure:

osm vim-create --name azure-site --account_type azure \
    --auth_url http://www.azure.com \
    --user "$AZURE_CLIENT_ID" --password "$AZURE_SECRET" --tenant "$AZURE_TENANT" \
    --description "Azure cloud account" \
    --creds ~/vims/azure-credentials.json \
    --config "{region_name: westeurope, resource_group: 'osmRG', subscription_id: '$AZURE_SUBSCRIPTION_ID', vnet_name: 'osm', flavors_pattern: '^Standard'}"

For other cloud providers, see Managing VIM Accounts.

1.2 Create a Kubernetes Cluster

Create a managed Kubernetes cluster on your registered cloud account:

osm cluster-create --name my-cluster \
    --vim azure-site \
    --k8s_version 1.28 \
    --node_count 3

Monitor the cluster status until it reaches READY:

osm cluster-list
osm cluster-show my-cluster

OSM orchestrates the cluster creation by submitting an ArgoWorkflow to the management cluster. The workflow provisions the cluster via the cloud provider API and commits the cluster configuration to the fleet-osm Git repository. FluxCD then bootstraps FluxCD on the workload cluster.

1.3 Deploy an Application with an OKA Package

An OKA Package is a simple blueprint for a single Kubernetes application. The following example deploys a Jenkins instance using a pre-built OKA from the NF Catalog:

# Onboard the OKA package
osm oka-create jenkins apps/jenkins.tar.gz

# Instantiate it as a KSU on the cluster
osm ksu-create --name jenkins-instance \
    --oka jenkins \
    --cluster my-cluster

The KSU creation commits the Jenkins manifests to fleet-osm. FluxCD on the workload cluster applies them, and after a few moments Jenkins is running:

osm ksu-list
osm ksu-show jenkins-instance

1.4 Deploy a Multi-Component App

For complex applications with multiple interdependent components, use an App Package. The following example deploys a multi-component application:

# Onboard the App package
osm app-pkg-create my-app my-app-package.tar.gz

# Create an App Instance on the cluster
osm app-create --name my-app-instance \
    --app-pkg my-app \
    --cluster my-cluster \
    --config '{"replicas": 2, "region": "westeurope"}'

OSM creates one KSU Instance per component in the App Package, in the correct dependency order. Monitor the App Instance:

osm app-list
osm app-show my-app-instance

Understanding the App Instance Model

When you create an App Instance, OSM builds the following hierarchy:

App Instance (my-app-instance)
├── KSU Instance: frontend  → committed to fleet-osm → applied by FluxCD
├── KSU Instance: backend   → committed to fleet-osm → applied by FluxCD
└── KSU Instance: database  → committed to fleet-osm → applied by FluxCD

Each KSU Instance is composed of Bricks — the individual Kubernetes resources (Deployments, Services, ConfigMaps) that FluxCD applies to the workload cluster.

1.5 Assign a Profile to Multiple Clusters

A Profile defines a set of KSUs to be deployed uniformly to a fleet of clusters. Profiles are ideal for deploying a consistent software baseline (monitoring agents, security tools, platform services) across many clusters at once.

# Create a profile from the catalog
osm profile-create --name monitoring-baseline \
    --vim azure-site

# Assign the profile to multiple clusters
osm cluster-update my-cluster --profile monitoring-baseline
osm cluster-update my-cluster-2 --profile monitoring-baseline

OSM commits the profile assignment to fleet-osm, and FluxCD synchronises the KSUs to all assigned clusters.

---

Part 2: NFV Operations

This part demonstrates OSM’s imperative NFV orchestration for managing Virtual Network Functions and Network Services.

2.1 Upload a VM Image to the VIM

NFV deployments require a VM image to be available in the VIM. Upload an Ubuntu image to OpenStack:

openstack image create \
    --file ./focal-server-cloudimg-amd64.img \
    --container-format bare \
    --disk-format qcow2 \
    ubuntu20.04

2.2 Onboard a VNF Package

Download a VNF package from the OSM NF Catalog and onboard it:

# Clone the OSM packages repository
git clone https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages.git

# Onboard the VNF package
osm nfpkg-create osm-packages/hackfest_basic_vnf.tar.gz
osm nfpkg-list

2.3 Onboard an NS Package

osm nspkg-create osm-packages/hackfest_basic_ns.tar.gz
osm nspkg-list

2.4 Instantiate a Network Service

osm ns-create \
    --ns_name my-first-ns \
    --nsd_name hackfest_basic-ns \
    --vim_account openstack-site

# Monitor until READY
osm ns-list
osm ns-show my-first-ns

2.5 Day-2 Operations: Scaling

Scale a VNF instance in the running Network Service:

osm ns-action my-first-ns \
    --vnf_name hackfest_basic-vnf \
    --action scale-out

2.6 Terminate the Network Service

osm ns-delete my-first-ns

---

What’s Next?

• Explore the full Cloud-Native Operations guide for advanced cluster management.

• Read Core Concepts for a deeper understanding of OKA Packages, App Packages, and the App Instance Model.

• Browse the NF Catalog for ready-to-use blueprints.

• Check the NFV Operations guide for advanced NS and VNF lifecycle management.