Dragonflow API requirements and specification¶

Dragonflow API requirements¶

In order to satisfy different usage scenarios, the Dragonflow API support should fulfil the following requirements.

• Support REST design idiom by exposing Dragonflow managed resources.
• RESTful API should be auto-generated from the model’s specification.
• Follow OpenAPI Spec (OAS) [1] for API definition.
• Provide support for multi-tenancy via Authorization component.
• Authentication should be optional and it should be possible to disable it for example during development phase.
• Provide API for configuration and operational data models.
• Provide support for bulk operations.
• Ensure model consistency to support multiple API workers case.
• Provide API (data model) backward compatibility. This requires that only changes to the data model may only extend existing objects and any changes to the model must be incremental.
• It should be possible to discover all API resources by querying the root.
• Provide Python library (subproject under Dragonflow) on top of the REST API to boost applications development.
• Provide command line tool which interact with the Dragonflow API server.

Along with stated above requirements, API performance should be reliable.

Data Model Object Hierarchy¶

Data Model contains different types of the objects. Objects created outside of the Dragonflow are Configuration state. Objects generated by the Dragonflow applications are Operational state. Some objects maybe either configured or generated. In addition, some physical entities are represented in the data model (i.e chassis). Dragonflow System Data Model should be well defined and keep backward compatibility in order to be consistent with applications consuming the API.

Current Dragonflow model is basic, assuming there is Neutron model on top of it. The local controller uses the model to program the dataplane. Model objects are: Chassis, LogicalSwitch, LogicalPort, LogicalRouter, SecurityGroup, FloatingIP and QoSPolicy.

In order to provide user facing management API, Dragonflow will need to add higher level models, such as Tenant. Higher Level model will allow decoupling of the management and data planes.

In the future, more high level models and APIs will be added to Dragonflow to allow native management of the services that currently managed via external APIs such as neutron, neutron-fwaas and other.

API Authentication¶

DF will provide authentication and authorization services by integrating with external identity services. Dragonflow will be responsible to enforce the authorization by querying the identity service. Keystone can be used for the API server authentication, as it is part of the OpenStack deployment anyway. Other authentication service alternatives can be considered later, therefore implementation should not make an assumption about authentication service. It should be possible to disable authentication and as result to return fake tokens to authenticating clients, and ignore sent tokens during the authorization. Authentication will be required for the operations on the higher level models as well as on the basic models.

Multi Tenancy and Role Based Access Control support¶

In order to provide proper support for multi tenancy and role based access control (RBAC) Dragonflow API should reject the requesting user attempts to perform operations or access resources that it does not have permission to. Dragonflow API can start by servicing 3 types of users:

• Admin - super user, has access to everything. In OpenStack environment, this user is usually the OpenStack cloud admin.
• Tenant Admin - admin of a tenant that has access to all resources that belongs to the tenant.
• Tenant User - user of a tenant that has read-only access to resources that belongs to the tenant.

In the future version, deployer should be able to define roles and access policies.

API definition¶

The proposal is to use OpenAPI specification [1] to describe Dragonflow API to allow both humans and computers to discover and understand the capabilities of the Dragonflow provided services without going to the source code or additional documentation. There are existing tools that can be used to generate documentation and client code.