Skip to content

Commit 3dcb404

Browse files
yongli-heyongli-he
committed
Add server sub-resource topology API
Add a new server topology API to show server NUMA information: - GET /servers/{server_id}/topology Add new policy to control the default behavior: - compute:server:topology:index - compute:server:topology:host:index Change-Id: Ie647ef96597195b0ef00f77cece16c2bef8a78d4 Implements: blueprint show-server-numa-topology Signed-off-by: Yongli He <[email protected]>
1 parent eb6fcb2 commit 3dcb404

File tree

19 files changed

+620
-3
lines changed

19 files changed

+620
-3
lines changed

‎api-ref/source/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ the `API guide <https://docs.openstack.org/api-guide/compute/index.html>`_.
5353
.. include:: os-services.inc
5454
.. include:: os-simple-tenant-usage.inc
5555
.. include:: os-server-external-events.inc
56+
.. include:: server-topology.inc
5657

5758
===============
5859
Deprecated APIs

‎api-ref/source/parameters.yaml

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6354,6 +6354,77 @@ server_tags_create:
63546354
required: false
63556355
type: array
63566356
min_version: 2.52
6357+
server_topology_nodes:
6358+
description: |
6359+
NUMA nodes information of a server.
6360+
in: body
6361+
required: true
6362+
type: array
6363+
server_topology_nodes_cpu_pinning:
6364+
description: |
6365+
The mapping of server cores to host physical CPU. for example::
6366+
6367+
cpu_pinning: { 0: 0, 1: 5}
6368+
6369+
This means vcpu 0 is mapped to physical CPU 0, and vcpu 1 is mapped
6370+
physical CPU 5.
6371+
6372+
By default the ``cpu_pinning`` field is only visible to users with the
6373+
administrative role. You can change the default behavior via the policy
6374+
rule::
6375+
6376+
compute:server:topology:host:index
6377+
in: body
6378+
required: false
6379+
type: dict
6380+
server_topology_nodes_cpu_siblings:
6381+
description: |
6382+
A mapping of host cpus thread sibling. For example::
6383+
6384+
siblings: [[0,1],[2,3]]
6385+
6386+
This means vcpu 0 and vcpu 1 belong to same CPU core, vcpu 2, vcpu 3
6387+
belong to another CPU core.
6388+
6389+
By default the ``siblings`` field is only visible to users with the
6390+
administrative role. You can change the default behavior via the policy
6391+
rule::
6392+
6393+
compute:server:topology:host:index
6394+
in: body
6395+
required: false
6396+
type: list
6397+
server_topology_nodes_host_numa_node:
6398+
description: |
6399+
The host NUMA node the virtual NUMA node is map to.
6400+
6401+
By default the ``host_numa_node`` field is only visible to users with the
6402+
administrator role. You can change the default behavior via the policy
6403+
rule::
6404+
6405+
compute:server:topology:host:index
6406+
in: body
6407+
required: false
6408+
type: integer
6409+
server_topology_nodes_memory_mb:
6410+
description: |
6411+
The amount of memory assigned to this NUMA node in MB.
6412+
in: body
6413+
required: false
6414+
type: integer
6415+
server_topology_nodes_vcpu_set:
6416+
description: |
6417+
A list of IDs of the virtual CPU assigned to this NUMA node.
6418+
in: body
6419+
required: false
6420+
type: list
6421+
server_topology_pagesize_kb:
6422+
description: |
6423+
The page size in KB of a server. This field is ``null`` if the
6424+
page size information is not available.
6425+
in: body
6426+
required: true
6427+
type: integer
63576428
server_trusted_image_certificates_create_req:
63586429
description: |
63596430
A list of trusted certificate IDs, which are used during image

