OpenStack API Documentation

OpenStack APIs

为了认证对OpenStack服务的访问,你首先需要向OpenStack认证服务发出携带证书信息的认证请求以获得认证令牌。

证书通常是您的用户名和密码的组合,或者是您的云环境中项目的名称或ID。从你的云管理员那里获得你的用户名,密码和项目信息以便于生成认证令牌。相应地,你可以使用这个令牌来代替用户名和密码进行认证操作。

当你发送API请求时,你需要将令牌信息包含在“X-Auth-Token”的消息头中。如果你要访问多个OpenStack的服务,你必须为每个服务获取一个令牌。令牌的有效性是有时间限制的。当然,令牌也可能因为其它原因而失效。例如,如果用户的角色发生了变化,该用户当前存在的令牌也就会失效。

认证和 API 请求工作流程

  1. 从云管理员提供的认证服务接入点请求一个认证令牌,以“ref:authenticate”的形式发送一个有效载荷的请求,如果请求成功,服务器将返回一个认证令牌。
  2. 发送API请求时,令牌信息包含在“X-Auth-Token”的包头中,使用该令牌发送请求,直到请求的服务完成或者Unauthorized (401)错误出现。
  3. 如果Unauthorized (401)错误出现, 重新申请一个令牌。

该部分的实例使用了cURL命令。关于cURL的信息,请参考http://curl.haxx.se/。关于OpenStack APIs的信息,请参考 当前API 版本

认证

The payload of credentials to authenticate contains these parameters:

参数 类型 描述
*用户域*(必需有) 字符串 用户的域
用户名 (必需有) 字符串 用户名。如果您不提供用户名和密码,那么必须提供一个令牌。
密码 (必需有) 字符串 该用户的密码。
*项目域*(可选) 字符串 该项目的域是scope对象的必需部分。
*项目名*(可选) 字符串 项目名。*项目ID*和*项目名*都是可选的。
*项目ID*(可选) 字符串 项目ID。*项目ID*和*项目名*都是可选的。但是伴随着*项目域*这两个属性其中之一是必须有的。这两个属性包含在scope对象下。如果你不知道项目的名称或者ID,发送一个不包含任何scope对象的请求。

在一个运行着认证服务的典型OpenStack环境中,你可以指定你的项目名,用户名和密码进行身份验证。

首先,将你的项目名传递给环境变量``OS_TENANT_NAME``,你的项目域名传递给环境变量``OS_PROJECT_DOMAIN_NAME``,你的用户名传递给环境变量``OS_USERNAME``,你的密码传递给环境变量``OS_PASSWORD``,同时你的用户域名传递给环境变量``OS_USER_DOMAIN_NAME``。

下面例子使用了遵循安装手册安装Ocata。但是,你也可以使用``$OS_AUTH_URL``作为一个环境变量,如果需要改变该URL。

然后,运行cURL命令去请求一个token。

$ curl -v -s -X POST $OS_AUTH_URL/auth/tokens?nocatalog   -H "Content-Type: application/json"   -d '{ "auth": { "identity": { "methods": ["password"],"password": {"user": {"domain": {"name": "'"$OS_USER_DOMAIN_NAME"'"},"name": "'"$OS_USERNAME"'", "password": "'"$OS_PASSWORD"'"} } }, "scope": { "project": { "domain": { "name": "'"$OS_PROJECT_DOMAIN_NAME"'" }, "name":  "'"$OS_PROJECT_NAME"'" } } }}' \
| python -m json.tool

如果请求成功是,将会返回``Created (201)``响应码,同时在``X-Subject-Token``响应头中包含着token值。该请求头伴随着一个响应体,包含一个``token``类型的对象,该对象包含token过期日期和时间,以``”expires_at”:”datetime”``的形式,还包含其它属性。

下面的例子展示了一个成功的响应:

