how to read openstack code: Core plugin and resource extension
本章我们将写一个自己的core plugin 和一个resource extension来加深理解。(阅读本文的前提是你已经理解了restful以及stevedore等内容)
什么是 core plugin
neutron的plugin有core和service两种。core plugin实现core resource的增删改查，service plugin我们在本文暂不讨论。
core resource 有network/subnet/port/subnet-pool。每种资源对应CURD和index5种操作。以network资源为例，相关操作和HTTP请求的对应关系如下
create_network POST networks
delete_network DELETE networks/network_id
update_network PUT networks/network_id
get_network GET networks/network_id
get_networks GET networks
因此，core plugin中对各种核心资源都有如下的函数对应：
create_{resource_name}
update_{resource_name}
delete_{resource_name}
get_{resource_name}
get_{resource_names}
how to write core plugin
既然是plugin，也就是我们前面说过的third-party code，那就应该定义一些接口，好让第三方的组织可以参与开发。
neutron中定义的接口在neutron.neutron_plugin_base_v2.NeutronPluginBaseV2。要实现一个core plugin，你需要实现这个class。
下面是我写的一个core plugin 代码
from neutron import neutron_plugin_base_v2
from oslo_log import log
LOG = log.getLogger(__name__)
class MyNeutronPlugin(neutron_plugin_base_v2.NeutronPluginBaseV2):
supported_extension_aliases = ['gold']
def __init__(self):
super(MyNeutronPlugin,self).__init__()
#### network ####
def create_network(self, context, network):
LOG.info("network is %s" %network)
return network
def update_network(self, context, id, network):
return network
def get_network(self, context, id, fields=None):
network = {}
return network
def get_networks(self, context, filters=None, fields=None):
network = {}
LOG.info("return network %s" %network)
return network
def delete_network(self, context, id):
return id
...
#### gold ####
def create_gold(self, context, gold):
LOG.info("gold is %s" %gold)
return gold
def update_gold(self, context, id, gold):
return gold
def get_gold(self, context, id, fields=None):
gold = {}
return gold
def get_golds(self, context, filters=None, fields=None):
gold = {}
LOG.info("return gold %s" %gold)
return gold
def delete_gold(self, context, id):
return id
请注意，除了network等核心资源，我们还实现了一个gold资源。 上面粘贴的内容省略了subnet/port/subnet-pool的相关代码。 既然是thirty-party code,就应该可以独立安装。所以我们的代码结构如下：
myPlugin/
├── myPluginPKG
│ ├── __init__.py
│ └── myPluginModule.py
└── setup.py
init.py的内容为
import myPluginModule
setup.py内容如下：
from setuptools import setup, find_packages
setup(
name='myPluginPKG',
version='1.0',
packages=find_packages(),
entry_points={
'neutron.core_plugins': [
'myNeutronPlugin = myPluginPKG.myPluginModule:MyNeutronPlugin',
],
},
)
这样在运行python setup.py install 后，我们的plugin就注册到了neutron.core_plugins这个namespace下。这部分内容其实就是前面stevedore中driver开发的内容。neutron通过stevedore在这个namespace下加载core_plugin
OK。在python setup.py install 后，我们的core plugin安装完成了，这时要修改/etc/neutron/neutron.conf，让neutron使用我们的core plugin。
[default]
core_plugin = myNeutronPlugin
然后重启neutron服务
systemctl restart neutron-server
接下来你就可以通过API 尝试了， 我们创建一个network 如下：
curl -g -i -X POST "http://liberty-controller01:9696/v2.0/networks" -H "Content-Type: application/json" -H "Accept: application/json" -H "X-Auth-Token:$token" -d '{"network": {"name": "n2", "admin_state_up": true}}'
HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Content-Length: 15
X-Openstack-Request-Id: req-a8cfde05-6425-42fe-b516-0bb2d264cf61
Date: Tue, 07 Feb 2017 08:01:47 GMT
{"network": {}}
可以看到成功返回，因为我们的plugin中什么也没做，所以返回的其实是一个空的字典。但至少证明该api成功了。
之前我们还在plugin中增加了gold资源对应的函数，我们试试访问gold资源：
curl -g -i "http://liberty-controller01:9696/v2.0/golds" -H "Content-Type: application/json" -H "Accept: application/json" -H "X-Auth-Token:$token"
HTTP/1.1 404 NOT FOUND
为什么gold资源的API不好使呢。这是因为要想在neutron core plugin中定义一个资源，不仅要提供该资源的CURD 函数，还要有对应的RESOURCE_ATTRIBUTE_MAP.
RESOURCE_ATTRIBUTE_MAP
RESOURCE_ATTRIBUTE_MAP是neutron/api/v2/attribute.py中的一个字典，其结构大概如下：
RESOURCE_ATTRIBUTE_MAP = {
NETWORKS: {
'id': {'allow_post': False, 'allow_put': False,
'validate': {'type:uuid': None},
'is_visible': True,
'primary_key': True},
'name': {'allow_post': True, 'allow_put': True,
'validate': {'type:string': NAME_MAX_LEN},
'default': '', 'is_visible': True},
'subnets': {'allow_post': False, 'allow_put': False,
'default': [],
'is_visible': True},
'admin_state_up': {'allow_post': True, 'allow_put': True,
'default': True,
'convert_to': convert_to_boolean,
'is_visible': True},
'status': {'allow_post': False, 'allow_put': False,
'is_visible': True},
'tenant_id': {'allow_post': True, 'allow_put': False,
'validate': {'type:string': TENANT_ID_MAX_LEN},
'required_by_policy': True,
'is_visible': True},
SHARED: {'allow_post': True,
'allow_put': True,
'default': False,
'convert_to': convert_to_boolean,
'is_visible': True,
'required_by_policy': True,
'enforce_policy': True},
},
该字典定义了资源以及资源对应的属性，我们这里只列出了network。所以，要想定义gold资源，除了在core plugin中添加对应的函数，还有在这个attribute map中添加相关的信息。不过，我们不建议直接修改这里的代码，正确的方法是通过resource extension来实现。
how to code an extension (resource extension)
之前提到了extension有3种类型，resource，action，request。我们这里要实现一个新的资源，就是用resource extension。无论是哪种extension 都要遵守一些特定的规则，或者说接口，这些规则如下：
1. extension应该放在neutron/extensions文件夹下，或者在配置文件中设置api_extensions_path
2. extension的class名应该和文件同名，当然首字母应该大写
3. 应该实现neutron.api.extensions.py中ExtensionDescriptor定义的接口
4. 在对应的plugin的supported_extension_aliases 中增加我们extension的别名。前面我们写的core plugin就有这个属性，当时没有做说明，其实是这里应该添加的。所谓别名是该extension要实现的一个接口，后面会看到。
另外很重要的一点是，因为我们要实现的是resource extension，所以还要实现
get_resources
这个接口。
下面我们实现一个自己的resource extension来增加 gold 资源。
from neutron.api import extensions
from neutron import manager
from neutron.api.v2 import base
# You have to specify the attributes neutron-server should expect when
# someone invokes this plugin. Let's say you want
# 'name', 'priority', 'credential' for your extension /golds
# then following dictionary must be declared.
# I am following the naming convention used by other extensions.
RESOURCE_ATTRIBUTE_MAP = {
'golds': {
'name': {'allow_post': True, 'allow_put': True,
'is_visible': True},
'priority': {'allow_post': True, 'allow_put': True,
'is_visible': True},
'credential': {'allow_post': True, 'allow_put': True,
'is_visible': True},
# tenant_id is the user id used by keystone for authorisation
# It's good to use the following as it is and it is necessary
# for every extension
'tenant_id': {'allow_post': True, 'allow_put': False,
'required_by_policy': True,
'validate': {'type:string': None},
'is_visible': True}
}
}
# Great! Now you have the defined the attributes that you need for your
# extensions. You need to store this dictionary in the neutron-server
# by the following class
class Golds(extensions.ExtensionDescriptor):
# The name of this class should be the same as the file name
# There are a couple of methods and their properties defined in the
# parent class of this class, ExtensionDescriptor you can check them
@classmethod
def get_name(cls):
# You can coin a name for this extension
return "Name of golds"
@classmethod
def get_alias(cls):
# This alias will be used by your core_plugin class to load
# the extension
return "gold"
@classmethod
def get_description(cls):
# A small description about this extension
return "A quick brown fox jumped over a lazy dog"
@classmethod
def get_namespace(cls):
# The XML namespace for this extension
# but as we move on to use JSON over XML based request
# this is not that important, correct me if I am wrong.
return "namespace of xml"
@classmethod
def get_updated(cls):
# Specify when was this extension last updated,
# good for management when there are changes in the design
return "2017-02-07T10:00:00-00:00"
@classmethod
def get_resources(cls):
# This method registers the URL and the dictionary of
# attributes on the neutron-server.
exts = list()
plugin = manager.NeutronManager.get_plugin()
resource_name = 'gold'
collection_name = resource_name + 's'
params = RESOURCE_ATTRIBUTE_MAP.get(resource_name + 's', dict())
controller = base.create_resource(collection_name, resource_name,
plugin, params, allow_bulk=False)
ex = extensions.ResourceExtension(collection_name, controller)
exts.append(ex)
return exts
代码的大部分解释都包含在注释里，因此请详细阅读每一行。这里只重点说一下RESOURCE_ATTRIBUTE_MAP 和 get_resources。 我们的extension就是通过这个函数来在resource attribute map中增加了gold资源。
另外要注意的是get_alias，该函数返回extension的别名，plugin的supported_extension_alias中用该别名来找extension。
ok，我们现在尝试一下访问gold 资源
curl -g -i http://liberty-controller01:9696/v2.0/golds.json -H "Content-Type: application/json" -H "Accept: application/json" -H "X-Auth-Token:$token"
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 13
X-Openstack-Request-Id: req-7b925f97-4df0-49ee-bb6a-fd7c86fda9aa
Date: Tue, 07 Feb 2017 08:29:34 GMT
{"golds": []}
这次成功了。 以上就是core plugin和resource extension