‎api-ref/source/server-topology.inc

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
.. -*- rst -*-
2+
3+
=====================================
4+
Servers Topology (servers, topology)
5+
=====================================
6+
7+
Shows the NUMA topology information for a server.
8+
9+
Show Server Topology
10+
====================
11+
12+
.. rest_method:: GET /servers/{server_id}/topology
13+
.. versionadded:: 2.78
14+
15+
Shows NUMA topology information for a server.
16+
17+
Policy defaults enable only users with the administrative role or the owners
18+
of the server to perform this operation. Cloud providers can change these
19+
permissions through the ``policy.json`` file.
20+
21+
Normal response codes: 200
22+
23+
Error response codes: unauthorized(401), notfound(404), forbidden(403)
24+
25+
Request
26+
-------
27+
28+
.. rest_parameters:: parameters.yaml
29+
30+
- server_id: server_id_path
31+
32+
Response
33+
--------
34+
35+
All response fields are listed below. If some information is not available or
36+
not allow by policy, the corresponding key value will not exist in response.
37+
38+
.. rest_parameters:: parameters.yaml
39+
40+
- nodes: server_topology_nodes
41+
- nodes.cpu_pinning: server_topology_nodes_cpu_pinning
42+
- nodes.vcpu_set: server_topology_nodes_vcpu_set
43+
- nodes.siblings: server_topology_nodes_cpu_siblings
44+
- nodes.memory_mb: server_topology_nodes_memory_mb
45+
- nodes.host_numa_node: server_topology_nodes_host_numa_node
46+
- pagesize_kb: server_topology_pagesize_kb
47+
48+
**Example Server topology (2.xx)**
49+
50+
.. literalinclude:: ../../doc/api_samples/os-server-topology/v2.78/servers-topology-resp.json
51+
:language: javascript
52+

‎doc/api_samples/os-server-topology/v2.78/servers-topology-resp-user.json

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"nodes": [
3+
{
4+
"memory_mb": 1024,
5+
"siblings": [
6+
[
7+
0,
8+
1
9+
]
10+
],
11+
"vcpu_set": [
12+
0,
13+
1
14+
]
15+
},
16+
{
17+
"memory_mb": 2048,
18+
"siblings": [
19+
[
20+
2,
21+
3
22+
]
23+
],
24+
"vcpu_set": [
25+
2,
26+
3
27+
]
28+
}
29+
],
30+
"pagesize_kb": 4
31+
}

‎doc/api_samples/os-server-topology/v2.78/servers-topology-resp.json

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"nodes": [
3+
{
4+
"cpu_pinning": {
5+
"0": 0,
6+
"1": 5
7+
},
8+
"host_node": 0,
9+
"memory_mb": 1024,
10+
"siblings": [
11+
[
12+
0,
13+
1
14+
]
15+
],
16+
"vcpu_set": [
17+
0,
18+
1
19+
]
20+
},
21+
{
22+
"cpu_pinning": {
23+
"2": 1,
24+
"3": 8
25+
},
26+
"host_node": 1,
27+
"memory_mb": 2048,
28+
"siblings": [
29+
[
30+
2,
31+
3
32+
]
33+
],
34+
"vcpu_set": [
35+
2,
36+
3
37+
]
38+
}
39+
],
40+
"pagesize_kb": 4
41+
}

‎doc/api_samples/versions/v21-version-get-resp.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
}
2020
],
2121
"status": "CURRENT",
22-
"version": "2.77",
22+
"version": "2.78",
2323
"min_version": "2.1",
2424
"updated": "2013-07-23T11:33:21Z"
2525
}

‎doc/api_samples/versions/versions-get-resp.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
}
2323
],
2424
"status": "CURRENT",
25-
"version": "2.77",
25+
"version": "2.78",
2626
"min_version": "2.1",
2727
"updated": "2013-07-23T11:33:21Z"
2828
}

