docs/release/userguide/feature.userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) 2017 OPNFV
   4
   5 ========================================
   6 Domino API Usage Guidelines and Examples
   7 ========================================
   8
   9 Using domino-cli Client
  10 =======================
  11
  12 Prerequisites:
  13
  14 1. Make sure that domino-cli.py is in +x mode.
  15
  16 2. Change directory to where domino-cli.py, DominoClient.py and DominoServer.py are located or include file path in the PATH environment variable.
  17
  18 3. Start the Domino Server:
  19
  20 .. code-block:: bash
  21
  22   ./DominoServer.py --log=debug
  23
  24 4. Start the Domino Client:
  25
  26 .. code-block:: bash
  27
  28   ./DominoClient.py -p <portnumber> --cliport <cli-portnumber> --log=debug
  29
  30 Note1: The default log level is WARNING and omitting --log option will lead to minimal/no logging on the console
  31
  32 Note2: domino_conf.py file includes most of the default values
  33
  34 * Registration Command
  35
  36 Command line input:
  37
  38 .. code-block:: bash
  39
  40   ./domino-cli.py <cli-portnumber> register
  41
  42 This message has the following fields that are automatically filled in.
  43
  44 .. code-block:: bash
  45
  46   Message Type (= REGISTER)
  47   DESIRED UDID (= if not allocated, this will be assigned as Unique Domino ID)
  48   Sequence Number (=incremented after each RPC call)
  49   IP ADDR (= IP address of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client)
  50   TCP PORT (= TCP port of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client)
  51   Supported Templates (= Null, this field not used currently)
  52
  53 * Heart Beat Command
  54
  55 Command line input:
  56
  57 .. code-block:: bash
  58
  59   ./domino-cli.py <cli-portnumber> heartbeat
  60
  61 This message has the following fields that are automatically filled in.
  62
  63 .. code-block:: bash
  64
  65   Message Type (= HEART_BEAT)
  66   UDID (= Unique Domino ID assigned during registration)
  67   Sequence Number (=incremented after each RPC call)
  68
  69 * Label and Template Type Subscription Command
  70
  71 .. code-block:: bash
  72
  73   ./domino-cli.py <cli-portnumber> subscribe -l <labelname> -t <templatetype>
  74
  75 Note that -l can be substituted by --label and -t can be substituted by --ttype.
  76
  77 More than one label or template type can be subscribed within the same command line as comma separated labels or template types
  78
  79 .. code-block:: bash
  80
  81   ./domino-cli.py <cli-portnumber> subscribe -l <label1>,<label2>,<labeln> -t <ttype1>,<ttype2>,<ttypen>
  82
  83 To subscribe more than one label or template type, one can also repeat the options -l and -t, e.g.:
  84
  85 .. code-block:: bash
  86
  87   ./domino-cli.py <cli-portnumber> subscribe -l <label1> -l <label2> -l <labeln> -t <ttype1> -t <ttype2> -t <ttypen>
  88
  89 It is safe to call subscribe command multiple times with duplicate labels.
  90
  91 This message has the following fields that are automatically filled in.
  92
  93 .. code-block:: bash
  94
  95   Message Type (= SUBSCRIBE)
  96   UDID (= Unique Domino ID assigned during registration)
  97   Sequence Number (=incremented after each RPC call)
  98   Template Operation (= APPEND)
  99   Label Operation (= APPEND)
 100
 101 The following fields are filled in based on arguments passed on via -l/--label and -t/--ttype flags
 102
 103 Subscribe RPC also supports options for label using
 104   --lop=APPEND/DELETE/OVERWRITE
 105 and for supported template types using
 106   --top=APPEND/DELETE/OVERWRITE.
 107 When unspecified, the default is APPEND.
 108 DELETE deletes existing labels (template types) specified in the current call via key -l/--label (-t/--ttype).
 109 OVERWRITE removes the current set of labels (template types) and sets it to the new set of values passed in the same RPC call.
 110
 111 By default, no translation service is provided. Currently, only TOSCA to Heat
 112 Orchestration Template (HOT) translation is supported using OpenStack
 113 heat-translator library. A domain that requires HOT files must subscribe HOT
 114 template type using
 115
 116 .. code-block:: bash
 117
 118   ./domino-cli.py <cli-portnumber> subscribe -t hot
 119
 120 * Template Publishing Command
 121
 122 .. code-block:: bash
 123
 124   ./domino-cli.py <cli-portnumber> publish -t <toscafile>
 125
 126 Note that -t can be substituted with --tosca-file.
 127
 128 If -t or --tosca-file flag is used multiple times, the last tosca file passed as input will be used. This usage is not recommended as undefined/unintended results may emerge as the Domino client will continue to publish.
 129
 130 This message has the following fields that are automatically filled in.
 131
 132 .. code-block:: bash
 133
 134   Message Type (= PUBLISH)
 135   UDID (= Unique Domino ID assigned during registration)
 136   Sequence Number (=incremented after each RPC call)
 137   Template Type (= TOSCA)
 138   Template File
 139
 140 Since Danube release, Domino Server supports stateful updates for template publishing. The following command can be used to update the service template for an existing Template Unique ID (TUID):
 141
 142 .. code-block:: bash
 143
 144   ./domino-cli.py <cli-portnumber> publish -t <toscafile> -k <TUID>
 145
 146 Note that -k can be substituted with --tuid. When Domino Server receives this command, it verifies whether
 147 the client previously published the provided TUID. If such TUID does not exist, then Domino Server returns
 148 FAILED response back to the client. If such TUID exists, Domino Server recomputes which resources are
 149 mapped onto which domains and updates each domain with the new VNF and NS descriptors. If a previously
 150 utilized domain is no longer targeted, it is updated with a null descriptor.
 151
 152 * Template Listing Command
 153
 154 .. code-block:: bash
 155
 156   ./domino-cli.py <cli-portnumber> list-tuids
 157
 158 Queries all the Template Unique IDs (TUIDs) published by the Domino Client from the Domino Server.
 159
 160 Interactive CLI mode
 161 --------------------
 162
 163 To enter this mode, start Domino Client with interactive console option set as true, i.e., --iac=true:
 164
 165 .. code-block:: bash
 166
 167   ./DominoClient -p <portnumber> --iax=true --log=DEBUG
 168
 169 The rest of the API calls are the same as in the case of using domino-cli.py except that at the prompt there is no need to write "domino-cli.py <cli-portnumber>, e.g.,:
 170
 171 .. code-block:: bash
 172
 173   >>register
 174   >>heartbeat
 175   >>subscribe -l <label1> -t <ttype1>
 176   >>publish -t <toscafile>
 177
 178 The interactive CLI mode is mainly supported for manual testing.