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:

Credential 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 请求

This section shows how to make some basic Compute API calls. For a complete list of Compute API calls, see Compute API.

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

export OS_TOKEN=gAAAAABZJ8_a7aiq1SnOhbNw8vFb5WZChcvWdzzUAFzhiB99BHrjdSGai--_-JstU3WazsFXmRHNbD07qOQKTp5Sen2R_b9csaDkU49VXqSaJ0jh2nAlwJkys8aazz2oa3xSeUVe3Ndv_HRiW23-iWTr6jquK_AXdhRX7nvM4lmVTrxXFpelnJQ

默认情况下token的有效时间为1小时,也可以通过配置设置为其他值。可参考`<https://docs.openstack.org/keystone/latest/configuration/config-options.html#token.expiration>`__ *身份识别服务配置指南*中过期这一章节中相关的配置选项

将项目名传递给环境变量``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/>`__。

安装客户端

Use pip to install the OpenStack clients on a Mac OS X or Linux system. It is easy and ensures that you get the latest version of the client from the Python Package Index. Also, pip lets you update or remove a package.

你必须为每个工程单独安装客户端,但是``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.