‎nova/api/openstack/api_version_request.py

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,8 @@
203203
``GET /servers/{server_id}/os-instance-actions/{request_id}``.
204204
* 2.77 - Add support for specifying ``availability_zone`` to unshelve of a
205205
shelved offload server.
206+
* 2.78 - Adds new API ``GET /servers/{server_id}/topology`` which shows
207+
NUMA topology of a given server.
206208
"""
207209

208210
# The minimum and maximum versions of the API supported
@@ -211,7 +213,7 @@
211213
# Note(cyeoh): This only applies for the v2.1 API once microversions
212214
# support is fully merged. It does not affect the V2 API.
213215
_MIN_API_VERSION = "2.1"
214-
_MAX_API_VERSION = "2.77"
216+
_MAX_API_VERSION = "2.78"
215217
DEFAULT_API_VERSION = _MIN_API_VERSION
216218

217219
# Almost all proxy APIs which are related to network, images and baremetal

‎nova/api/openstack/compute/rest_api_version_history.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -998,3 +998,15 @@ through ``GET /servers/{server_id}/os-instance-actions`` and
998998
----
999999
API microversion 2.77 adds support for specifying availability zone when
10001000
unshelving a shelved offloaded server.
1001+
1002+
2.78
1003+
----
1004+
1005+
Add server sub-resource ``topology`` to show server NUMA information.
1006+
1007+
* ``GET /servers/{server_id}/topology``
1008+
1009+
The default behavior is configurable using two new policies:
1010+
1011+
* ``compute:server:topology:index``
1012+
* ``compute:server:topology:host:index``

‎nova/api/openstack/compute/routes.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@
7575
from nova.api.openstack.compute import server_migrations
7676
from nova.api.openstack.compute import server_password
7777
from nova.api.openstack.compute import server_tags
78+
from nova.api.openstack.compute import server_topology
7879
from nova.api.openstack.compute import servers
7980
from nova.api.openstack.compute import services
8081
from nova.api.openstack.compute import shelve
@@ -316,6 +317,8 @@ def _create_controller(main_controller, action_controller_list):
316317
server_tags_controller = functools.partial(_create_controller,
317318
server_tags.ServerTagsController, [])
318319

320+
server_topology_controller = functools.partial(_create_controller,
321+
server_topology.ServerTopologyController, [])
319322

320323
server_volume_attachments_controller = functools.partial(_create_controller,
321324
volumes.VolumeAttachmentController, [])
@@ -832,6 +835,9 @@ def _create_controller(main_controller, action_controller_list):
832835
'PUT': [server_tags_controller, 'update'],
833836
'DELETE': [server_tags_controller, 'delete']
834837
}),
838+
('/servers/{server_id}/topology', {
839+
'GET': [server_topology_controller, 'index']
840+
}),
835841
)
836842

837843

‎nova/api/openstack/compute/server_topology.py

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
#
2+
# Licensed under the Apache License, Version 2.0 (the "License"); you may
3+
# not use this file except in compliance with the License. You may obtain
4+
# a copy of the License at
5+
#
6+
# http://www.apache.org/licenses/LICENSE-2.0
7+
#
8+
# Unless required by applicable law or agreed to in writing, software
9+
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
10+
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
11+
# License for the specific language governing permissions and limitations
12+
# under the License.
13+
14+
from nova.api.openstack import common
15+
from nova.api.openstack import wsgi
16+
from nova.compute import api as compute
17+
from nova.policies import server_topology as st_policies
18+
19+
20+
class ServerTopologyController(wsgi.Controller):
21+
22+
def __init__(self, *args, **kwargs):
23+
super(ServerTopologyController, self).__init__(*args, **kwargs)
24+
self.compute_api = compute.API()
25+
26+
@wsgi.Controller.api_version("2.78")
27+
@wsgi.expected_errors((404))
28+
def index(self, req, server_id):
29+
context = req.environ["nova.context"]
30+
context.can(st_policies.BASE_POLICY_NAME % 'index')
31+
host_policy = (st_policies.BASE_POLICY_NAME % 'host:index')
32+
show_host_info = context.can(host_policy, fatal=False)
33+
34+
instance = common.get_instance(self.compute_api, context, server_id,
35+
expected_attrs=['numa_topology',
36+
'vcpu_model'])
37+
38+
return self._get_numa_topology(context, instance, show_host_info)
39+
40+
def _get_numa_topology(self, context, instance, show_host_info):
41+
42+
if instance.numa_topology is None:
43+
return {
44+
'nodes': [],
45+
'pagesize_kb': None
46+
}
47+
48+
topo = {}
49+
cells = []
50+
pagesize_kb = None
51+
52+
for cell_ in instance.numa_topology.cells:
53+
cell = {}
54+
cell['vcpu_set'] = cell_.cpuset
55+
cell['siblings'] = cell_.siblings
56+
cell['memory_mb'] = cell_.memory
57+
58+
if show_host_info:
59+
cell['host_node'] = cell_.id
60+
if cell_.cpu_pinning is None:
61+
cell['cpu_pinning'] = {}
62+
else:
63+
cell['cpu_pinning'] = cell_.cpu_pinning
64+
65+
if cell_.pagesize:
66+
pagesize_kb = cell_.pagesize
67+
68+
cells.append(cell)
69+
70+
topo['nodes'] = cells
71+
topo['pagesize_kb'] = pagesize_kb
72+
73+
return topo

‎nova/policies/__init__.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@
6161
from nova.policies import server_metadata
6262
from nova.policies import server_password
6363
from nova.policies import server_tags
64+
from nova.policies import server_topology
6465
from nova.policies import servers
6566
from nova.policies import servers_migrations
6667
from nova.policies import services
@@ -123,6 +124,7 @@ def list_rules():
123124
server_metadata.list_rules(),
124125
server_password.list_rules(),
125126
server_tags.list_rules(),
127+
server_topology.list_rules(),
126128
servers.list_rules(),
127129
servers_migrations.list_rules(),
128130
services.list_rules(),

0 commit comments

Comments
 (0)