*   Trying 192.168.56.101...
* Connected to controller (192.168.56.101) port 5000 (#0)
> POST /v3/auth/tokens?nocatalog HTTP/1.1
> Host: controller:5000
> User-Agent: curl/7.47.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 226
>
} [226 bytes data]
* upload completely sent off: 226 out of 226 bytes
< HTTP/1.1 201 Created
< Date: Fri, 26 May 2017 06:48:58 GMT
< Server: Apache/2.4.18 (Ubuntu)
< X-Subject-Token: gAAAAABZJ8_a7aiq1SnOhbNw8vFb5WZChcvWdzzUAFzhiB99BHrjdSGai--_-JstU3WazsFXmRHNbD07qOQKTp5Sen2R_b9csaDkU49VXqSaJ0jh2nAlwJkys8aazz2oa3xSeUVe3Ndv_HRiW23-iWTr6jquK_AXdhRX7nvM4lmVTrxXFpelnJQ
< Vary: X-Auth-Token
< X-Distribution: Ubuntu
< x-openstack-request-id: req-0e9239ec-104b-40e0-a337-dca91fb24387
< Content-Length: 521
< Content-Type: application/json
<
{ [521 bytes data]
* Connection #0 to host controller left intact
{
    "token": {
        "audit_ids": [
            "HOGlhnMFT52xY7PjbuJZlA"
        ],
        "expires_at": "2017-05-26T07:48:58.000000Z",
        "is_domain": false,
        "issued_at": "2017-05-26T06:48:58.000000Z",
        "methods": [
            "password"
        ],
        "project": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "05ef0bf2a79c42b2b8155873b6404061",
            "name": "demo"
        },
        "roles": [
            {
                "id": "b18239b7026042ef8695c3c4cf10607b",
                "name": "user"
            }
        ],
        "user": {
            "domain": {
                "id": "default",
                "name": "Default"
            },
            "id": "12846256e60c42f88d0e1ba9711a57f5",
            "name": "demo",
            "password_expires_at": null
        }
    }
}

注解

在上面的请求中,``nocatalog``请求字符串用于当你想要获取一个token,同时并不想要服务目录(如果对于当前用户来说可用)使输出结果混乱时。如果一个用户项目要获取服务目录,该请求字符串不需要添加到URL中。

发送 API 请求

这部分内容展示了如何调用一些基本的计算服务API,对于一个完整的计算API函数列表,请见`Compute API <https://developer.openstack.org/api-ref/compute/>`__。

将token ID传递给环境变量“OS_TOKEN”,例如:

export OS_TOKEN=gAAAAABZJ8_a7aiq1SnOhbNw8vFb5WZChcvWdzzUAFzhiB99BHrjdSGai--_-JstU3WazsFXmRHNbD07qOQKTp5Sen2R_b9csaDkU49VXqSaJ0jh2nAlwJkys8aazz2oa3xSeUVe3Ndv_HRiW23-iWTr6jquK_AXdhRX7nvM4lmVTrxXFpelnJQ

The token expires every hour by default, though it can be configured differently - see the expiration option in the the Identity Service Configuration Guide.

将项目名传递给环境变量``OS_PROJECT_NAME``,例如:

export OS_PROJECT_NAME=demo

之后,可以使用计算服务API来列出所有的云主机类型,使用如下所示的包含在你项目ID中的flavor来替换计算API端点

