README.md

   1 <!--
   2 Copyright 2020 ETSI
   3
   4 Licensed under the Apache License, Version 2.0 (the "License");
   5 you may not use this file except in compliance with the License.
   6 You may obtain a copy of the License at
   7
   8    http://www.apache.org/licenses/LICENSE-2.0
   9
  10 Unless required by applicable law or agreed to in writing, software
  11 distributed under the License is distributed on an "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
  13 implied.
  14 See the License for the specific language governing permissions and
  15 limitations under the License
  16 -->
  17 # python-osmclient
  18
  19 OSM client library and console script
  20
  21 ## Installation
  22
  23 ```bash
  24 # Ubuntu pre-requirements
  25 sudo apt-get install python3-pip
  26 # Centos pre-requirements
  27 # sudo yum install python3-pip
  28 ```
  29
  30 Clone the osmclient repo:
  31
  32 ```bash
  33 git clone https://osm.etsi.org/gerrit/osm/osmclient
  34 cd osmclient
  35 ```
  36
  37 Finally install osmclient with pip. For development, you should install osmclient in editable mode (`--user -e`):
  38
  39 ```bash
  40 # Install osmclient
  41 python3 -m pip install --user . -r requirements.txt -r requirements-dev.txt
  42 # Install osmclient in editable mode (-e)
  43 # python3 -m pip install --user -e . -r requirements.txt -r requirements-dev.txt
  44 # logout and login so that PATH can be updated. Executable osm will be found in /home/ubuntu/.local/bin
  45 ```
  46
  47 After logging out and in, you can check that osm is running with:
  48
  49 ```bash
  50 which osm
  51 osm version
  52 ```
  53
  54 ## Setup
  55
  56 Set the OSM_HOSTNAME variable to the host of the OSM server (default: localhost).
  57
  58 ```bash
  59 localhost$ export OSM_HOSTNAME=<hostname>
  60 ```
  61
  62 ## Examples
  63
  64 ### upload vnfd
  65
  66 ```bash
  67 localhost$ osm upload-package ubuntu_xenial_vnf.tar.gz
  68 {'transaction_id': 'ec12af77-1b91-4c84-b233-60f2c2c16d14'}
  69 localhost$ osm vnfd-list
  70 +--------------------+--------------------+
  71 | vnfd name          | id                 |
  72 +--------------------+--------------------+
  73 | ubuntu_xenial_vnfd | ubuntu_xenial_vnfd |
  74 +--------------------+--------------------+
  75 ```
  76
  77 ### upload nsd
  78
  79 ```bash
  80 localhost$ osm upload-package ubuntu_xenial_ns.tar.gz
  81 {'transaction_id': 'b560c9cb-43e1-49ef-a2da-af7aab24ce9d'}
  82 localhost$ osm nsd-list
  83 +-------------------+-------------------+
  84 | nsd name          | id                |
  85 +-------------------+-------------------+
  86 | ubuntu_xenial_nsd | ubuntu_xenial_nsd |
  87 +-------------------+-------------------+
  88 ```
  89
  90 ### vim-list
  91
  92 ```bash
  93 localhost$ osm vim-list
  94 +-------------+-----------------+--------------------------------------+
  95 | ro-account  | datacenter name | uuid                                 |
  96 +-------------+-----------------+--------------------------------------+
  97 | osmopenmano | openstack-site  | 2ea04690-0e4a-11e7-89bc-00163e59ff0c |
  98 +-------------+-----------------+--------------------------------------+
  99 ```
 100
 101 ### instantiate ns
 102
 103 ```bash
 104 localhost$ osm ns-create ubuntu_xenial_nsd testns openstack-site
 105 {'success': ''}
 106 localhost$ osm ns-list
 107 +------------------+--------------------------------------+-------------------+--------------------+---------------+
 108 | ns instance name | id                                   | catalog name      | operational status | config status |
 109 +------------------+--------------------------------------+-------------------+--------------------+---------------+
 110 | testns           | 6b0d2906-13d4-11e7-aa01-b8ac6f7d0c77 | ubuntu_xenial_nsd | running            | configured    |
 111 +------------------+--------------------------------------+-------------------+--------------------+---------------+
 112 ```
 113
 114 ## Using osmclient as a library to interact with OSM
 115
 116 Assuming that you have installed python-osmclient package, it's pretty simple to write some Python code to interact with OSM.
 117
 118 ### Simple Python code to get the list of NS packages
 119
 120 ```python
 121 from osmclient import client
 122 from osmclient.common.exceptions import ClientException
 123 hostname = "127.0.0.1"
 124 myclient = client.Client(host=hostname, sol005=True)
 125 resp = myclient.nsd.list()
 126 print yaml.safe_dump(resp, indent=4, default_flow_style=False)
 127 ```
 128
 129 ### Simple Python code to get the list of VNF packages from a specific user and project
 130
 131 The code will print for each package a pretty table, then the full details in yaml
 132
 133 ```python
 134 from osmclient import client
 135 from osmclient.common.exceptions import ClientException
 136 import yaml
 137 from prettytable import PrettyTable
 138 hostname = "127.0.0.1"
 139 user = admin
 140 password = admin
 141 project = admin
 142 kwargs = {}
 143 if user is not None:
 144     kwargs['user']=user
 145 if password is not None:
 146     kwargs['password']=password
 147 if project is not None:
 148    kwargs['project']=project
 149 myclient = client.Client(host=hostname, sol005=True, **kwargs)
 150 resp = myclient.vnfd.list()
 151 print yaml.safe_dump(resp, indent=4, default_flow_style=False)
 152 ```
 153
 154 ## Enable autocompletion
 155
 156 You can enable autocompletion in OSM client by creating a file osm-complete.sh in the following way:
 157
 158 ```bash
 159 mkdir -p $HOME/.bash_completion.d
 160 _OSM_COMPLETE=source osm > $HOME/.bash_completion.d/osm-complete.sh
 161 ```
 162
 163 Then you can add the following to your $HOME/.bashrc file:
 164
 165 ```bash
 166 . .bash_completion.d/osm-complete.sh
 167 ```
 168
 169 ## Future work
 170
 171 - Option `-c` for list and show operations to filter output and show only selected columns
 172 - Option `-o <FORMAT>` to adapt output format (table, csv, yaml, json, jsonpath)
 173 - Command ns-status to show the deployment status (RO) and configuration status (VCA) in an appealing format
 174 - See how to deprecate commands and options: <https://stackoverflow.com/questions/50366719/correct-way-to-deprecate-parameter-alias-in-click>
 175 - Evaluate the possibility to re-structure code to uniform all commands: `check`, `table_headers`, `run`, `output`
 176