README.md

# README

## Cloning the repo

You need to clone the repo with the option "--recursive" to fetch all the dependent git modules:

```bash
# Clone with SSH
git clone --recursive ssh://git@osm.etsi.org:29419/vnf-onboarding/osm-packages.git
# Clone with HTTPS
git clone --recursive https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages.git
```

## Structure of the repo

This repo contains OSM packages used for testing and for the hackfest.

There is typically a folder for each VNF under test and NS to run the test, for instance:

- `hackfest_basic_vnf`: the VNF package to run the hackfest basic test
- `hackfest_basic_ns`: the NS package to run the hackfest basic test

Please use the following conventions:

- VNF folders should end with "_vnf"
- NS folders should end with "_ns"

Charm sources must be stored in the folder of the package, in `charms/layers` folder. If relations are in place, the charm interfaces must be stored in `charms/interfaces` folder.

Thanks to the new way for building and generating packages, charms sources can be placed directly in the package folder, under `charms/layers/` folder, thus simplifying the structure. When building the package, the charm will be built and only the binaries will be placed in the tar.gz file.

## Working with packages

Osmclient has been improved so that all utilities required to validate and build the packages have been
added. Now the single `osm` command line client is able to do everything you need to work with VNF and
NS packages.

### Uploading a package from a folder

This is by far the simplest way of working. The following command will validate the package,
build the charm from source if it exists under `PKGFOLDER/charms/layers`, build the tar.gz,
and onboard/upload it to OSM.

```bash
osm nfpkg-create PKGFOLDER
```

For NS packages, the same applies.

```bash
osm nspkg-create PKGFOLDER
```

Full help for both commands is show below:

```bash
$ osm nfpkg-create --help
Usage: osm nfpkg-create [OPTIONS] FILENAME

  onboards a new NFpkg (alias of nfpkg-create)

  FILENAME: NF Package tar.gz file, NF Descriptor YAML file or NF Package folder
            If FILENAME is a file (NF Package tar.gz or NF Descriptor YAML), it is onboarded.
            If FILENAME is an NF Package folder, it is built and then onboarded.

Options:
  --overwrite TEXT     Deprecated. Use override
  --override TEXT      overrides fields in descriptor, format: "key1.key2...=value[;key3...=value;...]"
  --skip-charm-build   The charm will not be compiled, it is assumed to already exist
  --override-epa       adds guest-epa parameters to all VDU
  --override-nonepa    removes all guest-epa parameters from all VDU
  --override-paravirt  overrides all VDU interfaces to PARAVIRT
  -h, --help           Show this message and exit.
```

```bash
$ osm nspkg-create --help
Usage: osm nspkg-create [OPTIONS] FILENAME

  onboards a new NSpkg

  FILENAME: NF Package tar.gz file, NF Descriptor YAML file or NF Package folder
            If FILENAME is a file (NF Package tar.gz or NF Descriptor YAML), it is onboarded.
            If FILENAME is an NF Package folder, it is built and then onboarded.

Options:
  --overwrite TEXT    Deprecated. Use override
  --override TEXT     overrides fields in descriptor, format: "key1.key2...=value[;key3...=value;...]"
  --skip-charm-build  The charm will not be compiled, it is assumed to already exist
  -h, --help          Show this message and exit.
```

### Validating a descriptor

The following command will look for all the descriptor files in a folder and validate them

```bash
osm package-validate PKGFOLDER
```

Some relevant options are shown below:

```bash
$ osm package-validate --help
Usage: osm package-validate [OPTIONS] [BASE_DIRECTORY]

  Validate descriptors given a base directory.

  BASE_DIRECTORY: Stub folder for NS, VNF or NST package.

Options:
  --recursive / --no-recursive  The activated recursive option will validate the yaml files within the indicated directory and in its subdirectories
  -h, --help                    Show this message and exit.
```

### Building a package

The following command will validate and build the tar.gz file. It will als

```bash
osm package-build PKGFOLDER
```

Some relevant options are shown below:

```bash
$ osm package-build --help
Usage: osm package-build [OPTIONS] PACKAGE_FOLDER

  Build the package NS, VNF given the package_folder.

  PACKAGE_FOLDER: Folder of the NS, VNF or NST to be packaged

Options:
  --skip-validation   skip package validation
  --skip-charm-build  the charm will not be compiled, it is assumed to already exist
  -h, --help          Show this message and exit.
```

### Creating a package structure

The best way to work is by copying a previous one that is up-to-date. But you can also create
a first skeleton using this command:

```bash
Usage: osm package-create [OPTIONS] PACKAGE_TYPE PACKAGE_NAME

  Creates an OSM NS, VNF, NST package

  PACKAGE_TYPE: Package to be created: NS, VNF or NST.
  PACKAGE_NAME: Name of the package to create the folder with the content.

Options:
  --base-directory TEXT       (NS/VNF/NST) Set the location for package creation. Default: "."
  --image TEXT                (VNF) Set the name of the vdu image. Default "image-name"
  --vdus INTEGER              (VNF) Set the number of vdus in a VNF. Default 1
  --vcpu INTEGER              (VNF) Set the number of virtual CPUs in a vdu. Default 1
  --memory INTEGER            (VNF) Set the memory size (MB) of the vdu. Default 1024
  --storage INTEGER           (VNF) Set the disk size (GB) of the vdu. Default 10
  --interfaces INTEGER        (VNF) Set the number of additional interfaces apart from the management interface. Default 0
  --vendor TEXT               (NS/VNF) Set the descriptor vendor. Default "OSM"
  --override                  (NS/VNF/NST) Flag for overriding the package if exists.
  --detailed                  (NS/VNF/NST) Flag for generating descriptor .yaml with all possible commented options
  --netslice-subnets INTEGER  (NST) Number of netslice subnets. Default 1
  --netslice-vlds INTEGER     (NST) Number of netslice vlds. Default 1
  -h, --help                  Show this message and exit.
```

## Using images in public clouds

When a NF package wants to use an image from the public cloud, we need to specify the specific image in that public cloud. The name will be different for each public cloud. That's why we need to specify, for each VIM type, a different image. Find below an excerpt from `hackfest_basic_vnf`:

```yaml
  sw-image-desc:
  - id: ubuntu20.04
    image: ubuntu20.04
    name: ubuntu20.04
  - id: ubuntu20.04-aws
    name: ubuntu20.04-aws
    image: ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-20231025
    vim-type: aws
  - id: ubuntu20.04-azure
    name: ubuntu20.04-azure
    image: Canonical:0001-com-ubuntu-server-focal:20_04-lts:latest
    vim-type: azure
  - id: ubuntu20.04-gcp
    name: ubuntu20.04-gcp
    image: ubuntu-os-cloud:image-family:ubuntu-2004-lts
    vim-type: gcp
```

In order to know what are the name of the images on each public cloud, you could check the links below:

- Ubuntu images in Azure: <https://canonical-azure.readthedocs-hosted.com/en/latest/azure-how-to/instances/find-ubuntu-images/>
- Ubuntu images in GCP: <https://canonical-gcp.readthedocs-hosted.com/en/latest/google-how-to/gce/find-ubuntu-images/>
- Ubuntu images in AWS: <https://aws.amazon.com/marketplace/pp/prodview-tuap4sdmqpo52>
  - From AWS Console > EC2 > Images > AMI > Search
    - Public images
    - Filter: "Platform=Ubuntu", "Virtualization=hvm", "Architecture=x86_64", "AMI name=ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server"