OpenStack API Documentation

OpenStack API

OpenStack サービスへのアクセスの認証を行うには、まず最初に、ペイロードにクレデンシャルを指定して OpenStack Identity に認証リクエストを行って、認証トークンを取得する必要があります。

Credentials are usually a combination of your user name and password, and optionally, the name or ID of the project of your cloud. Ask your cloud administrator for your user name, password, and project so that you can generate authentication tokens. Alternatively, you can supply a token rather than a user name and password.

API リクエストの送信時、X-Auth-Token ヘッダーにトークンを指定します。複数の OpenStack サービスにアクセスする場合、サービス毎にトークンを取得する必要があります。トークンは一定時間有効で、その後期限切れとなります。トークンは他の理由で失効することもあります。例えば、ユーザーのロールが変更された場合、そのユーザーの既存のトークンは無効になります。

認証と API リクエストのワークフロー

  1. クラウド管理者が指定した Identity エンドポイントに対して認証トークンを要求します。リクエストでクレデンシャルのペイロードを送信します。詳細は 認証 に書かれているとおりです。リクエストに成功すると、サーバーから認証トークンが返されます。
  2. API リクエストを送信する際には X-Auth-Token ヘッダーにトークンを指定します。サービスに対するリクエストが全部完了するか、 Unauthorized (401) エラーが発生するまで、API リクエストの送信ではそのトークンを使い続けます。
  3. Unauthorized (401) エラーが発生した場合、別のトークンをリクエストします。

このセクションにある例では、cURL コマンドを使用します。cURL に関する情報は http://curl.haxx.se/ を参照してください。OpenStack API に関する情報は カレント API バージョン を参照してください。

認証

認証のためのクレデンシャルのペイロードには、以下のパラメーターを指定します。

パラメーター 説明
User Domain (required) 文字列 The Domain of the user.
ユーザー名 (必須) 文字列 ユーザー名。ユーザー名とパスワードを指定しない場合は、トークンを指定する必要があります。
パスワード (必須) 文字列 ユーザーのパスワード。
Project Domain (optional) 文字列 The Domain of the project. This is a required part of the scope object.
Project Name (optional) 文字列 The project name. Both the Project ID and Project Name are optional.
Project ID (optional) 文字列 The project ID. Both the project ID and Project Name are optional. But one of them is required along with the Project Domain. They are wrapped under a scope object. If you do not know the project name or ID, send a request without any scope object.

In a typical OpenStack deployment that runs Identity, you can specify your project name, and user name and password credentials to authenticate.

First, export your project name to the OS_PROJECT_NAME environment variable, your project domain name to the OS_PROJECT_DOMAIN_NAME environment variable, your user name to the OS_USERNAME environment variable, your password to the OS_PASSWORD environment variable and your user domain name to the OS_USER_DOMAIN_NAME environment variable.

The example below uses an endpoint from an installation of Ocata by following the installation guide. However, you can also use $OS_AUTH_URL as an environment variable as needed to change the URL.

次に、この cURL コマンドを実行して、トークンをリクエストします。

$ 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

If the request succeeds, it returns the Created (201) response code along with the token as a value in the X-Subject-Token response header. The header is followed by a response body that has an object of type token which has the token expiration date and time in the form "expires_at":"datetime" along with other attributes.

以下は、成功した場合の応答例です。

*   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
        }
    }
}

注釈

In the above request, the query string nocatalog is used as you just want to get a token and do not want the service catalog (if it is available for the user) cluttering the output. If a user wants to get the service catalog, this query string need not be appended to the URL.

API リクエストの送信

このセクションでは、基本的な Compute API コールの実行方法を示します。 Compute API コールの一覧は Compute API を参照してください。

トークン ID を環境変数 OS_TOKEN として export します。例:

export OS_TOKEN=gAAAAABZJ8_a7aiq1SnOhbNw8vFb5WZChcvWdzzUAFzhiB99BHrjdSGai--_-JstU3WazsFXmRHNbD07qOQKTp5Sen2R_b9csaDkU49VXqSaJ0jh2nAlwJkys8aazz2oa3xSeUVe3Ndv_HRiW23-iWTr6jquK_AXdhRX7nvM4lmVTrxXFpelnJQ

トークンはデフォルトでは 毎時間ごとに期限切れとなりますが、設定で変更が可能です - Identity Service ConfigurationDescription of token configuration options セクション中の expiration オプションを参照してください。

Export the project name to the OS_PROJECT_NAME environment variable. For example:

export OS_PROJECT_NAME=demo

次に、Compute API を使用してフレーバーを一覧表示します。Compute API のエンドポイントをお使いのプロジェクト ID に置き換えてください。

$ 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 を設定してから、Compute 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 を設定してから、Compute 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 クライアントなどのコマンドラインクライアントが利用できます。このクライアントを使って、コマンドラインインターフェースから Identity API、 Compute API、Block Storage API、Object Storage API を使用できます。また、各 OpenStack プロジェクトには対応するクライアントプロジェクトがあり、 Python API バインディングとコマンドラインインターフェース (CLI) が提供されています。

コマンドラインクライアントに関する情報は OpenStack Command-Line Interface Reference を参照してください。

クライアントのインストール

Mac OS X や Linux のシステムに OpenStack クライアントをインストールするには pip を使用します。Python Package Index からクライアントの最新バージョンを簡単かつ確実に入手できます。また、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

クライアントコマンドを発行する前に、openrc ファイルをダウンロードし、これを読み込んで、環境変数を設定する必要があります。

openrc ファイルの読み込み方法など、OpenStack クライアントの詳細は、OpenStack エンドユーザーガイドOpenStack 管理者ガイドOpenStack Command-Line Interface Reference を参照してください。

インスタンスの起動

インスタンスを起動する場合、インスタンスの名前、イメージ、フレーバーを選択する必要があります。

利用可能なイメージの一覧を表示するには、 openstack クライアント経由で Compute 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、フレーバー 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                        |
+--------------------------------------+---------------------------------------------------------+

注釈

OpenStack のコンポーネントが使用するデフォルトのポート番号については、OpenStack Configuration Referenceファイアウォールとデフォルトのポート を参照してください。

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.