$ curl -s -H "X-Auth-Token: $OS_TOKEN" \
  $OS_COMPUTE_API/flavors \
  | python -m json.tool
{
    "flavors": [
        {
            "id": "1",
            "links": [
                {
                    "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/1",
                    "rel": "self"
                },
                {
                    "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/1",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.tiny"
        },
        {
            "id": "2",
            "links": [
                {
                    "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/2",
                    "rel": "self"
                },
                {
                    "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/2",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.small"
        },
        {
            "id": "3",
            "links": [
                {
                    "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/3",
                    "rel": "self"
                },
                {
                    "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/3",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.medium"
        },
        {
            "id": "4",
            "links": [
                {
                    "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/4",
                    "rel": "self"
                },
                {
                    "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/4",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.large"
        },
        {
            "id": "5",
            "links": [
                {
                    "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/5",
                    "rel": "self"
                },
                {
                    "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/5",
                    "rel": "bookmark"
                }
            ],
            "name": "m1.xlarge"
        }
    ]
}

从令牌中导出$OS_PROJECT_ID,然后基于计算服务API来列出所有镜像

$ curl -s -H "X-Auth-Token: $OS_TOKEN" \
  http://8.21.28.222:8774/v2/$OS_PROJECT_ID/images \
  | python -m json.tool
{
    "images": [
        {
            "id": "2dadcc7b-3690-4a1d-97ce-011c55426477",
            "links": [
                {
                    "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/2dadcc7b-3690-4a1d-97ce-011c55426477",
                    "rel": "self"
                },
                {
                    "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/2dadcc7b-3690-4a1d-97ce-011c55426477",
                    "rel": "bookmark"
                },
                {
                    "href": "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/2dadcc7b-3690-4a1d-97ce-011c55426477",
                    "type": "application/vnd.openstack.image",
                    "rel": "alternate"
                }
            ],
            "name": "Fedora 21 x86_64"
        },
        {
            "id": "cfba3478-8645-4bc8-97e8-707b9f41b14e",
            "links": [
                {
                    "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/cfba3478-8645-4bc8-97e8-707b9f41b14e",
                    "rel": "self"
                },
                {
                    "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/cfba3478-8645-4bc8-97e8-707b9f41b14e",
                    "rel": "bookmark"
                },
                {
                    "href": "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/cfba3478-8645-4bc8-97e8-707b9f41b14e",
                    "type": "application/vnd.openstack.image",
                    "rel": "alternate"
                }
            ],
            "name": "Ubuntu 14.04 amd64"
        },
        {
            "id": "2e4c08a9-0ecd-4541-8a45-838479a88552",
            "links": [
                {
                    "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/2e4c08a9-0ecd-4541-8a45-838479a88552",
                    "rel": "self"
                },
                {
                    "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/2e4c08a9-0ecd-4541-8a45-838479a88552",
                    "rel": "bookmark"
                },
                {
                    "href": "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/2e4c08a9-0ecd-4541-8a45-838479a88552",
                    "type": "application/vnd.openstack.image",
                    "rel": "alternate"
                }
            ],
            "name": "CentOS 7 x86_64"
        },
        {
            "id": "c8dd9096-60c1-4e23-a486-82955481df9f",
            "links": [
                {
                    "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/c8dd9096-60c1-4e23-a486-82955481df9f",
                    "rel": "self"
                },
                {
                    "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/c8dd9096-60c1-4e23-a486-82955481df9f",
                    "rel": "bookmark"
                },
                {
                    "href": "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/c8dd9096-60c1-4e23-a486-82955481df9f",
                    "type": "application/vnd.openstack.image",
                    "rel": "alternate"
                }
            ],
            "name": "CentOS 6.5 x86_64"
        },
        {
            "id": "f97b8d36-935e-4666-9c58-8a0afc6d3796",
            "links": [
                {
                    "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/f97b8d36-935e-4666-9c58-8a0afc6d3796",
                    "rel": "self"
                },
                {
                    "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/f97b8d36-935e-4666-9c58-8a0afc6d3796",
                    "rel": "bookmark"
                },
                {
                    "href": "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/f97b8d36-935e-4666-9c58-8a0afc6d3796",
                    "type": "application/vnd.openstack.image",
                    "rel": "alternate"
                }
            ],
            "name": "Fedora 20 x86_64"
        }
    ]
}

从令牌中导出$OS_PROJECT_ID,然后基于计算服务API来列出所有服务器

$ curl -s -H "X-Auth-Token: $OS_TOKEN" \
  http://8.21.28.222:8774/v2/$OS_PROJECT_ID/servers \
  | python -m json.tool
{
    "servers": [
        {
            "id": "41551256-abd6-402c-835b-e87e559b2249",
            "links": [
                {
                    "href": "http://8.21.28.222:8774/v2/f8828a18c6484624b571e85728780ba8/servers/41551256-abd6-402c-835b-e87e559b2249",
                    "rel": "self"
                },
                {
                    "href": "http://8.21.28.222:8774/f8828a18c6484624b571e85728780ba8/servers/41551256-abd6-402c-835b-e87e559b2249",
                    "rel": "bookmark"
                }
            ],
            "name": "test-server"
        }
    ]
}

OpenStack 命令行客户端

对于脚本操作和简单的请求,你可以使用像“openstack-client”这样的客户端命令行,这个客户端能让你通过命令行接口去使用认证,计算,块存储,对象存储API。同时每个openstack项目都会有一个包含Python API绑定和命令行接口(CLI)的相关的客户端项目。

获取更多关于命令行客户端的信息,请看`OpenStack命令行接口参考文献: <https://docs.openstack.org/cli-reference/>`__。

安装客户端

使用``pip``在Mac OS X系统或者Linux系统上安装OpenStack客户端,确保从``Python Package Index<http://pypi.python.org/pypi>``获取最新版本的客户端。你也可以使用``pip``去更新或者移除一个包。

你必须为每个工程单独安装客户端,但是``python-openstackclient``可以覆盖多个工程。

安装或者更新一个客户端:

$ sudo pip install [--upgrade] python-PROJECTclient

*PROJECT*是一个工程名。

例如,安装``openstack``客户端:

$ sudo pip install python-openstackclient

运行如下命令更新``openstack``客户端:

$ sudo pip install --upgrade python-openstackclient

运行如下命令移除``openstack``客户端:

$ sudo pip uninstall python-openstackclient

在执行客户端命令之前,你必须下载并使用source命令执行``openrc``文件来设置环境变量。

获取更多关于OpenStack客户端的信息,包括如何source ``openrc``文件,请看`OpenStack 终端用户手册 <https://docs.openstack.org/user-guide/>`,OpenStack 管理员手册 <https://docs.openstack.org/admin-guide/>`和`OpenStack 命令行接口参考 <https://docs.openstack.org/cli-reference/>

创建云主机

启动虚拟机实例前,需要为其选择名称,镜像和云主机类型。

通过``openstack``客户端调用计算服务API列出可用的镜像:

$ openstack image list
+--------------------------------------+------------------+
| ID                                   | Name             |
+--------------------------------------+------------------+
| a5604931-af06-4512-8046-d43aabf272d3 | fedora-20.x86_64 |
+--------------------------------------+------------------+

运行如下命令以列出云主机类型:

$ openstack flavor list
+----+-----------+-----------+------+-----------+------+-------+-----------+
| ID | Name      | Memory_MB | Disk | Ephemeral | Swap | VCPUs | Is_Public |
+----+-----------+-----------+------+-----------+------+-------+-----------+
| 1  | m1.tiny   | 512       | 0    | 0         |      | 1     | True      |
| 2  | m1.small  | 2048      | 20   | 0         |      | 1     | True      |
| 3  | m1.medium | 4096      | 40   | 0         |      | 2     | True      |
| 4  | m1.large  | 8192      | 80   | 0         |      | 4     | True      |
| 42 | m1.nano   | 64        | 0    | 0         |      | 1     | True      |
| 5  | m1.xlarge | 16384     | 160  | 0         |      | 8     | True      |
| 84 | m1.micro  | 128       | 0    | 0         |      | 1     | True      |
+----+-----------+-----------+------+-----------+------+-------+-----------+

启动虚拟机实例前,记录下您所需的镜像和云主机类型的 ID。

启动 my_instance 云主机,带着镜像、类型ID和服务器名称参数运行 openstack server create 命令:

$ openstack server create --image a5604931-af06-4512-8046-d43aabf272d3 --flavor 1 my_instance
+--------------------------------------+---------------------------------------------------------+
| Field                                | Value                                                   |
+--------------------------------------+---------------------------------------------------------+
| OS-DCF:diskConfig                    | MANUAL                                                  |
| OS-EXT-AZ:availability_zone          | nova                                                    |
| OS-EXT-STS:power_state               | 0                                                       |
| OS-EXT-STS:task_state                | scheduling                                              |
| OS-EXT-STS:vm_state                  | building                                                |
| OS-SRV-USG:launched_at               | None                                                    |
| OS-SRV-USG:terminated_at             | None                                                    |
| accessIPv4                           |                                                         |
| accessIPv6                           |                                                         |
| addresses                            |                                                         |
| adminPass                            | 3vgzpLzChoac                                            |
| config_drive                         |                                                         |
| created                              | 2015-08-27T03:02:27Z                                    |
| flavor                               | m1.tiny (1)                                             |
| hostId                               |                                                         |
| id                                   | 1553694c-d711-4954-9b20-84b8cb4598c6                    |
| image                                | fedora-20.x86_64 (a5604931-af06-4512-8046-d43aabf272d3) |
| key_name                             | None                                                    |
| name                                 | my_instance                                             |
| os-extended-volumes:volumes_attached | []                                                      |
| progress                             | 0                                                       |
| project_id                           | 9f0e4aa4fd3d4b0ea3184c0fe7a32210                        |
| properties                           |                                                         |
| security_groups                      | [{u'name': u'default'}]                                 |
| status                               | BUILD                                                   |
| updated                              | 2015-08-27T03:02:28Z                                    |
| user_id                              | b3ce0cfc170641e98ff5e42b1be9c85a                        |
+--------------------------------------+---------------------------------------------------------+

注解

For information about the default ports that the OpenStack components use, see Firewalls and default ports in the OpenStack Installation Guide.

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.