Dragonflow API requirements and specification

Dragonflow API requirements and specification

The URL of your launchpad Blueprint:

https://blueprints.launchpad.net/dragonflow/+spec/add-dragonflow-api

This blueprint states the requirements and proposes the way to provide Dragonflow configuration management API. Currently, Neutron API is the only way to manage Dragonflow configuration. While this is good enough for the OpenStack environments, it limits number of use cases where Dragonflow can be used or adds Neutron API server as a mandatory required service. Native Dragonflow API support unlocks integrations with different container Orchestration Engines, i.e. Kubernetes, Mesos. It enables users to manipulate configuration elements exposed by the Dragonflow SDN Controller and makes the application more robust. Since the implementation is hidden and exposed only via the API, enhancements can be added without causing the disruption to the application consuming the API. Native Dragonflow API will enable new network-aware applications to provide control over networks.

Problem Description

Currently the only way to manage Dragonflow configuration elements is by using Neutron API. As stated above, this is not enough to cover all the potential Dragonflow usage scenarios. Dragonflow is an open, standards-based SDN controller that virtualises the network and should enable automation and orchestration of the various cloud environments and networking services. Without Dragonflow API, while the only way is to access the North Bound DB API, the existing applications may be impacted upon implementation changes or enhancement additions. This will not be the case once applications will use API.

Proposed Change

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.

Deployment Impact

API server will be part of the Dragonflow deployment and should be deployed as part of the Dragonflow. The authentication (keystone) service endpoint and the admin user details should be provided via API server configuration file.

Work Items

  1. Define Dragonflow programming model.
  2. Add support for auto-generation of the OpenAPI spec from the model.
  3. Add RESTful API (preferably auto-generated) from the model’s spec.
  4. Add Authorization service.
  5. Add Python library (binding)
  6. Add Command Line Tool (CLI) which interact with the API server.
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.