dashboard/open-api-spec.yaml

   1 ---
   2 swagger: "2.0"
   3 info:
   4   description: This is the Lab as a Service API
   5   version: 2.0.1
   6   title: LaaS API
   7   contact:
   8     email: nfvlab@iol.unh.edu
   9   license:
  10     name: Apache 2.0
  11     url: http://www.apache.org/licenses/LICENSE-2.0.html
  12 host: virtserver.swaggerhub.com
  13 basePath: /IOL-OPNFV-LaaS/Labs/1.0.0
  14 tags:
  15 - name: admin
  16   description: Secured Admin-only calls
  17 - name: developers
  18   description: Operations available to regular developers
  19 schemes:
  20 - https
  21 paths:
  22   /api/labs/{lab-name}/jobs/new:
  23     get:
  24       summary: list of new, unstarted jobs for the lab
  25       description: |
  26         List of jobs for <lab-name> to start. These jobs all must have a status of `new`,
  27         meaning they are unstarted.
  28       produces:
  29       - application/json
  30       parameters:
  31       - name: lab-name
  32         in: path
  33         required: true
  34         type: string
  35       responses:
  36         200:
  37           description: search results matching criteria
  38           schema:
  39             type: array
  40             items:
  41               $ref: '#/definitions/Job'
  42   /api/labs/{lab-name}/jobs/current:
  43     get:
  44       summary: list of unfinished jobs
  45       description: |
  46         List of jobs for <lab-name> that are still in progress. A job is in progress if
  47         it has been started but has not finished.
  48       produces:
  49       - application/json
  50       parameters:
  51       - name: lab-name
  52         in: path
  53         required: true
  54         type: string
  55       responses:
  56         200:
  57           description: search results matching criteria
  58           schema:
  59             type: array
  60             items:
  61               $ref: '#/definitions/Job'
  62   /api/labs/{lab-name}/jobs/done:
  63     get:
  64       summary: list of done jobs
  65       description: |
  66         List of jobs for <lab-name> that were started and are no longer in progress.
  67         A job can be marked 'done' with a succesful or error status.
  68       produces:
  69       - application/json
  70       parameters:
  71       - name: lab-name
  72         in: path
  73         required: true
  74         type: string
  75       responses:
  76         200:
  77           description: search results matching criteria
  78           schema:
  79             type: array
  80             items:
  81               $ref: '#/definitions/Job'
  82   /api/labs/{lab-name}/jobs/{job_id}/{task_id}>:
  83     post:
  84       summary: update job information
  85       produces:
  86       - application/json
  87       parameters:
  88       - name: lab-name
  89         in: path
  90         required: true
  91         type: string
  92       - name: job_id
  93         in: path
  94         required: true
  95         type: integer
  96       - name: task_id
  97         in: path
  98         required: true
  99         type: string
 100       - in: body
 101         name: payload
 102         description: payload, schema based on job type
 103         required: true
 104         schema:
 105           $ref: '#/definitions/JobUpdate'
 106       responses:
 107         200:
 108           description: success
 109   /api/labs/{lab-name}/inventory:
 110     get:
 111       summary: lab inventory
 112       produces:
 113       - application/json
 114       parameters:
 115       - name: lab-name
 116         in: path
 117         required: true
 118         type: string
 119       responses:
 120         200:
 121           description: lab inventory
 122           schema:
 123             $ref: '#/definitions/Inventory'
 124     post:
 125       summary: updates lab inventory
 126       parameters:
 127       - name: lab-name
 128         in: path
 129         required: true
 130         type: string
 131       - in: body
 132         name: inventory
 133         required: true
 134         schema:
 135           $ref: '#/definitions/Inventory'
 136       responses:
 137         200:
 138           description: success
 139   /api/labs/{lab-name}/profile:
 140     get:
 141       summary: lab profile
 142       produces:
 143       - application/json
 144       parameters:
 145       - name: lab-name
 146         in: path
 147         required: true
 148         type: string
 149       responses:
 150         200:
 151           description: lab profile
 152           schema:
 153             $ref: '#/definitions/Profile'
 154     post:
 155       summary: updates lab profile
 156       parameters:
 157       - name: lab-name
 158         in: path
 159         required: true
 160         type: string
 161       - in: body
 162         name: profile
 163         required: true
 164         schema:
 165           $ref: '#/definitions/Profile'
 166       responses:
 167         200:
 168           description: success
 169 definitions:
 170   Host_Interface:
 171     properties:
 172       mac:
 173         type: string
 174         example: 00:11:22:33:44:55
 175         description: mac address
 176       busaddr:
 177         type: string
 178         example: 0000:02:00.1
 179         description: bus address reported by `ethtool -i <ifname>`
 180       switchport:
 181         $ref: '#/definitions/Switchport'
 182   Generic_Interface:
 183     properties:
 184       speed:
 185         type: string
 186         example: 10G
 187         description: speed in M or G
 188       name:
 189         type: string
 190         example: eno3
 191         description: interface name
 192   Generic_Disk:
 193     properties:
 194       size:
 195         type: string
 196         example: 500G
 197         description: size in M, G, or T
 198       type:
 199         type: string
 200         example: SSD
 201         description: must be SSD or HDD
 202       name:
 203         type: string
 204         example: sda
 205         description: name of root block device
 206   CPU:
 207     properties:
 208       cores:
 209         type: integer
 210         format: int32
 211         example: 64
 212         description: how many CPU cores the host has (across all physical cpus)
 213         minimum: 1
 214       arch:
 215         type: string
 216         example: x86_64
 217         description: must be x86_64 or aarch64
 218       cpus:
 219         type: integer
 220         example: 2
 221         description: Number of different physical CPU chips
 222         minimum: 1
 223   Image:
 224     properties:
 225       name:
 226         type: string
 227       description:
 228         type: string
 229       lab_id:
 230         type: string
 231         description: identifier provided by lab
 232       dashboard_id:
 233         type: string
 234         description: identifier provided by dashboard
 235   Inventory_Host:
 236     properties:
 237       interfaces:
 238         type: array
 239         items:
 240           $ref: '#/definitions/Host_Interface'
 241       hostname:
 242         type: string
 243         example: hpe3.opnfv.iol.unh.edu
 244         description: globally unique fqdn
 245       host_type:
 246         type: string
 247         description: name of host type this host belongs to
 248   Inventory_Network:
 249     properties:
 250       cidr:
 251         type: string
 252         example: 174.0.5.0/24
 253         description: subnet description
 254       gateway:
 255         type: string
 256         example: 174.0.5.1
 257         description: ip of gateway
 258       vlan:
 259         type: integer
 260         example: 100
 261         description: vlan tag of this network
 262   Inventory:
 263     properties:
 264       hosts:
 265         type: array
 266         description: all hosts
 267         items:
 268           $ref: '#/definitions/Inventory_Host'
 269       networks:
 270         type: array
 271         description: all networks
 272         items:
 273           $ref: '#/definitions/Inventory_Network'
 274       images:
 275         type: array
 276         description: available images
 277         items:
 278           $ref: '#/definitions/Image'
 279       host_types:
 280         type: array
 281         description: all host types hosted by a lab
 282         items:
 283           $ref: '#/definitions/Host_Type'
 284   Host_Type:
 285     properties:
 286       cpu:
 287         $ref: '#/definitions/CPU'
 288       disks:
 289         type: array
 290         items:
 291           $ref: '#/definitions/Generic_Disk'
 292       description:
 293         type: string
 294         description: human readable description of host type
 295       interface:
 296         type: array
 297         items:
 298           $ref: '#/definitions/Generic_Interface'
 299       ram:
 300         $ref: '#/definitions/Ram'
 301       name:
 302         type: string
 303         description: lab-unique name
 304   Ram:
 305     properties:
 306       amount:
 307         type: integer
 308         example: 16
 309         description: amount of ram in Gibibytes (GiB)
 310   Switchport:
 311     properties:
 312       switch_name:
 313         type: string
 314         example: Cisco-9
 315         description: name of switch owning this switchport
 316       port_name:
 317         type: string
 318         example: Ethernet1/34
 319         description: name of port on switch
 320       invariant_config:
 321         type: array
 322         description: list of vlans that may not be modified on this port
 323         items:
 324           $ref: '#/definitions/Vlan'
 325       current_config:
 326         type: array
 327         description: list of current vlan configuration
 328         items:
 329           $ref: '#/definitions/Vlan'
 330   Vlan:
 331     properties:
 332       vlan_id:
 333         type: integer
 334         example: 100
 335         description: vlan id
 336         minimum: 1
 337         maximum: 4098
 338       tagged:
 339         type: boolean
 340         example: true
 341         description: whether this vlan is tagged or untagged
 342   Job:
 343     properties:
 344       id:
 345         type: integer
 346         description: globally unique job identifier
 347       payload:
 348         $ref: '#/definitions/JobPayload'
 349   JobPayload:
 350     properties:
 351       hardware:
 352         $ref: '#/definitions/HardwareTask'
 353       software:
 354         $ref: '#/definitions/SoftwareTask'
 355       network:
 356         $ref: '#/definitions/NetworkTask'
 357       access:
 358         $ref: '#/definitions/AccessTask'
 359       snapshot:
 360         $ref: '#/definitions/SnapshotTask'
 361   HardwareTask:
 362     properties:
 363       taskId:
 364         $ref: '#/definitions/HardwareConfig'
 365   SoftwareTask:
 366     properties:
 367       taskId:
 368         $ref: '#/definitions/SoftwarePayload'
 369   NetworkTask:
 370     properties:
 371       taskId:
 372         $ref: '#/definitions/NetworkPayload'
 373   AccessTask:
 374     properties:
 375       taskId:
 376         $ref: '#/definitions/AccessPayload'
 377   SnapshotTask:
 378     properties:
 379       taskId:
 380         $ref: '#/definitions/SnapshotPayload'
 381   SnapshotPayload:
 382     properties:
 383       host:
 384         type: string
 385         example: hpe3
 386         description: how the lab identifies the host
 387       image:
 388         type: string
 389         example: "4"
 390         description: lab id of existing image, if updating an existing image. if this key does not exist, the lab must create a new image
 391       dashboard_id:
 392         type: string
 393         description: how the dashboard identifies this image / snapshot
 394   AccessPayload:
 395     properties:
 396       revoke:
 397         type: boolean
 398         description: whether to revoke key during completion of job
 399       user:
 400         type: string
 401         description: PK/ID of user access is being given to
 402       access_type:
 403         type: string
 404         example: ssh
 405         description: type of access key to be generated. Options include "vpn and ssh"
 406       hosts:
 407         type: array
 408         description: hosts to grant access to if applicable
 409         items:
 410           type: string
 411           description: id of host
 412       lab_token:
 413         type: string
 414         description: identifier provided by lab to this task
 415   HardwareConfig:
 416     properties:
 417       id:
 418         type: string
 419         description: ID of host
 420       image:
 421         type: integer
 422         example: 42
 423         description: lab provided ID of the request image
 424       power:
 425         type: string
 426         example: on
 427         description: desired power state, either on or off
 428       hostname:
 429         type: string
 430         example: my_new_machine
 431         description: user-defined hostname
 432       ipmi_create:
 433         type: boolean
 434         description: whether or not to create an ipmi account
 435       lab_token:
 436         type: string
 437         description: identifier provided by lab to this task
 438   SoftwarePayload:
 439     properties:
 440       opnfv:
 441         $ref: '#/definitions/OpnfvConfiguration'
 442       lab_token:
 443         type: string
 444         description: identifier provided by lab to this task
 445   OpnfvHost:
 446     properties:
 447       hostname:
 448         type: string
 449         example: Jumphost
 450         description: maps hostname to OPNFV role
 451   OpnfvConfiguration:
 452     properties:
 453       installer:
 454         type: string
 455         description: Installer user wants
 456       scenario:
 457         type: string
 458         description: scenario of OPNFV to deploy
 459       pdf:
 460         type: string
 461         example: LaaS.com/api/my_job/pdf
 462         description: URL to find the Pod Descriptor File contents
 463       idf:
 464         type: string
 465         example: LaaS.com/api/my_job/idf
 466         description: URL to find the Installer Descriptor File contents
 467       roles:
 468         type: array
 469         description: role the host will play in OPNFV
 470         items:
 471           $ref: '#/definitions/OpnfvHost'
 472   NetworkPayload:
 473     properties:
 474       hostId:
 475         $ref: '#/definitions/NetworkConfig'
 476       lab_token:
 477         type: string
 478         description: identifier provided by lab to this task
 479   NetworkConfig:
 480     properties:
 481       interface_name:
 482         type: array
 483         description: list of vlans on this interface
 484         items:
 485           $ref: '#/definitions/Vlan'
 486   JobUpdate:
 487     properties:
 488       status:
 489         type: integer
 490         description: status type, see status enum
 491       message:
 492         type: string
 493         description: message from lab for user
 494       lab_token:
 495         type: string
 496         description: identifier provided by lab to this task
 497   Profile:
 498     properties:
 499       name:
 500         type: string
 501         description: proper expanded lab name
 502       contact:
 503         $ref: '#/definitions/Contact'
 504       description:
 505         type: string
 506       host_count:
 507         type: array
 508         items:
 509           $ref: '#/definitions/Host_Number'
 510   Host_Number:
 511     properties:
 512       type:
 513         type: string
 514       count:
 515         type: integer
 516   Contact:
 517     properties:
 518       phone:
 519         type: string
 520         description: phone number at which a lab can be reached
 521       email:
 522         type: string
 523         description: email at which a lab can be reached