Skip to content

Latest commit

 

History

History
233 lines (163 loc) · 9.42 KB

README.md

File metadata and controls

233 lines (163 loc) · 9.42 KB
Raw

Join the chat at https://gitter.im/sonata-nfv/Lobby Build Status

tng-sdk-project

This repository contains the tng-sdk-project component that is part of the European H2020 project 5GTANGO NFV SDK. This component is responsible for managing network service workspaces and projects on the developer's machine. It allows preparing structured 5GTANGO projects containing service descriptions, which can then be validated, packaged, and processed by other 5GTANGO SDK tools.

The seed code of this component is based on the son-cli toolbox that was developed as part of the European H2020 project SONATA.

Installation

Requires Python 3.5+ and setuptools.

For simple, automatic installation and usage:

# latest release from PyPi
$ pip install tngsdk.project
# latest version from GitHub master
$ pip install git+https://github.com/sonata-nfv/tng-sdk-project.git

Alternatively, for obtaining the source code, installation, and development:

$ git clone https://github.com/sonata-nfv/tng-sdk-project.git
$ cd tng-sdk-project
$ sudo python3 setup.py install

It is a good practice to first create a new virtual environment in which all 5GTANGO SDK tools can be installed. You can do this as follows:

# get the path to your Python3 installation
which python3

# create a new virtualenv
virtualenv -p <path/to/python3> venv

# activate the virtualenv
source venv/bin/activate

Sometimes you might have to upgrade the version of your installed pip packages if they are outdated. This can be done with:

pip install <package-name> --upgrade

Usage

CLI

Workspace

To start working, you need a workspace that holds your configuration files. The default location is ~/.tng-workspace/, but it may be at any location and there can also be multiple workspaces.

$ tng-workspace       # initializes a new workspace at the default location
$ tng-workspace --workspace path/to/workspace     # inits a workspace at a custom location

Project managament

Once you have a workspace, you can create projects with the tng-project command. You can also add or remove files from the project (wildcards allowed) or check the project status.

$ tng-project -p path/to/project                # creates a new project at the specified path
$ tng-project -p path/to/project --add file1    # adds file1 to the project.yml
$ tng-project -p path/to/project --add file1 --type text/plain  # adds file1 with explicit MIME type
$ tng-project -p path/to/project --remove file1 # removes file1 from the project.yml
$ tng-project -p path/to/project --status       # shows project overview/status

The --workspace option allows to specify a workspace at a custom location. Otherwise, the workspace at the default location is used. For both tng-workspace and tng-project the option --debug makes the output more verbose.

Since the structure of projects and descriptors changed from SONATA (v3.1) to 5GTANGO (v5.0), tng-project also provides a command to automatically translate old to new projects. For more information see the corresponding wiki page.

$ tng-project -p path/to/old-project --translate   # translates the project to the new structure

Descriptor generation (CLI)

This tool also includes a CLI for descriptor generation. Its functionality is mostly consistent with the GUI version but might be preferred by advanced users.

The descriptor generator is integrated in the project management tool such that additional arguments are passed to the descriptor generator and are used to generate suitable descriptors in a new project:

$ tng-project -p path/to/project --author abc --vnfs 2 \  
  --image_names img1 img2 --image_types docker docker     # creates a new project with descriptors for 2 VNFs with the specified author and images

The descriptorgen CLI can also be used separately as follows:

$ tng-descriptorgen --author author.name --vnfs 3   # generate NSD and VNFDs for service with 3 VNFs
$ tng-descriptorgen --author author.name --vnfs 2 \
  --image_names img1 img2 --image_types docker docker  # generate descriptors for 2 VNFs with specific images
$ tng-descriptorgen --tango -o tango-project        # generate only 5GTANGO descriptors in a folder "tango-project"
$ tng-descriptorgen --osm -o osm-project            # generate only OSM descriptors in a folder "osm-project"

For more information, use tng-descriptorgen -h.

Service mode with REST API

In addition to the CLI, the tng-sdk-project tool can also be started in "service mode" and be used via its REST API. This enables simple integration with other tools or frontend services.

Run on bare metal

# terminal 1
$ tng-project -s    # starts the tool in service mode (running forever)

This will start the tool in service mode running in the terminal forever until stopped with Ctrl+C.

Run in Docker container

Locally-build images

The simplest option is using Docker Compose.

docker-compose up

Alternatively, you can also build and run the Docker container manually. The commands here don't attach to the volume, i.e., projects are not stored persistently and lost after restart.

pipeline/build/build.sh
docker run --rm -d -p 5098:5098 --name tng-sdk-project registry.sonata-nfv.eu:5000/tng-sdk-project
Image from DockerHub

The Docker image is also available on DockerHub:

docker pull sonatanfv/tng-sdk-project:dev
docker run --rm -d -p 5098:5098 --name tng-sdk-project sonatanfv/tng-sdk-project:dev

This will run the tool in service mode in a detached Docker container, i.e., in the background (check with docker ps). See the wiki page on Docker deployment for additional details.

Calling the REST API

You can find the Swagger API specification here. Additionally, see the examples below.

Showing, adding, deleting projects:

# terminal 2
$ curl -X POST localhost:5098/api/v1/projects            # create a new project
$ curl -X GET localhost:5098/api/v1/projects             # show all projects
$ curl -X POST localhost:5098/api/v1/projects \
-d author=alice -d vendor=eu.tango -d vnfs=3             # new project with custom-generated descriptors
$ curl -X POST localhost:5098/api/v1/projects \
-d vnfs=2 -d image_names="img1 img2"                     # you can specify image names/types as white space-separated list in quotation marks ("", not ''!) 
$ curl -X GET localhost:5098/api/v1/projects/{uuid}      # show details of the specified project
$ curl -X DELETE localhost:5098/api/v1/projects/{uuid}   # delete the specified project

Showing, adding, deleting project files:

# terminal 2
$ curl -X GET localhost:5098/api/v1/projects/{uuid}/files   # show files of the specified project
$ curl -X POST localhost:5098/api/v1/projects/{uuid}/files \
    -H "Content-Type: multipart/form-data" \
    -F file="@requirements.txt"                             # add new file to the project
$ curl -X POST localhost:5098/api/v1/projects/{uuid}/files \
    -H "Content-Type: multipart/form-data" \
    -F file="@LICENSE" -F file_type="text/plain"            # add new file with specific MIME type
$ curl -X DELETE localhost:5098/api/v1/projects/{uuid}/files \
    -d filename="requirements.txt"                          # remove the specified file
$ curl -X GET localhost:5098/api/v1/projects/{uuid}/{file_name} # show content of the specified file of specified project

Documentation

See the wiki for further documentation and details.

Dependencies

tng-sdk-project only depends on Python packages, which are listed in and can be installed through setup.py.

Development

To contribute to the development of this 5GTANGO component, you may use the very same development workflow as for any other 5GTANGO Github project. That is, you have to fork the repository and create pull requests.

Setup development environment

$ python setup.py develop

CI Integration

Run tests manually

You can also run the test manually on your local machine. To do so, you need to do:

$ pytest -v
$ pycodestyle .

License

This 5GTANGO component is published under Apache 2.0 license. Please see the LICENSE file for more details.

Lead Developers

The following lead developers are responsible for this repository and have admin rights. They can, for example, merge pull requests.

Feedback-Chanel

  • Please use the GitHub issues to report bugs.
  • You may use the mailing list [email protected]