From 54af57f485e9abc3bd11d314079b11cbdfe70f0f Mon Sep 17 00:00:00 2001 From: He Jie Xu Date: Wed, 6 Jul 2016 14:35:08 +0800 Subject: [PATCH] api-ref: Complete all the verifications of remote consoles This patch includes all the verifications of remote consoles part of blueprint api-ref-in-rst-pike Co-Authored-By: Markus Zoeller Change-Id: Ib169e4bd931b5a04f31cd0e7c43c161b49eafe5c --- api-ref/source/index.rst | 3 +- api-ref/source/parameters.yaml | 68 +++++++++-- .../source/servers-action-remote-consoles.inc | 107 ++++++++++++++---- api-ref/source/servers-remote-consoles.inc | 58 ++++++++++ 4 files changed, 204 insertions(+), 32 deletions(-) create mode 100644 api-ref/source/servers-remote-consoles.inc diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index ff6dd305a1fb..242f35fe00fa 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -18,10 +18,11 @@ the `API guide `_. .. include:: servers-action-evacuate.inc .. include:: servers-action-deferred-delete.inc .. include:: servers-action-console-output.inc -.. include:: servers-action-remote-consoles.inc .. include:: servers-action-shelve.inc .. include:: servers-action-crash-dump.inc +.. include:: servers-action-remote-consoles.inc .. include:: servers-admin-action.inc +.. include:: servers-remote-consoles.inc .. include:: server-security-groups.inc .. include:: diagnostics.inc .. include:: ips.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 093bb88e7b8d..02e4a0b5c6f6 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -3263,10 +3263,16 @@ os-getRDPConsole: The action. in: body required: true - type: string + type: object os-getRDPConsole-type: description: | - The type of RDP console. The correct value is ``rdp-html5``. + The type of RDP console. The only valid value is ``rdp-html5``. + in: body + required: true + type: string +os-getRDPConsole-url: + description: | + The URL used to connect to the RDP console. in: body required: true type: string @@ -3275,10 +3281,16 @@ os-getSerialConsole: The action. in: body required: true - type: string + type: object os-getSerialConsole-type: description: | - The type of serial console. The correct value is ``serial``. + The type of serial console. The only valid value is ``serial``. + in: body + required: true + type: string +os-getSerialConsole-url: + description: | + The URL used to connect to the Serial console. in: body required: true type: string @@ -3287,10 +3299,16 @@ os-getSPICEConsole: The action. in: body required: true - type: string + type: object os-getSPICEConsole-type: description: | - The type of SPICE console. The correct value is ``spice-html5``. + The type of SPICE console. The only valid value is ``spice-html5``. + in: body + required: true + type: string +os-getSPICEConsole-url: + description: | + The URL used to connect to the SPICE console. in: body required: true type: string @@ -3299,10 +3317,16 @@ os-getVNCConsole: The action. in: body required: true - type: string + type: object os-getVNCConsole-type: description: | - The type of VNC console. The correct value is ``novnc``. + The type of VNC console. The valid values are ``novnc`` and ``xvpvnc``. + in: body + required: true + type: string +os-getVNCConsole-url: + description: | + The URL used to connect to the VNC console. in: body required: true type: string @@ -3600,6 +3624,34 @@ rebuild: in: body required: true type: string +remote_console: + description: | + The remote console object. + in: body + required: true + type: object +remote_console_protocol: + description: | + The protocol of remote console. The valid values are ``vnc``, ``spice``, + ``rdp``, ``serial`` and ``mks``. The protocol ``mks`` is added since + Microversion ``2.8``. + in: body + required: true + type: string +remote_console_type: + description: | + The type of remote console. The valid values are ``novnc``, ``xvpvnc``, + ``rdp-html5``, ``spice-html5``, ``serial``, and ``webmks``. The type + ``webmks`` is added since Microversion ``2.8``. + in: body + required: true + type: string +remote_console_url: + description: | + The URL is used to connect the console. + in: body + required: true + type: string removeFixedIp: description: | The action. diff --git a/api-ref/source/servers-action-remote-consoles.inc b/api-ref/source/servers-action-remote-consoles.inc index d3fb6b4d7420..105a00dd10a1 100644 --- a/api-ref/source/servers-action-remote-consoles.inc +++ b/api-ref/source/servers-action-remote-consoles.inc @@ -1,15 +1,22 @@ .. -*- rst -*- -.. needs:parameter_verification -.. needs:example_verification -.. needs:body_verification -Get Rdp Console (os-getRDPConsole Action) -========================================= +Get RDP Console (os-getRDPConsole Action) (DEPRECATED) +====================================================== .. rest_method:: POST /servers/{server_id}/action + max_version: 2.5 Gets an `RDP `__ console for a server. +.. warning:: + + This action is deprecated in microversion 2.5 and superseded + by the API `Server Remote Consoles`_ in microversion 2.6. + The new API offers a unified API for different console types. + +The only supported connect type is ``rdp-html5``. The ``type`` parameter should +be set as ``rdp-html5``. + Specify the ``os-getRDPConsole`` action in the request body. Normal response codes: 200 @@ -23,11 +30,11 @@ Request .. rest_parameters:: parameters.yaml - - server_id: server_id + - server_id: server_id_path - os-getRDPConsole: os-getRDPConsole - type: os-getRDPConsole-type -**Example Get Rdp Console (os-getRDPConsole Action): JSON request** +**Example Get RDP Console (os-getRDPConsole Action)** .. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-rdp-console-post-req.json :language: javascript @@ -35,20 +42,36 @@ Request Response -------- -**Example Get Rdp Console (os-getRDPConsole Action): JSON response** +.. rest_parameters:: parameters.yaml + + - console: remote_console + - type: os-getRDPConsole-type + - url: os-getRDPConsole-url + +**Example Get RDP Console (os-getRDPConsole Action)** .. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-rdp-console-post-resp.json :language: javascript -Get Serial Console (os-getSerialConsole Action) -=============================================== +Get Serial Console (os-getSerialConsole Action) (DEPRECATED) +============================================================ .. rest_method:: POST /servers/{server_id}/action + max_version: 2.5 Gets a serial console for a server. +.. warning:: + + This action is deprecated in microversion 2.5 and superseded + by the API `Server Remote Consoles`_ in microversion 2.6. + The new API offers a unified API for different console types. + Specify the ``os-getSerialConsole`` action in the request body. +The only supported connection type is ``serial``. The ``type`` parameter +should be set as ``serial``. + Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), @@ -60,11 +83,11 @@ Request .. rest_parameters:: parameters.yaml - - server_id: server_id + - server_id: server_id_path - os-getSerialConsole: os-getSerialConsole - type: os-getSerialConsole-type -**Example Get Serial Console (os-getSerialConsole Action): JSON request** +**Example Get Serial Console (os-getSerialConsole Action)** .. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-serial-console-post-req.json :language: javascript @@ -72,20 +95,36 @@ Request Response -------- -**Example Get Serial Console (os-getSerialConsole Action): JSON response** +.. rest_parameters:: parameters.yaml + + - console: remote_console + - type: os-getSerialConsole-type + - url: os-getSerialConsole-url + +**Example Get Serial Console (os-getSerialConsole Action)** .. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-serial-console-post-resp.json :language: javascript -Get Spice Console (os-getSPICEConsole Action) -============================================= +Get SPICE Console (os-getSPICEConsole Action) (DEPRECATED) +========================================================== .. rest_method:: POST /servers/{server_id}/action + max_version: 2.5 Gets a SPICE console for a server. +.. warning:: + + This action is deprecated in microversion 2.5 and superseded + by the API `Server Remote Consoles`_ in microversion 2.6. + The new API offers a unified API for different console types. + Specify the ``os-getSPICEConsole`` action in the request body. +The only supported connection type is ``spice-html5``. The ``type`` parameter +should be set to ``spice-html5``. + Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), @@ -97,11 +136,11 @@ Request .. rest_parameters:: parameters.yaml - - server_id: server_id + - server_id: server_id_path - os-getSPICEConsole: os-getSPICEConsole - type: os-getSPICEConsole-type -**Example Get Spice Console (os-getSPICEConsole Action): JSON request** +**Example Get Spice Console (os-getSPICEConsole Action)** .. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-spice-console-post-req.json :language: javascript @@ -109,20 +148,36 @@ Request Response -------- -**Example Get Spice Console (os-getSPICEConsole Action): JSON response** +.. rest_parameters:: parameters.yaml + + - console: remote_console + - type: os-getSPICEConsole-type + - url: os-getSPICEConsole-url + +**Example Get SPICE Console (os-getSPICEConsole Action)** .. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-spice-console-post-resp.json :language: javascript -Get Vnc Console (os-getVNCConsole Action) -========================================= +Get VNC Console (os-getVNCConsole Action) (DEPRECATED) +====================================================== .. rest_method:: POST /servers/{server_id}/action + max_version: 2.5 Gets a VNC console for a server. +.. warning:: + + This action is deprecated in microversion 2.5 and superseded + by the API `Server Remote Consoles`_ in microversion 2.6. + The new API offers a unified API for different console types. + Specify the ``os-getVNCConsole`` action in the request body. +The supported connection types are ``novnc``, ``xvpvnc``. Such as connect +with ``novnc``, set ``type`` parameter to ``novnc``. + Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), @@ -134,11 +189,11 @@ Request .. rest_parameters:: parameters.yaml - - server_id: server_id + - server_id: server_id_path - os-getVNCConsole: os-getVNCConsole - type: os-getVNCConsole-type -**Example Get Vnc Console (os-getVNCConsole Action): JSON request** +**Example Get Vnc Console (os-getVNCConsole Action)** .. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-vnc-console-post-req.json :language: javascript @@ -146,7 +201,13 @@ Request Response -------- -**Example Get Vnc Console (os-getVNCConsole Action): JSON response** +.. rest_parameters:: parameters.yaml + + - console: remote_console + - type: os-getVNCConsole-type + - url: os-getVNCConsole-url + +**Example Get VNC Console (os-getVNCConsole Action)** .. literalinclude:: ../../doc/api_samples/os-remote-consoles/get-vnc-console-post-resp.json :language: javascript diff --git a/api-ref/source/servers-remote-consoles.inc b/api-ref/source/servers-remote-consoles.inc new file mode 100644 index 000000000000..4fd8e7c9d62e --- /dev/null +++ b/api-ref/source/servers-remote-consoles.inc @@ -0,0 +1,58 @@ +.. -*- rst -*- + +====================== +Server Remote Consoles +====================== + +Create server remote console. + +Create Remote Console +===================== + +.. rest_method:: POST /servers/{server_id}/remote-consoles + +.. note:: Microversion 2.6 or greater is required for this API. + +The API provides a unified request for creating a remote console. The user can +get a URL to connect the console from this API. The URL includes the token +which is used to get permission to access the console. Servers may support +different console protocols. To return a remote console using a specific +protocol, such as RDP, set the ``protocol`` parameter to ``rdp``. For the same +protocol, there may be different connection types such as ``vnc protocal and +novnc type`` or ``vnc protocol and xvpvnc type``. + +Normal response codes: 200 + +Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), +conflict(409), notImplemented(501) + +Request +------- + +.. rest_parameters:: parameters.yaml + + + - server_id: server_id_path + - remote_console: remote_console + - protocol: remote_console_protocol + - type: remote_console_type + +**Example Get Remote VNC Console** + +.. literalinclude:: ../../doc/api_samples/os-remote-consoles/v2.6/create-vnc-console-req.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - remote_console: remote_console + - protocol: remote_console_protocol + - type: remote_console_type + - url: remote_console_url + +**Example Get Remote VNC Console** + +.. literalinclude:: ../../doc/api_samples/os-remote-consoles/v2.6/create-vnc-console-resp.json + :language: javascript