introduction of a new nova rest api · if not specifying microversion, nova takes v2 compatible...

Introduction of a new Nova REST API Why we need to use Nova V2.1 API

Ken’ichi Ohmichi

NEC

© NEC Corporation 2015

Agenda

▌Who am I ?

▌REST API & OpenStack

▌Nova V2.1 API

V2 Compatibility

Validation

Microversions

▌Usage of V2.1

▌Latest development status for Liberty

▌Summary


Who am I ?

▌Ken’ichi Ohmichi

Software developer from NEC

OpenStack community member since 2012

Core developer of Nova and Tempest

REST API & OPENSTACK


REST API

▌Software architecture style for creating scalable web services

▌CRUD operation with Method and URI

GET /v1/resources

Method Base Resource

URI

Operation Method Resource URI

Create a new resource POST /resources

(Read) List resources GET /resources

(Read) Show a resource GET /resources/<id>

Update a resource PUT /resources/<id>

Delete a resource DELETE /resources/<id>


OpenStack services through REST APIs

▌OpenStack components provide many functions through REST APIs

Component Operation Method Resource URI

Nova Create a new server POST /servers

List servers GET /servers

Keystone Add an endpoint POST /endpoints

List endpoints GET /endpoints

Glance Create a new image POST /images

List images GET /images

Cinder Create a new volume POST /volumes

List volumes GET /volumes

A part of OpenStack APIs


Users use REST APIs

▌Dashboard and commands request operations through REST APIs

OpenStack Cloud

Nova Glance

REST API REST API

Keystone

REST API

Commands

Horizon

$ nova list $ glance image-list

REST API is important for OpenStack

APPs

NOVA V2.1 API


Nova V2.1 API is released in Kilo

▌Nova provides V2 and V2.1 as REST APIs

▌Both APIs are available on different endpoints

V2: GET /v2/{project-id}/servers

V2.1: GET /v2.1/{project-id}/servers

▌Both implementation codes are

different

▌V2.1 is newer and the status

is CURRENT

▌New features have been added

to V2.1 only since Kilo.

V2 is frozen now

Nova

OpenStack Cloud

/v2 V2 API

(SUPPORTED)

/v2.1 V2.1 API

(CURRENT)

Ｅｎｄｐｏｉｎｔ

New feature New feature New feature New feature

New feature New feature New feature New feature

Code


What is Nova V2.1 API?

Nova V2.1 API

= V2 compatibility

+ Validation

+ Microversions

V2 COMPATIBILITY

Features of Nova V2.1 API


V2 compatibility is super important

▌V2 has been used since Nov. 2011

▌There are 30+ SDKs using OpenStack REST APIs

▌There is a lot of APPs using Nova V2 API in the world

Incompatible changes would break a lot of APPs

Nova

V2 API

OpenStack Cloud SDKs

jcloud (Java)

fog (Ruby)

Goose (Go)

…

APPs

APP

APP

APP

APP Incompatible change

break break


The default endpoint is still V2 in Kilo

▌V2 still works on the default endpoint (/v2)

▌Incompatible changes never happen on the default

We can continue using the existing APPs

without any changes on Kilo

Nova

V2.1 API


jcloud (Java)

fog (Ruby)

Goose (Go)

…

APPs

APP

APP

APP

APP

V2 API /v2

/v2.1



The default behavior of V2.1 is V2 compatible

▌V2.1 works like V2 as default behavior

▌Incompatible changes never happen on the default behavior

On V2.1, we can continue using

the existing APPs without any changes

Nova

V2.1 API


jcloud (Java)

fog (Ruby)

Goose (Go)

…

APPs

APP

APP

APP

APP

Switch from V2

to V2.1

V2 API /v2

/v2.1


VALIDATION



V2 had validation problems

▌Easy to cause internal errors due to lacks of input validation

▌Operation cost was high

Cloud operators need to investigate and fix the errors

Users cannot know what they should do

Nova

OpenStack Cloud

V2 API APP

{“server”: {

“name”: “VM01”,

[..]

“metadata”: “non-obj”

}} Internal

Error

POST

HTTP500

Error response doesn’t

contain the reason

User Operator

Hmm Hmm


V2.1 implements input validation framework

▌All API parameters need to be defined with types and formats

Types: string, boolean, integer, etc.

Format: UUID, hostname, ipv4, etc.

▌V2.1 denies a malformed request based on these definitions

Possible to avoid internal errors

Error message contains the reason with consistent format

Users can know the reason and fix their own problems easily

V2.1 validation can reduce operation cost

MICROVERSIONS



Microversions is API versioning mechanism

▌New versions for each small API change

All API changes will appear as new microversions

▌APPs can specify a microversion for their operations

The microversion is specified with a request header, not endpoint

Nova

V2.1 API

V2 API

APP

V2.1

/v2

/v2.1

Ｅｎｄｐｏｉｎｔ Code

V2.2 V2.3 V2.x Microversions

The microversion V2.1 is

the default microversion

and V2 compatible

V2.1 + new change

V2.2 + new change

V2.(x-1) + new change

header

Specifying V2.2

The endpoint is the same

between microversions


With microversions, V2 interfaces bugs will be fixed

▌V2 contains interfaces bugs

Wrong http status codes, inconsistent URIs, etc

But it was difficult to fix them because of backwards incompatibility

