SONATA SDK command line interface tools
This set of command line tools are meant to aid the SONATA service developers on their tasks. The tools are briefly described as follows.
son-workspacecreates, configures and manages development workspaces and projects.son-publishallows the publication of projects, services and functions to private catalogues.son-packagepackages a project, containing services and functions, to be instantiated in the SONATA Service Platform. All project components are syntatically validated and external dependencies are retrieved to produce a complete service package.son-pushis used to upload the service package to the Service Platform Gatekeeper.
To build the son-cli tools it is recommended the use of a virtual environment to avoid polluting your system and to offer isolation from the installed libraries on the host.
Prerequisites:
- python 3 (3.4 used for most of the development)
- virtualenv
- Install virtualenvwrapper using your distribution repositories or the pip package. https://virtualenvwrapper.readthedocs.org/en/latest/
- Create a virtualenv for this project
mkvirtualenv -p /usr/bin/python34 sonata
activate the virtualenv for the project workon sonata then clone the project and bootstrap and run buildout. This will download all the dependencies and creante the development environment.
git clone [email protected]:sonata-nfv/son-cli.git
cd son-cli
python bootstrap.py
bin/buildoutIf you are using pycharm, the IDE has support both for buildout and for virtualenvs, please read their fine documentation on the subject before proceeding.
The buildout generates the binaries for the tools son-workspace, son-publish, son-package and son-push. Information on how to use the tools is detailed in Usage section bellow.
The son-cli tools have the following dependencies:
- pyaml >= 15.8.2 (WTFPL)
- jsonschema >= 2.5.1 (MIT)
- validators >= 0.10.3 (BSD)
- requests >= 2.10 (Apache 2.0)
- coloredlogs >= 5.0 (MIT)
To contribute to son-cli this simple process should be followed:
- Fork this repository;
- Work on your proposed changes, preferably through submiting issues;
- Submit a Pull Request to the master branch;
- Follow/answer related issues (see Feedback-Chanel, below).
To install the SONATA CLI toolset in Ubuntu follow these steps:
-
Add the new GPG key
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys D0DF34A30A4FE3F8
-
Add a source entry for your Ubuntu OS. For now, supported distributions are supported:
-
Ubuntu Trusty 14.04 (LTS)
echo "deb http://registry.sonata-nfv.eu:8080 ubuntu-trusty main" | sudo tee -a /etc/apt/sources.list
-
Ubuntu Xenial 16.04 (LTS)
echo "deb http://registry.sonata-nfv.eu:8080 ubuntu-xenial main" | sudo tee -a /etc/apt/sources.list
-
Update and install
sudo apt-get update sudo apt-get install sonata-cli
-
Test if its working by invoking:
$ son-workspace -h $ son-package -h $ son-publish -h $ son-push -h
The usage guidelines of the son-cli tools are described as follows.
Create workspaces and projects
This tool is responsible to create workspaces and generate project layouts.
usage: son-workspace [-h] [--init] [--workspace WORKSPACE] [--project PROJECT]
[--debug]
Generate new sonata workspaces and project layouts
optional arguments:
-h, --help show this help message and exit
--init Create a new sonata workspace
--workspace WORKSPACE
location of existing (or new) workspace. If not
specified will assume '$HOME/.son-workspace'
--project PROJECT create a new project at the specified location
--debug increases logging level to debugExample on how to create an workspace and a project:
son-workspace --init --workspace /home/user/workspaces/ws1
son-workspace --workspace /home/user/workspace/ws1 --project /home/user/workspace/ws1/projects/p1This example creates the workspace 'ws1' and a project 'p1' associated with it.
This tool publishes service descriptors, function descriptors to a catalogue. It is possible to publish all the components of a project using the --project option, instead of publishing a single component. Before any descriptor is published, a syntax validation is performed against the latest schemas, defined in the son-schema repository (https://github.com/sonata-nfv/son-schema/tree/master/package-descriptor).
usage: son-publish [-h] [--workspace WORKSPACE] [--project PROJECT]
[-d COMPONENT] [-c CATALOGUE]
Publish a project or component to the catalogue server
optional arguments:
-h, --help show this help message and exit
--workspace WORKSPACE
Specify workspace. Default is located at
'/home/lconceicao/.son-workspace'
--project PROJECT Specify project to be published
-d COMPONENT, --component COMPONENT
Project component to be published.
-c CATALOGUE, --catalogue CATALOGUE
Catalogue ID where to publish. Overrides defaults in
workspace config.Example on how to publish a single descriptor:
son-publish --workspace /home/user/workspaces/ws1 --component vnfd-firewall.ymlExample on how to publish all the descriptors of a project:
son-publish --workspace /home/user/workspace/ws1 --project /home/user/project/prj1These examples assume that the catalogue server address is defined at the workspace configuration. Otherwise, the catalogue address must be specified explicitly.
Generate a SONATA SDK package.
This tool delivers a SON file compiling all the required descriptors of specified the project and workspace.
The generated file structure follows the format defined in the package-descriptor of the son-schema repository (https://github.com/sonata-nfv/son-schema/tree/master/package-descriptor). Please check folder examples for a demo package.
usage: son-package [-h] [--workspace WORKSPACE] [--project PROJECT]
[-d DESTINATION] [-n NAME]
Generate new sonata package
optional arguments:
-h, --help show this help message and exit
--workspace WORKSPACE
Specify workspace to generate the package. If not
specified will assume '$HOME/.son-workspace'
--project PROJECT create a new package based on the project at the
specified location. If not specified will assume the
current directory.
-d DESTINATION, --destination DESTINATION
create the package on the specified location
-n NAME, --name NAME create the package with the specific nameson-package will create a package inside the DESTINATION directory. If DESTINATION is not specified, the package will be deployed at <project root/target>.
Example on how to package a project:
son-package --workspace /home/user/workspace/ws1 --project /home/user/project/prj1Example on how to package a project with custom destination and package name:
son-package --workspace /home/user/workspace/ws1 --project /home/user/project/prj1 --d /home/user/packages -n sonata-demo.sonUpload a SONATA SDK package to the Gatekeeper for instantiation. With this tools it is also possible to list the packages uploaded and deployed at the Platform.
usage: son-push [-h] [-P] [-I] [-U UPLOAD_PACKAGE] [-D DEPLOY_PACKAGE_UUID]
platform_url
Push packages to the SONATA service platform/emulator or list
packages/instances available on the SONATA platform/emulator.
positional arguments:
platform_url url of the gatekeeper/platform/emulator
optional arguments:
-h, --help show this help message and exit
-P, --list_packages List packages uploaded to the platform
-I, --list_instances List deployed packages on the platform
-U UPLOAD_PACKAGE, --upload_package UPLOAD_PACKAGE
Filename incl. path of package to be uploaded
-D DEPLOY_PACKAGE_UUID, --deploy_package_uuid DEPLOY_PACKAGE_UUID
UUID of package to be deployed (must be available at
platform)
Example usage:
son-push http://127.0.0.1:5000 -U sonata-demo.son
son-push http://127.0.0.1:5000 --list-packages
son-push http://127.0.0.1:5000 --deploy-package <uuid>
son-push http://127.0.0.1:5000 -I
The son-cli is published under Apache 2.0 license. Please see the LICENSE file for more details.
The following lead developers are responsible for this repository and have admin rights. They can, for example, merge pull requests.
- Tiago Batista (https://github.com/tsbatista)
- Wouter Tavernier (https://github.com/wtaverni)
- Luís Conceição (https://github.com/lconceicao)
- You may use the mailing list [email protected]
- GitHub issues