cloudpods/docs/instance.yaml

swagger: "2.0"
info:
  title: "OneCloud API"
  version: "1.0"
  termsOfService: ""
  contact:
    email: zhouyousong@yunion.cn
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

host: "10.168.222.136:8889"
basePath: "/"

schemes:
  - https
  - http
consumes:
  - application/json
produces:
  - application/json

tags:
  - name: instance

paths:
  /servers:
    get:
      summary: 按指定条件列出实例
      parameters:
        - $ref: '#/parameters/offsetParam'
        - $ref: '#/parameters/limitParam'
        - $ref: '#/parameters/billingTypeParam'
        - $ref: '#/parameters/baremetalParam'
        - $ref: '#/parameters/hypervisorParam'
        - $ref: '#/parameters/hostParam'
        - $ref: '#/parameters/secgroupParam'
        - $ref: '#/parameters/zoneParam'
        - $ref: '#/parameters/wireParam'
        - $ref: '#/parameters/networkParam'
        - $ref: '#/parameters/vpcParam'
        - $ref: '#/parameters/diskParam'
        - $ref: '#/parameters/regionParam'
        - $ref: '#/parameters/witheipParam'
        - $ref: '#/parameters/withouteipParam'
        - $ref: '#/parameters/gpuParam'
        - $ref: '#/parameters/orderByDiskParam'
        - $ref: '#/parameters/orderByHostParam'
      responses:
        200:
          description: 实例列表信息
          schema:
            $ref: '#/definitions/InstanceListResponse'
      tags:
        - instance
    post:
      summary: 创建实例
      responses:
        200:
          description: 新创建的实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true
    get:
      summary: 获取指定实例详情信息
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
    put:
      summary: 更新实实例信息
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
    delete:
      summary: 删除指定实例
      responses:
        200:
          description: 被删除实例的信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/monitor:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true
    post:
      summary: 发送qemu-monitor指令给实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/save-image:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 保存镜像
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/sync:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 同步配置信息
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/migrate:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 迁移实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/live-migrate:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 在线迁移实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  # /servers/{serverId}/clone:
  #   parameters: 
  #   - name: serverId
  #     type: string
  #     in: path
  #     required: true

  #   post:
  #     summary: 克隆实例
  #     responses:
  #       200:
  #         description: 实例信息
  #         schema:
  #           $ref: '#/definitions/InstanceResponse'
  #     tags:
        - instance
  /servers/{serverId}/deploy:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 重置实例密码信息
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/attach-disk:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 挂载磁盘到实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/suspend:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 休眠实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/start:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 启动实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/insertiso:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 挂载ISO设备到实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/ejectiso:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 卸载实例ISO设备
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/add-secgroup:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 绑定安全组到实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/revoke-secgroup:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 解绑实例安全组
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/assign-secgroup:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 替换实例默认安全组
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/set-secgroup:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 批量设置安全组
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/purge:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 抹除数据库实例数据(不真正删除实例)
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/rebuild-root:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 重装系统
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/createdisk:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 创建磁盘并挂载到实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/detachdisk:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 卸载实例磁盘
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/detach-isolate-device:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 解除透传设备
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/attach-isolate-device:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 透传设备
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/change-ip-addr:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 更改实例IP地址
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/detachnetwork:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 移除实例的网络(解绑网络上的IP地址)
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/attachnetwork:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 实例绑定网络(从网络上分配IP地址)
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/change-bandwidth:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 更改实例网卡带宽
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/change-config:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 更改实例网卡带宽
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/cancel-delete:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 恢复回收站实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/reset:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 重启实例(软重启)
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/syncstatus:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 同步实例状态
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/status:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 更改实例状态
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/stop:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 关闭实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/restart:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 重启实例(硬重启)
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/send-keys:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 发送按键给实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/associate-eip:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 实例关联弹性IP
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/dissociate-eip:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 解绑实例弹性IP
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/create-eip:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 创建并绑定弹性IP给实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/user-data:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 更新实例UserData
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/switch-to-backup:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 备份机转换
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/create-backup:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 添加实例备份机
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/delete-backup:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 删除实例备份机
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/set-extra-option:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 设置实例额外选项(USB透传)
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/del-extra-option:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 删除实例额外选项
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance
  /servers/{serverId}/renew:
    parameters: 
    - name: serverId
      type: string
      in: path
      required: true

    post:
      summary: 续费实例
      responses:
        200:
          description: 实例信息
          schema:
            $ref: '#/definitions/InstanceResponse'
      tags:
        - instance


