ovirt4.3部分开发文档分析
本文主要翻译Red Hat Virtualization4.3的部分开发文档,也就是ovirt4.3。
全文档链接:Product Documentation for Red Hat Virtualization 4.3
Rest API文档:REST API GUIDE
Rest API文档
CHAPTER 1. 简介
Red Hat虚拟化管理器提供了一个Representational State Transfer (REST) API。该API为软件开发人员和系统管理员提供了对标准web接口之外的Red Hat虚拟化环境的控制。对于开发人员和管理员来说,该API非常有用,可以将Red Hat虚拟化环境的功能与通过标准超文本传输协议(HTTP)访问API的自定义脚本或外部应用程序集成在一起。
API的优势:
- 广泛的客户端支持——任何支持HTTP协议的编程语言、框架或系统都可以使用该API。
- 自描述——客户机应用程序只需要很少的虚拟化基础设施知识,因为很多细节都是在运行时发现的。
- 基于资源的模型——基于资源的REST模型提供了一种自然地管理虚拟化平台的方法。
1.1. REST(Representational State Transfer)
表述性状态转移(Representational State Transfer, REST)是一种设计体系结构,它关注特定服务的资源及其表示。资源表示是信息的关键抽象,它对应于服务器上的一个特定托管元素。客户机向位于统一资源标识符(URI)的服务器元素发送请求,并使用标准HTTP方法执行操作,比如GET、POST、PUT和DELETE。这提供了客户机和服务器之间的无状态通信,其中每个请求独立于任何其他请求,并包含完成请求所需的所有信息。
1.2. API 前提条件
使用Red Hat虚拟化API的先决条件:
- 一个拥有安装了网络服务的Red Hat虚拟化管理平台,它需要包括API
- 一个从API服务器发起和接收HTTP请求的客户机或编程库。
例如:
oVirt Python SDK。
oVirt Ruby SDK。
oVirt Java SDK。
cURL命令行工具。
RESTClient,用于RESTful web服务的调试器。 - 了解用于REST API交互的超文本传输协议(HTTP)。
- 了解可扩展标记语言(XML)或JavaScript对象表示法(JSON),API使用它们来构造资源表示。
CHAPTER 2. 身份验证和安全
2.1. TLS/SSL 证书
Red Hat虚拟化API需要超文本传输协议安全(HTTPS)来与客户端软件(如SDK和CLI组件)进行安全交互。这包括获取服务器使用的CA证书,并将其导入客户机的证书存储区。
2.1.1. 获取CA认证
您可以从Red Hat虚拟化管理器获得CA证书,并使用以下方法之一将其传输到客户机:
- 方法一:
获取CA证书的首选方法是使用openssl s_client命令行工具与服务器执行真正的TLS握手,然后提取它所提供的证书。运行这样的命令:
$ openssl s_client \
-connect myengine.example.com:443 \
-showcerts \
< /dev/null
该命令将连接到服务器,并显示如下输出:
CONNECTED(00000003)
depth=1 C = US, O = Example Inc., CN = myengine.example.com.23416
verify error:num=19:self signed certificate in certificate chain
---
Certificate chain
0 s:/C=US/O=Example Inc./CN=myengine.example.com
i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIEaTCCA1GgAwIBAgICEAQwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
SVlJe7e5FTEtHJGTAeWWM6dGbsFhip5VXM0gfqg=
-----END CERTIFICATE-----
1 s:/C=US/O=Example Inc./CN=myengine.example.com.23416
i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----
在 -----BEGIN CERTIFICATE----- 和 -----END CERTIFICATE----- 标记之间的文本显示了服务器提供的证书。第一个是服务器本身的证书,后一个是CA的证书。将CA证书(包括标记)复制到CA. crt文件中。结果应该是这样的:
-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----
【注意!】这是获得服务器使用的CA证书的最可靠的方法。这里描述的其他方法在大多数情况下都可以工作,但是如果CA证书被服务器管理员手动替换,它们将无法获得正确的CA证书。
- 方法二:
如果不能使用上面描述的openssl s_client方法,则可以使用命令行工具从Red Hat虚拟化管理器下载CA证书。
命令行工具的例子包括curl和wget,它们都可以在多个平台上使用。
如果使用curl,例子如下:
$ curl \
--output ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'
如果使用wget,例子如下:
$ wget \
--output-document ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'
- 方法三:
使用网页浏览器浏览位于:
https://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA
根据所选浏览器的不同,证书将下载或导入浏览器的密钥存储库。
如果浏览器下载证书:将文件保存为ca.crt。
如果浏览器导入证书:从浏览器的认证选项中导出证书,并将其保存为ca.crt。
- 方法四:
登录到Red Hat虚拟化管理器,从信任存储库导出证书,并将其复制到客户机。
- 以root用户身份登录到Red Hat虚拟化管理器机器。
- 使用Java keytool管理实用工具从信任库导出证书:
# keytool \
-keystore /etc/pki/ovirt-engine/.truststore \
-storepass mypass \
-exportcert \
-alias cacert \
-rfc \
-file ca.crt
这将创建一个名为ca.crt的证书文件。
- 使用scp命令将证书复制到客户端计算机:
$ scp ca.crt myuser@myclient.example.com:/home/myuser/.
这里的每种方法都会在您的客户机上生成一个名为ca.crt的证书文件,然后必须将此文件导入客户机的证书存储区。
2.1.2. 向客户端导入证书
向客户机导入证书取决于客户机如何存储和解释证书。有关导入证书的更多信息,请参阅客户端文档。
2.2. 认证
任何拥有Red Hat虚拟化管理器帐户的用户都可以访问该API。所有请求都必须使用OAuth或基本身份验证进行身份验证,如下所述。
2.2.1. OAuth 认证
从Red Hat虚拟化的4.0版本开始,首选的身份验证机制是OAuth 2.0,如RFC 6749中所述。
OAuth是一种复杂的协议,具有几种获取授权和访问令牌的机制。对于与Red Hat虚拟化API一起使用,唯一受支持的是资源所有者密码凭证授权,如RFC 6749的4.3节所述。
您必须首先获得一个令牌,将用户名和密码发送到Red Hat Virtualization Manager单点登录服务:
POST /ovirt-engine/sso/oauth/token HTTP/1.1
Host: myengine.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
请求体必须包含grant_type、范围、用户名和密码参数:
表2.1 OAuth令牌请求参数
| Name | Value |
|---|---|
| grant_type | password |
| scope | ovirt-app-api |
| username | admin@internal |
| password | mypassword |
这些参数必须是url编码的。例如,用户名中的@字符需要编码为%40。最终的请求体将是这样的:
grant_type=password&scope=ovirt-app-api&username=admin%40internal&password=mypassword
【注意!!!】范围参数在OAuth RFC中被描述为可选的,但是当它与Red Hat虚拟化API一起使用时,它是强制性的,它的值必须是ovirt-app-api。
如果用户名和密码是有效的,Red Hat虚拟化管理器单点登录服务将响应一个类似于如下的JSON文档:
{
"access_token": "fqbR1ftzh8wBCviLxJcYuV5oSDI=",
"token_type": "bearer",
"scope": "...",
...
}
对于API身份验证目的,唯一相关的名称/值对是access_token。不要以任何方式操控它,请完全按照SSO服务提供的方式使用它。
一旦获得了令牌,就可以使用它来执行对API的请求,方法是将它包含在HTTP的Authorization头中,并使用Bearer模式。
例如,要获取虚拟机列表,发送如下请求:
GET /ovirt-engine/api/vms HTTP/1.1
Host: myengine.example.com
Accept: application/xml
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
令牌可以多次用于多个请求,但它最终将过期。当它过期时,服务器将拒绝请求,并返回401 HTTP响应:
HTTP/1.1 401 Unauthorized
发生这种情况时,需要一个新的令牌,因为Red Hat虚拟化管理器单点登录服务目前不支持刷新令牌。可以使用上面描述的相同方法请求一个新的令牌。
2.2.2. 基本认证
【注意!!!】基本认证只支持向后兼容。从Red Hat虚拟化的4.0版本开始,它就被弃用了,并将在将来被删除。
本文在这部分就省略了。
2.2.3. 认证会话
该API还提供了身份验证会话支持。发送带有身份验证细节的初始请求,然后使用会话cookie发送所有后续请求进行身份验证。
请求经过身份验证的会话过程
- 发送一个报头包含授权(authorization)和持续验证(prefer)设置如下:
HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==
Prefer: persistent-auth
HTTP/1.1 200 OK
...
这将返回一个响应,其头部如下:
Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/ovirt-engine/api; Secure
请注意JSESSIONID的值。在本例中,值为5dQja5ubr4yvI2MM2z+LZxrK。
- 发送所有后续请求,其中包含preferred: persistence -auth和Cookie头JSESSIONID的值。当使用经过身份验证的会话时,不再需要授权头(Authorization)。
HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Prefer: persistent-auth
Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK
HTTP/1.1 200 OK
...
- 当不再需要会话时,向服务器发送请求,其中不包含preferred: persistence -auth头。
HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==
HTTP/1.1 200 OK
...
CHAPTER 3. 基本概念
3.1. 类型
API使用类型概念来描述接受和返回的不同类型的对象。有三种相关类型:
- 初始类型
描述简单类型的对象,如字符串或整数。 - 枚举类型
描述有效值列表,如VmStatus(虚拟机状态)或DiskFormat(磁盘格式)。 - 结构化类型
描述具有多个属性和链接的结构化对象,如Vm(虚拟机)或Disk(磁盘)。
3.2. 已标识类型
API使用的许多类型表示为已标识的对象,这些对象具有唯一的标识符,并且独立于其他对象存在。用于描述这些对象的类型扩展了已标识的类型,该类型包含以下一组公共属性:
| 属性 | 类型 | 描述 |
|---|---|---|
| id | String | 虚拟化基础设施中的每个对象都包含一个id,它充当唯一标识符 |
| href | String | 对象作为绝对路径的规范位置 |
| name | String | 由用户提供的对象可读名称,name在同一类型的所有对象中都是唯一的。 |
| descript ion | String | 由用户提供的一个自由形式的可读对象描述。 |
【注意!】
目前,对于大多数类型的对象,属性id实际上是随机生成的UUID,但这是一个实现细节,用户不应该依赖于它,因为它将来可能会发生变化。相反,用户应该假设这些标识符只是字符串。
3.3 对象
对象是API支持的类型的单独实例。例如,标识符为123的虚拟机是Vm类型的对象。
3.4 集合
集合是同一类型的一组对象。
3.5 表示
当对象在客户机和服务器之间传输时,需要表示对象的状态。API支持XML和JSON作为对象状态的表示,用于输入和输出。
3.5.1 XML 表示
对象的XML表示由对应于对象类型的XML元素、id和href属性的XML元素以及其他属性的嵌套XML元素组成。例如,虚拟机的XML表示如下:
<vm id="123" href="/ovirt-engine/api/vms/123">
<name>myvm</name>
<description>My VM</description>
<memory>1073741824</memory>
...
</vm>
对象集合的XML表示形式由一个XML元素组成,该元素以对象的类型复数命名。
它包含集合对象的表示。例如,虚拟机集合的XML表示如下:
<vms>
<vm id="123" href="/ovirt-engine/api/vms/123">
<name>yourvm</name>
<description>Your VM</description>
<memory>1073741824</memory>
...
</vm>
<vm id="456" href="/ovirt-engine/api/vms/456">
<name>myname</name>
<description>My description</description>
<memory>2147483648</memory>
...
</vm>
...
</vms>
【注意!】
在对象的XML表示中,id和href属性是唯一表示为XML元素的属性,其余的表示为嵌套的XML元素。
3.5.2 JSON 表示
对象的JSON表示由一个JSON文档组成,其中包含每个属性的名称/值对(包括id和href)。例如,虚拟机的JSON表示如下:
{
"id": "123",
"href": "/ovirt-engine/api/vms/123",
"name": "myvm",
"description": "My VM",
"memory": 1073741824,
...
}
对象集合的JSON表示由一个JSON文档组成,该文档包含一个名称/值对(以对象的类型命名,用单数表示),该名称/值对又包含一个表示集合对象的数组。例如,一个虚拟机集合的JSON表示如下:
{
"vm": [
{
"id": "123",
"href": "/ovirt-engine/api/vms/123",
"name": "myvm",
"description": "My VM",
"memory": 1073741824,
...
},
{
"id": "456",
"href": "/ovirt-engine/api/vms/456",
"name": "yourvm",
"description": "Your VM",
"memory": 2147483648,
...
},
]
}
3.6 服务
服务是服务器的一部分,负责检索、添加更新、删除和执行API支持的对象上的操作。
有两种相关的服务:
管理对象集合的服务
这些服务负责列出现有对象和添加新对象。例如,Vms服务负责管理系统中可用虚拟机的集合。
管理特定对象的服务
这些服务负责检索、更新、删除和执行特定对象中的操作。例如,Vm服务负责管理特定的虚拟机。
每个服务都可以通过服务器中的特定路径访问。例如,管理系统中可用的虚拟机集合的服务通过路径 /vms访问,管理虚拟机123的服务通过路径 /vms/123访问。
所有类型的服务都有一组表示它们可以执行的操作的方法。管理对象集合的服务通常具有list和add方法,管理特定对象的服务通常具有get、update和remove方法。此外,服务还可能具有表示较不常见操作的操作方法。例如,Vm服务有一个用于启动虚拟机的start方法。
对于更常见的方法,方法的名称和HTTP方法的名称之间有一个直接的映射:
| 方法名称 | HTTP方法 |
|---|---|
| add | POST |
| get | GET |
| list | GET |
| update | PUT |
| remove | DELETE |
HTTP请求中使用的路径是服务的路径,带有/ovirt-engine/api前缀。
例如,使用HTTP GET方法和路径 /vms列出虚拟机的请求应该是这样的:
GET /ovirt-engine/api/vms
对于操作方法,HTTP方法总是POST,方法的名称作为后缀添加到路径中。例如,使用HTTP POST方法和路径/vms/123/start启动虚拟机123的请求应该是这样的:
POST /ovirt-engine/api/vms/123/start
每个方法都有一组参数。参数分为两类:
主参数
主参数对应于检索、添加或更新的对象或集合。这只适用于add、get、list和update方法,而且每个方法都有一个这样的主参数。
次要参数
其余参数。
例如,添加虚拟机的操作有三个参数:vm、clone和clone_permissions。主要参数是vm,因为它描述了添加的对象。clone和clone_permissions参数是次要参数。
用于输入的主要参数必须包含在HTTP请求的主体中。例如,在添加虚拟机时,必须在请求体中包含vm类型的vm参数。因此,添加虚拟机的完整请求,包括所有HTTP细节,必须如下所示:
POST /ovirt-engine/api/vms HTTP/1.1
Host: myengine.example.com
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
Content-Type: application/xml
Accept: application/xml
<vm>
<name>myvm</name>
<description>My VM</description>
<cluster>
<name>Default</name>
</cluster>
<template>
<name>Blank</name>
</template>
</vm>
当用于输出时,主要参数包含在响应体中。例如,在添加虚拟机时,vm参数将包含在响应体中。所以完整的响应体应该是这样的:
HTTP/1.1 201 Created
Content-Type: application/xml
<vm href="/ovirt-engine/api/vms/123" id="123">
<name>myvm</name>
<description>My VM</description>
...
</vm>
次要参数只允许用于输入(操作方法除外,稍后将对此进行描述),并且它们必须包含为查询参数。例如,当添加clone参数设置为true的虚拟机时,完整的请求必须如下所示:
POST /ovirt-engine/api/vms?clone=true HTTP/1.1
Host: myengine.example.com
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
Content-Type: application/xml
Accept: application/xml
<vm>
<name>myvm</name>
<description>My VM</description>
<cluster>
<name>Default</name>
</cluster>
<template>
<name>Blank</name>
</template>
</vm>
操作方法只有次要参数,它们可以用于输入和输出,并且应该包含在请求体中,并使用action元素进行包装。例如,用于启动虚拟机的操作方法,有一个vm参数来描述应该如何启动虚拟机,以及一个use_cloud_init参数来指定是否应该使用cloud-init来配置客户操作系统。
因此,使用cloud-init启动虚拟机123的完整请求在使用XML时是这样的:
POST /ovirt-engine/api/vms/123/start HTTP/1.1
Host: myengine.example.com
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
Content-Type: application/xml
Accept: application/xml
<action>
<use_cloud_init>true</use_cloud_init>
<vm>
<initialization>
<nic_configurations>
<nic_configuration>
<name>eth0</name>
<on_boot>true</on_boot>
<boot_protocol>static</boot_protocol>
<ip>
<address>192.168.0.100</address>
<netmask>255.255.255.0</netmask>
<gateway>192.168.0.1</netmask>
</ip>
</nic_configuration>
</nic_configurations>
<dns_servers>192.168.0.1</dns_servers>
</initialization>
</vm>
</action>
3.7 搜索
一些服务的list方法有一个搜索参数,可用于指定搜索条件。使用时,服务器只返回满足这些条件的集合中的对象。例如,下面的请求将只返回名为myvm的虚拟机:
GET /ovirt-engine/api/vms?search=name%3Dmyvm
以下一些具体操作省略,需要使用的可以自行查看。
Chapter3
3.8 追寻链接
API将相关对象的引用作为链接返回。例如,当检索虚拟机时,它包含到其磁盘附件和网络接口卡的链接:
<vm id="123" href="/ovirt-engine/api/vms/123">
...
<link rel="diskattachments" href="/ovirt-engine/api/vms/123/diskattachments"/>
<link rel="nics" href="/ovirt-engine/api/vms/123/nics"/>
...
</vm>
通过发送单独的请求,可以检索到这些链接对象的完整描述:
GET /ovirt-engine/api/vms/123/diskattachments
GET /ovirt-engine/api/vms/123/nics
然而,在某些情况下,应用程序使用API检索相同请求中的链接信息更为方便。例如,当额外的网络往返带来不可接受的开销时,或者当多个请求以不可接受的方式使应用程序代码复杂化时。对于这些用例,API提供了一个follow参数,该参数允许应用程序仅使用一个请求检索链接的信息。
follow参数的值是由逗号分隔的字符串列表,每个字符串都是链接对象的路径。例如,要检索上面例子中的磁盘附件和nic,请求应该是这样的:
GET /ovirt-engine/api/vms/123?follow=disk_attachments,nics
它将会返回一个如下的回复:
<vm id="123" href="/ovirt-engine/api/vms/123">
...
<disk_attachments>
<disk_attachment id="456" href="/ovirt-engine/api/vms/123/diskattachments/456">
<active>true</active>
<bootable>true</bootable>
<interface>virtio_scsi</interface>
<pass_discard>false</pass_discard>
<read_only>false</read_only>
<uses_scsi_reservation>false</uses_scsi_reservation>
<disk id="789" href="/ovirt-engine/api/disks/789"/>
</disk_attachment>
...
</disk_attacments>
<nics>
<nic id="234" href="/ovirt-engine/api/vms/123/nics/234">
<name>eth0</name>
<interface>virtio</interface>
<linked>true</linked>
<mac>
<address>00:1a:4a:16:01:00</address>
</mac>
<plugged>true</plugged>
</nic>
...
</nics>
...
</vm>
链接对象的路径可以是一个单词,就像前面的例子中那样,也可以是一个单词序列,用点分隔,以请求嵌套数据。例如,前一个示例使用disk_attachments来检索磁盘附件的完整描述,但是每个磁盘附件都包含一个到磁盘的链接,它没有追寻这个链接。若要跟随连结至磁碟,可使用以下请求:
POST /ovirt-engine/api/vms/123?follow=disk_attachments.disk
它将会返回如下的回复:
<vm id="123" href="/ovirt-engine/api/vms/123">
<disk_attachments>
<disk_attachment id="456" href="/ovirt-engine/api/vms/123/diskattachments/456">
<active>true</active>
<bootable>true</bootable>
<interface>virtio_scsi</interface>
<pass_discard>false</pass_discard>
<read_only>false</read_only>
<uses_scsi_reservation>false</uses_scsi_reservation>
<disk id="789" href="/ovirt-engine/api/disks/789">
<name>mydisk</name>
<description>My disk</description>
<actual_size>0</actual_size>
<format>raw</format>
<sparse>true</sparse>
<status>ok</status>
<storage_type>image</storage_type>
<total_size>0</total_size>
...
</disk>
</disk_attachment>
...
</disk_attachments>
...
</vm>
这条路径可以走得有多深就有多深。例如,还可以得到磁盘的统计信息:
POST /ovirt-engine/api/vms/123?follow=disk_attachments.disk.statistics
可以组合多个路径元素和多个路径。例如,获取磁盘附件和网络接口卡,以及它们的统计数据:
POST /ovirt-engine/api/vms/123?follow=disk_attachments.disk.statistics,nics.statistics
本文详细介绍了ovirt4.3的REST API,包括REST概念、API的前提条件,以及身份验证和安全的TLS/SSL证书获取与导入。文章强调了API的广泛客户端支持、自描述性和基于资源的模型。此外,还深入讨论了身份验证机制,如OAuth 2.0和基本认证,并提供了导入服务器证书的方法。

5342

被折叠的 条评论
为什么被折叠?