▌Microversions allows us to fix them

The default microversion(V2.1) is V2 compatible for the existing APPs

We will fix them with small changes to avoid a big impact to users

Microversions will make Nova API

more consistent and beautiful


Actual Microversions in Kilo

▌V2.1 The default and V2 compatible API

Validation

▌V2.2 Add new parameter “type” to keypair API response

Fix inaccurate status codes of keypair API

• “create keypair” API: Change from 200(OK) to 201(Created)

• “delete keypair” API: Change from 202(Accepted) to 204(No Content)

▌V2.3 Add new parameters to “show server” API for standalone EC2 service

You can find microversions history on

https://github.com/openstack/nova/blob/master/

nova/api/openstack/rest_api_version_history.rst

Backwards incompatible changes The keypair operation is synchronous,

so 201(Created) and 204(No Content) are

more appropriate. This change is based on

the API guideline of API-WG

USAGE OF V2.1


V2.1 and Microversion

▌To use V2.1

Switch an endpoint from /v2 to /v2.1

▌To use Microversion

Switch an endpoint from /v2 to /v2.1

Specify a microversion in a request header

APP Switch to /v2.1

V2.1 API

V2 API

V2.1

/v2

/v2.1


V2.2 V2.3 V2.x Microversions

Nova

Specify the microversion V2.2


How to know the supported V2.1 and microversions?

▌Try “nova version-list”

Check “v2.1” and its status is CURRENT

Check “Min Version” and “Version”

$ nova version-list +------+-----------+----------------------+-------------+---------+ | Id | Status | Updated | Min Version | Version | +------+-----------+----------------------+-------------+---------+ | v2.0 | SUPPORTED | 2011-01-21T11:33:21Z | | | | v2.1 | CURRENT | 2013-07-23T11:33:21Z | 2.1 | 2.3 | +------+-----------+----------------------+-------------+---------+

Check here

version-list was broken, use the latest

python-novaclient (v2.25.0, 13th/May)

Check here

“Version” means a maximum microversion.


How to switch V2.1 ?

▌Try adding --service-type computev21 to nova command

--debug option is useful for confirming V2.1 works

$ nova --debug --service-type computev21 list [..] DEBUG (connectionpool:383) "GET /v2.1/…/servers/detail HTTP/1.1" 200 15 DEBUG (session:224) RESP: [200] content-length: 15 [..] vary: X-OpenStack-Nova-API-Version x-openstack-nova-api-version: 2.1 [..] RESP BODY: {"servers": []} +----+------+--------+------------+-------------+----------+ | ID | Name | Status | Task State | Power State | Networks | +----+------+--------+------------+-------------+----------+ +----+------+--------+------------+-------------+----------+

The response includes which

microversion works on Nova side

The base URI is switched with

--service-type option


How to specify Microversion ?

▌With nova command

Specify a microversion with --os-compute-api-version

▌For APPs/SDKs

Specify a microversion in a request header

If not specifying microversion, Nova takes V2 compatible action (V2.1)

If passing a special keyword “latest”, Nova takes maximum

microversion action. This is useful for development in most cases

X-OpenStack-Nova-API-Version: 2.3

X-OpenStack-Nova-API-Version: latest

LATEST DEVELOPMENT STATUS

FOR LIBERTY


Switch default endpoint to /v2.1

▌The default endpoint will been switched to /v2.1

APPs can still work without any changes because of V2 compatibility

V2.1 validation works as the default

APPs can use microversions as the default

$ openstack catalog list +-------------+----------------+---------------------------------------------------+ | Name | Type | Endpoints | +-------------+----------------+---------------------------------------------------+ | nova | compute | RegionOne | | | | publicURL: http://192.168.11.65:8774/v2.1/[..] | | nova_legacy | compute_legacy | RegionOne | | | | publicURL: http://192.168.11.65:8774/v2/[..] |

The default endpoint shows /v2.1

The endpoint /v2 is marked as legacy


Switch code of legacy endpoint to V2.1

▌The legacy endpoint(/v2) will be implemented with V2.1 API code

Need to keep legacy endpoint for the existing users

Difficult to del legacy endpoint, but hard burden to maintain both API code

By reusing V2.1 API code for legacy endpoint, possible to del V2 API code

Nova

V2.1 API (13KL)

V2 API (13KL) /v2


/v2.1

Since Liberty,

this will be unused.

In long-term,

this will be removed. legacy

default


Simulate V2 behavior for legacy endpoint

▌Relax V2.1 API validation

V2.1 API validation breaks APPs which use API wrongly

Tempest (Integration tests) and Heat (Orchestration) also used Nova API wrongly

▌Disable Microversions

Legacy endpoint is for the existing users who don’t use microversions

Community dev team recommends using V2.1 API directly

Nova

V2.1 API (13KL)

V2 API (13KL) /v2


/v2.1

legacy

default

Relaxed validation Disabled microversions

SUMMARY


Summary

▌V2.1 =

V2 compatibility

• We can still use the existing APPs without any changes

Validation

• We can avoid internal errors and reduce operation cost

Microversions

• New features have been implemented on V2.1 only

▌A new OpenStack Liberty will be released 15th, Oct

We can use V2.1 API as the default

introduction of a new nova rest api · if not specifying microversion, nova takes v2 compatible...

Documents