parameters:
  offsetParam:
    name: offset
    in: query
    type: integer
    default: 0
    description: 查询偏移量
  limitParam:
    name: limit
    in: query
    type: integer
    default: 20
    description: 查询限制量
  billingTypeParam:
    name: billing_type
    in: query
    type: string
    enum: [postpaid, prepaid]
    description: 指定计费类型
  baremetalParam:
    name: baremetal
    in: query
    type: boolean
    description: 过滤裸金属类型实例
  hypervisorParam:
    name: hypervisor
    in: query
    type: string
    enum: [kvm,esxi,container,baremetal,aliyun,azure,aws,huawei,ucloud,qcloud,openstack,zstack]
    description: 过滤虚拟化平台
  hostParam:
    name: host
    in: query
    type: string
    description: 过滤宿主机上的实例
  secgroupParam:
    name: secgroup
    in: query
    type: string
    description: 过滤关联了此安全组的实例
  zoneParam:
    name: zone
    in: query
    type: string
    description: 过滤可用区底下的实例
  wireParam:
    name: wire
    in: query
    type: string
    description: 过滤连接此二层网络的实例
  networkParam:
    name: network
    in: query
    type: string
    description: 过滤关联词网络的实例
  vpcParam:
    name: vpc
    in: query
    type: string
    description: 过滤连接此VPC的实例
  diskParam:
    name: disk
    in: query
    type: string
    description: 过滤挂载此硬盘的实例
  regionParam:
    name: region
    in: query
    type: string
    description: 过滤此区域底下的实例
  witheipParam:
    name: with_eip
    in: query
    type: boolean
    enum: [true]
    description: 过滤关联的eip的实例
  withouteipParam:
    name: without_eip
    in: query
    type: boolean
    enum: [true]
    description: 过滤未关联eip的实例
  gpuParam:
    name: gpu
    in: query
    type: boolean
    enum: [true, false]
    description: 过滤关联GPU卡的实例
  orderByDiskParam:
    name: order_by_disk
    in: query
    type: string
    enum: [desc, asc]
    description: 根据磁盘大小排序
  orderByHostParam:
    name: order_by_host
    in: query
    type: string
    enum: [desc, asc]
    description: 根据宿主机名称排序

