docs/user-guide/alto-user-guide.rst

   1 ALTO User Guide
   2 ===============
   3
   4 Overview
   5 --------
   6
   7 The ALTO project is aimed to provide support for **Application Layer
   8 Traffic Optimization** services defined in `RFC
   9 7285 <https://tools.ietf.org/html/rfc7285>`__ in OpenDaylight.
  10
  11 This user guide will introduce the three basic services (namely
  12 ``simple-ird``, ``manual-maps`` and ``host-tracker``) which are
  13 implemented since the Beryllium release, and give instructions on how to
  14 configure them to provide corresponding ALTO services.
  15
  16 A new feature named ``simple-pce`` (**Simple Path Computation Engine**)
  17 is added into Boron release as an ALTO extension service.
  18
  19 How to Identify ALTO Resources
  20 ------------------------------
  21
  22 Each ALTO resource can be uniquely identified by a tuple . For each
  23 resource, a *version-tag* is used to support historical look-ups.
  24
  25 The formats of *resource-id* and *version-tag* are defined in `section
  26 10.2 <https://tools.ietf.org/html/rfc7285#section-10.2>`__ and `section
  27 10.3 <https://tools.ietf.org/html/rfc7285#section-10.3>`__ respectively.
  28 The *context-id* is not part of the protocol and we choose the same
  29 format as a *universal unique identifier* (UUID) which is defined in
  30 `RFC 4122 <http://tools.ietf.org/html/rfc4122>`__.
  31
  32 A context is like a namespace for ALTO resources, which eliminates
  33 *resource-id* collisions. For simplicity, we also provide a default
  34 context with the id **000000000000-0000-0000-0000-00000000**.
  35
  36 How to Use Simple IRD
  37 ---------------------
  38
  39 The simple IRD feature provides a simple *information resource
  40 directory* (IRD) service defined in `RFC
  41 7285 <https://tools.ietf.org/html/rfc7285#section-9>`__.
  42
  43 Install the Feature
  44 ~~~~~~~~~~~~~~~~~~~
  45
  46 To enable simple IRD, run the following command in the karaf CLI:
  47
  48 .. code:: bash
  49
  50     karaf > feature:install odl-alto-simpleird
  51
  52 After the feature is successfully installed, a special context will be
  53 created for all simple IRD resources. The id for this context can be
  54 seen by executing the following command in a terminal:
  55
  56 .. code:: bash
  57
  58     curl -X GET -u admin:admin http://localhost:8181/restconf/operational/alto-simple-ird:information/
  59
  60 Create a new IRD
  61 ~~~~~~~~~~~~~~~~
  62
  63 To create a new IRD resource, two fields MUST be provided:
  64
  65 -  Field **instance-id**: the *resource-id* of the IRD resource;
  66
  67 -  Field **entry-context**: the context-id for non-IRD entries managed
  68    by this IRD resource.
  69
  70 Using the following script, one can create an empty IRD resource:
  71
  72 .. code:: bash
  73
  74     #!/bin/bash
  75     # filename: ird-create
  76     INSTANCE_ID=$1
  77     if [ $2 ]; then
  78         CONTEXT_ID=$2
  79     else
  80         CONTEXT_ID="00000000-0000-0000-0000-000000000000"
  81     fi
  82     URL="`http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/"$INSTANCE_ID"/[`http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/"$INSTANCE_ID"/`]`"
  83     DATA=$(cat template \
  84       | sed 's/\$1/'$CONTEXT_ID'/g' \
  85       | sed 's/\$2/'$INSTANCE_ID'/g')
  86     curl -4 -D - -X PUT -u admin:admin \
  87       -H "Content-Type: application/json" -d "$(echo $DATA)"\
  88       $URL
  89
  90 For example, the following command will create a new IRD named *ird*
  91 which can accept entries with the default context-id:
  92
  93 .. code:: bash
  94
  95     $ ./ird-create ird 000000000000-0000-0000-0000-00000000
  96
  97 And below is the what the template file looks like:
  98
  99 .. code:: json
 100
 101     {
 102         "ird-instance-configuration": {
 103             "entry-context": "/alto-resourcepool:context[alto-resourcepool:context-id='$1']",
 104             "instance-id": "$2"
 105         }
 106     }
 107
 108 Remove an IRD
 109 ~~~~~~~~~~~~~
 110
 111 To remove an existing IRD (and all the entries in it), one can use the
 112 following command in a terminal:
 113
 114 .. code:: bash
 115
 116     curl -X DELETE -u admin:admin http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/$INSTANCE_ID
 117
 118 Add a new entry
 119 ~~~~~~~~~~~~~~~
 120
 121 There are several ways to add entries to an IRD and in this section we
 122 introduce only the simplest method. Using the following script, one can
 123 add a new entry to the target IRD.
 124
 125 For each new entry, four parameters MUST be provided:
 126
 127 -  Parameter *ird-id*: the *resource-id* of the target IRD;
 128
 129 -  Parameter *entry-id*: the *resource-id* of the ALTO service to be
 130    added;
 131
 132 -  Parameter *context-id*: the *context-id* of the ALTO service to be
 133    added, which MUST be identical to the target IRD’s *entry-context*;
 134
 135 -  Parameter *location*: either a URI or a relative path to the ALTO
 136    service.
 137
 138 The following script can be used to add one entry to the target IRD,
 139 where the relative path is used:
 140
 141 .. code:: bash
 142
 143     #!/bin/bash
 144     # filename: ird-add-entry
 145     IRD_ID=$1
 146     ENTRY_ID=$2
 147     CONTEXT_ID=$3
 148     BASE_URL=$4
 149     URL="`http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/"$IRD_ID"/ird-configuration-entry/"$ENTRY_ID"/"
 150     DATA=$(cat template \
 151       | sed 's/\$1/'$ENTRY_ID'/g' \
 152       | sed 's/\$2/'$CONTEXT_ID'/g' \
 153       | sed 's/\$3/'$BASE_URL'/g' )
 154     curl -4 -D - -X PUT -u admin:admin \
 155       -H "Content-Type: application/json" -d "$(echo $DATA)" \
 156       $URL
 157
 158 For example, the following command will add a new resource named
 159 *networkmap*, whose context-id is the default context-id and the base
 160 URL is /alto/networkmap, to the IRD named *ird*:
 161
 162 .. code:: bash
 163
 164     $ ./ird-add-entry ird networkmap 000000000000-0000-0000-0000-00000000 /alto/networkmap
 165
 166 And below is the template file:
 167
 168 .. code:: json
 169
 170     {
 171         "ird-configuration-entry": {
 172             "entry-id": "$1",
 173             "instance": "/alto-resourcepool:context[alto-resourcepool:context-id='$2']/alto-resourcepool:resource[alto-resourcepool:resource-id='$1']",
 174             "path": "$3/$1"
 175         }
 176     }
 177
 178 Remove an entry
 179 ~~~~~~~~~~~~~~~
 180
 181 To remove an entry from an IRD, one can use the following one-line
 182 command:
 183
 184 .. code:: bash
 185
 186     curl -X DELETE -u admin:admin http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/$IRD_ID/ird-configuration-entry/$ENTRY_ID/
 187
 188 How to Use Host-tracker-based ECS
 189 ---------------------------------
 190
 191 As a real instance of ALTO services, ***alto-hosttracker*** reads data
 192 from ***l2switch*** and generates a network map with resource id
 193 ***hosttracker-network-map*** and a cost map with resource id
 194 ***hostracker-cost-map***. It can only work with OpenFlow-enabled
 195 networks.
 196
 197 After installing the ***odl-alto-hosttracker*** feature, the
 198 corresponding network map and cost map will be inserted into the data
 199 store.
 200
 201 Managing Resource with ``alto-resourcepool``
 202 --------------------------------------------
 203
 204 After installing ``odl-alto-release`` feature in Karaf,
 205 ``alto-resourcepool`` feature will be installed automatically. And you
 206 can manage all resources in ALTO via RESTCONF APIs provided by
 207 ``alto-resourcepool``.
 208
 209 With the example bash script below you can get any resource infomation
 210 in a given context.
 211
 212 .. code:: bash
 213
 214     #!/bin/bash
 215     RESOURCE_ID=$1
 216     if [ $2 ] ; then
 217         CONTEXT_ID=$2
 218     else
 219         CONTEXT_ID="00000000-0000-0000-0000-000000000000"
 220     fi
 221     URL="http://localhost:8181/restconf/operational/alto-resourcepool:context/"$CONTEXT_ID"/alto-resourcepool:resource/"$RESOURCE_ID
 222     curl -X GET -u admin:admin $URL | python -m json.tool | sed -n '/default-tag/p' | sed 's/.*:.*\"\(.*\)\".*/\1/g'
 223
 224 Manual Configuration
 225 --------------------
 226
 227 Using RESTCONF API
 228 ~~~~~~~~~~~~~~~~~~
 229
 230 After installing ``odl-alto-release`` feature in Karaf, it is possible
 231 to manage network-maps and cost-maps using RESTCONF. Take a look at all
 232 the operations provided by ``resource-config`` at the API service page
 233 which can be found at
 234 ``http://localhost:8181/apidoc/explorer/index.html``.
 235
 236 The easiest method to operate network-maps and cost-maps is to modify
 237 data broker via RESTCONF API directly.
 238
 239 Using RPC
 240 ~~~~~~~~~
 241
 242 The ``resource-config`` package also provides a query RPC to config the
 243 resources. You can CREATE, UPDATE and DELETE **network-maps** and
 244 **cost-maps** via query RPC.
 245
 246 Simple Path Computation Engine
 247 ------------------------------
 248
 249 The ``simple-pce`` module provides a simple path computation engine for
 250 ALTO and other projects. It supports basic CRUD (create, read, update,
 251 delete) operations to manage L2 and L3 routing with/without rate
 252 limitation. This module is an independent feature, so you can follow the
 253 instruction below to install it independently.
 254
 255 .. code:: bash
 256
 257     karaf > feature:install odl-alto-extenstion
 258
 259 .. note::
 260
 261     The rate limitation meter requires OpenFlow 1.3 support.
 262
 263 Basic Usage with RESTCONF API
 264 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 265
 266 You can use the simple path computation engine with RESTCONF API, which
 267 is defined in the YANG model
 268 `here <https://git.opendaylight.org/gerrit/gitweb?p=alto.git;a=blob;f=alto-extensions/simple-pce/api/src/main/yang/alto-spce.yang;h=f5bbe6744f7dfba493edd275aa18114e363727ab;hb=refs/heads/stable/boron>`__.
 269
 270 Use Case
 271 --------
 272
 273 Server Selection
 274 ~~~~~~~~~~~~~~~~
 275
 276 One of the key use case for ALTO is server selection. For example, a
 277 client (with IP address 10.0.0.1) sends a data transferring request to
 278 Data Transferring Service (DTS). And there are three data replica
 279 servers (with IP address 10.60.0.1, 10.60.0.2 and 10.60.0.3) which can
 280 response the request. In this case, DTS can send a query request to ALTO
 281 server to make server selection decision.
 282
 283 Following is an example ALTO query:
 284
 285 ::
 286
 287     POST /alto/endpointcost HTTP/1.1
 288     Host: localhost:8080
 289     Content-Type: application/alto-endpointcostparams+json
 290     Accept: application/alto-endpointcost+json,application/alto-error+json
 291     {
 292       "cost-type": {
 293         "cost-mode": "ordinal",
 294         "cost-metric": "hopcount"
 295       },
 296       "endpoints": {
 297         "srcs": [ "ipv4:10.0.0.1" ],
 298         "dsts": [
 299           "ipv4:10.60.0.1",
 300           "ipv4:10.60.0.2",
 301           "ipv4:10.60.0.3"
 302       ]
 303       }
 304     }
 305