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 <yongli.he@intel.com>

3 files changed, 124 insertions, 0 deletions

diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index f3597cb46a..b83346f4a7 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -53,6 +53,7 @@ the `API guide <https://docs.openstack.org/api-guide/compute/index.html>`_.
 .. include:: os-services.inc
 .. include:: os-simple-tenant-usage.inc
 .. include:: os-server-external-events.inc
+.. include:: server-topology.inc
 
 ===============
 Deprecated APIs
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 82f9ef8801..150691f890 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -6354,6 +6354,77 @@ server_tags_create:
   required: false
   type: array
   min_version: 2.52
+server_topology_nodes:
+  description: |
+    NUMA nodes information of a server.
+  in: body
+  required: true
+  type: array
+server_topology_nodes_cpu_pinning:
+  description: |
+    The mapping of server cores to host physical CPU. for example::
+
+     cpu_pinning: { 0: 0, 1: 5}
+
+    This means vcpu 0 is mapped to physical CPU 0, and vcpu 1 is mapped
+    physical CPU 5.
+
+    By default the ``cpu_pinning`` field is only visible to users with the
+    administrative role. You can change the default behavior via the policy
+    rule::
+
+     compute:server:topology:host:index
+  in: body
+  required: false
+  type: dict
+server_topology_nodes_cpu_siblings:
+  description: |
+    A mapping of host cpus thread sibling. For example::
+
+      siblings: [[0,1],[2,3]]
+
+    This means vcpu 0 and vcpu 1 belong to same CPU core, vcpu 2, vcpu 3
+    belong to another CPU core.
+
+    By default the ``siblings`` field is only visible to users with the
+    administrative role. You can change the default behavior via the policy
+    rule::
+
+      compute:server:topology:host:index
+  in: body
+  required: false
+  type: list
+server_topology_nodes_host_numa_node:
+  description: |
+    The host NUMA node the virtual NUMA node is map to.
+
+    By default the ``host_numa_node`` field is only visible to users with the
+    administrator role. You can change the default behavior via the policy
+    rule::
+
+     compute:server:topology:host:index
+  in: body
+  required: false
+  type: integer
+server_topology_nodes_memory_mb:
+  description: |
+    The amount of memory assigned to this NUMA node in MB.
+  in: body
+  required: false
+  type: integer
+server_topology_nodes_vcpu_set:
+  description: |
+    A list of IDs of the virtual CPU assigned to this NUMA node.
+  in: body
+  required: false
+  type: list
+server_topology_pagesize_kb:
+  description: |
+    The page size in KB of a server. This field is ``null`` if the
+    page size information is not available.
+  in: body
+  required: true
+  type: integer
 server_trusted_image_certificates_create_req:
   description: |
     A list of trusted certificate IDs, which are used during image
diff --git a/api-ref/source/server-topology.inc b/api-ref/source/server-topology.inc
new file mode 100644
index 0000000000..1f2da300d1
--- /dev/null
+++ b/api-ref/source/server-topology.inc
@@ -0,0 +1,52 @@
+.. -*- rst -*-
+
+=====================================
+Servers Topology (servers, topology)
+=====================================
+
+Shows the NUMA topology information for a server.
+
+Show Server Topology
+====================
+
+.. rest_method:: GET /servers/{server_id}/topology
+.. versionadded:: 2.78
+
+Shows NUMA topology information for a server.
+
+Policy defaults enable only users with the administrative role or the owners
+of the server to perform this operation. Cloud providers can change these
+permissions through the ``policy.json`` file.
+
+Normal response codes: 200
+
+Error response codes: unauthorized(401), notfound(404), forbidden(403)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - server_id: server_id_path
+
+Response
+--------
+
+All response fields are listed below. If some information is not available or
+not allow by policy, the corresponding key value will not exist in response.
+
+.. rest_parameters:: parameters.yaml
+
+  - nodes: server_topology_nodes
+  - nodes.cpu_pinning: server_topology_nodes_cpu_pinning
+  - nodes.vcpu_set: server_topology_nodes_vcpu_set
+  - nodes.siblings: server_topology_nodes_cpu_siblings
+  - nodes.memory_mb: server_topology_nodes_memory_mb
+  - nodes.host_numa_node: server_topology_nodes_host_numa_node
+  - pagesize_kb: server_topology_pagesize_kb
+
+**Example Server topology (2.xx)**
+
+.. literalinclude:: ../../doc/api_samples/os-server-topology/v2.78/servers-topology-resp.json
+   :language: javascript
+