definitions:
  InstanceSecgroup:
    properties:
      id:
        type: string
        example: ea27c0ce-5870-49f3-8d57-f53e63f40361
        description: 安全组ID
      name:
        type: string
        example: Default
        description: 安全组名称

  Instance:
    type: object
    description: 实例
    properties:
      id:
        type: string
        example: ea27c0ce-5870-49f3-8d57-f53e63f40361
        description: 实例uuid
        readOnly: true
      name:
        type: string
        description: 实例名称
        example: ins-r4hilqks
        readOnly: true
      billing_type:
        type: string
        description: 计费类型
        example: postpaid
        readOnly: true
      account:
        type: string
        example: office-qcloud
        description: 所属云账号名称
      account_id:
        type: string
        description: 所属云账号ID
      bios:
        type: string
        example: 8ebce595-1a37-473e-8ff8-f02f0b82773d
        description: BIOS信息
      boot_order:
        type: string
        example: cdn
        description: 启动顺序 d(磁盘), c(光盘), n(网络)
      brand:
        type: string
        example: DStack
        description: 虚拟化品牌
      can_delete:
        type: boolean
        description: 是否可删除
      can_recycle:
        type: boolean
        description: 是否可回归资源池
      can_update:
        type: boolean
        description: 是否可以更新资源属性
      cdrom:
        type: string
        example: 536a05a9-0b4a-4464-8eaf-dd5eb3c7b553(inserting)
        description: 光盘信息
      created_at:
        type: string
        example: 2019-05-30T02:25:38.000000Z
        description: 资源创建时间
      disable_delete:
        type: boolean
        description: 是否开启删除保护 true(开启), false(关闭)
      disk:
        type: integer
        example: 51200
        description: 磁盘大小(包含系统盘), 单位Mb
      external_id:
        type: string
        example: ins-r4hilqks
        description: 实例外部ID，对应的纳管云实例ID
      host:
        type: string
        example: office-qcloud-ap-guangzhou-3
        description: 实例所在的宿主机名称
      host_id:
        type: string
        example: c767afc9-9175-4ae6-893b-b990c5c128d6
        description: 实例所在的宿主机ID
      hypervisor:
        type: string
        example: qcloud
        description: 虚拟化平台或技术
      instance_type:
        type: string
        example: SN3ne.SMALL2
        description: 实例规格
      ips:
        type: string 
        example: 10.0.42.4
        description: 虚拟机内网IP
      is_emulated:
        type: boolean 
        example: false
        description: 是否是虚拟出来的实例
      is_gpu:
        type: boolean 
        example: false
        description: GPU实例
      is_system:
        type: boolean 
        example: false
        description: 系统资源
      machine:
        type: string 
        example: pc
        description: 机器
      manager:
        type: string 
        example: office-qcloud
        description: 归属订阅名称
      manager_id:
        type: string 
        example: 30960bb7-4e7b-4df9-8738-b8ceafc99045
        description: 归属订阅ID
      manager_project:
        type: string 
        example: system
        description: 订阅归属项目名称
      manager_project_id:
        type: string 
        example: 29541006ae9148b9bf002fc294218022
        description: 订阅归属项目ID
      os_type:
        type: string 
        example: Linux
        description: 实例系统类型
      project_src:
        type: string 
        example: cloud
        description: 归属项目同步来源
      provider:
        type: string 
        example: Qcloud
        description: 纳管云平台
      region:
        type: string 
        example: 腾讯云 华南地区(广州)
        description: 区域名称
      region_ext_id:
        type: string 
        example: ap-guangzhou
        description: 区域外部ID,对应纳管云区域ID
      region_id:
        type: string 
        example: 13947bd8-569e-4094-8b03-4339c2a8e45b
        description: 区域ID
      secgroups:
        type: array 
        items:
          $ref: '#/definitions/InstanceSecgroup'
        description: 关联安全组列表
      shutdown_behavior:
        type: string 
        example: stop
        description: 关机后操作类型
      status:
        type: string 
        example: running
        description: 资源状态
      tenant:
        type: string 
        example: system
        description: 归属项目名称
      tenant_id:
        type: string 
        example: 29541006ae9148b9bf002fc294218022
        description: 归属项目ID
      update_version:
        type: integer 
        example: 2
        description: 资源被更新的次数
      updated_at:
        type: string 
        example: 2019-05-30T06:36:39.000000Z
        description: 资源最近一次更新时间
      vcpu_count:
        type: integer 
        example: 1
        description: 实例CPU核数
      vdi:
        type: string 
        example: vnc
        description: vnc连接协议
      vga:
        type: string 
        example: std
        description: vga
      vmem_size:
        type: integer 
        example: 2048
        description: 实例内存大小, 单位MB
      vpc:
        type: string 
        example: test-vpc
        description: 虚拟私有网络名称
      vpc_id:
        type: string 
        example: 7712297d-d0eb-4f6d-81e2-c9f768ca8bb6
        description: 虚拟私有网络ID
      zone:
        type: string 
        example: 腾讯云 广州三区
        description: 可用区名称
      zone_ext_id:
        type: string 
        example: ap-guangzhou-3
        description: 可用区外部ID,对应纳管云可用区ID
      zone_id:
        type: string 
        example: a16d3e0b-3fd6-45ec-8b2d-e51a51fa0efc
        description: 可用区ID

  InstanceListResponse:
    type: object
    properties:
      limit: 
        type: integer
        example: 20
      servers:
        type: array
        items:
          $ref: '#/definitions/Instance'
      total:
        type: integer
        example: 124
  InstanceResponse:
    type: object
    properties:
      server:
        type: object
        $ref: '#/definitions/Instance'