# 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](../getting-started/quickstart.md).
- The `osm` CLI configured with `OSM_HOSTNAME` pointing to your OSM NBI endpoint.
- A VIM/Cloud account registered in OSM.

```bash
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:

```bash
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](../how-to/managing-vim-accounts.md).

### 1.2 Create a Kubernetes Cluster

Create a managed Kubernetes cluster on your registered cloud account:

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

Monitor the cluster status until it reaches `READY`:

```bash
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:

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
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.

```bash
# 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:

```bash
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:

```bash
# 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

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

### 2.4 Instantiate a Network Service

```bash
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:

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

### 2.6 Terminate the Network Service

```bash
osm ns-delete my-first-ns
```

---

## What's Next?

- Explore the full [Cloud-Native Operations](../how-to/cloud-native-index.html) guide for advanced cluster management.
- Read [Core Concepts](../explanation/core-concepts.md) for a deeper understanding of OKA Packages, App Packages, and the App Instance Model.
- Browse the [NF Catalog](https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages) for ready-to-use blueprints.
- Check the [NFV Operations](../how-to/nfv/index.html) guide for advanced NS and VNF lifecycle management.