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