x/valence
Code Issues Proposed changes

Aapi-ref doc, this is converted from Word file to RST format.

Browse Source 
Add pooled resources, compute system , composed node and flavor API.
Remove extra space with end of line and fix literal block warning.

Change-Id: Ib7f00617e48e7ecc6fe30091d79ef6b47ae4c5af
This commit is contained in:
chesterkuo 2016-10-24 12:09:23 -04:00
parent fe25cdeaae
commit b121cd520b
28 changed files with 1705 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

212
api-ref/source/conf.py Normal file
View File

@ -0,0 +1,212 @@
# -*- coding: utf-8 -*-
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
#
import os
import subprocess
import sys
import openstackdocstheme
html_theme = 'openstackdocs'
html_theme_path = [openstackdocstheme.get_html_theme_path()]
html_theme_options = {
"sidebar_mode": "toc",
}
extensions = [
'os_api_ref',
]
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('../'))
sys.path.insert(0, os.path.abspath('./'))
# -- General configuration ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#
# source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Valence API Reference'
copyright = u'OpenStack Foundation'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# Config logABug feature
# source tree
# html_context allows us to pass arbitrary values into the html template
html_context = {"bug_tag": "api-ref",
"bug_project": "valence"}
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# The reST default role (used for this markup: `text`) to use
# for all documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
add_module_names = False
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for man page output ----------------------------------------------
# Grouping the document tree for man pages.
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
# -- Options for HTML output --------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
# html_theme_path = ["."]
# html_theme = '_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
# html_last_updated_fmt = '%b %d, %Y'
git_cmd = ["git", "log", "--pretty=format:%ad, commit %h", "--date=local",
"-n1"]
html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8')
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_use_modindex = True
# If false, no index is generated.
# html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'valencedoc'
# -- Options for LaTeX output -------------------------------------------------
# The paper size ('letter' or 'a4').
# latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
# latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [
('index', 'Valence.tex', u'OpenStack Valence Controller API Documentation',
u'OpenStack Foundation', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# Additional stuff for the LaTeX preamble.
# latex_preamble = ''
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_use_modindex = True

16
api-ref/source/index.rst Normal file
View File

@ -0,0 +1,16 @@
:tocdepth: 2
=============
Valence API
=============
This is a reference for the Openstack Valence API
.. rest_expand_all::
.. include:: valence-api-version.inc
.. include:: valence-api-v1-pooled.inc
.. include:: valence-api-v1-flavor.inc
.. include:: valence-api-v1-system.inc
.. include:: valence-api-v1-nodes.inc

30
api-ref/source/mockup/api-root-response.json Normal file
View File

@ -0,0 +1,30 @@
{
"name": "OpenStack Valence API",
"description": "Valence is an OpenStack project which aims to provide node composition based on Redfish(R) API.",
"versions": [
{
"id": "v1.0",
"links": [
{
"href": "http://127.0.0.1:8181/v1/",
"rel": "self"
}
],
"status": "CURRENT",
"max_version": "",
"min_version": ""
},
{
"id": "v1.1",
"links": [
{
"href": "http://127.0.0.1:8181/v1/",
"ref": "self"
}
],
"status": "",
"max_version": "1.1",
"min_version": "1.0"
}
]
}

61
api-ref/source/mockup/api-v1-root-response.json Normal file
View File

@ -0,0 +1,61 @@
{
"id" : "v1",
"links" : [
{
"href" : "http://127.0.0.1:8181/v1/",
"rel" : "self"
},
{
"rel" : "describedby",
"type" : "text/html",
"href" : "http://docs.openstack.org/developer/valence/dev/api-spec-v1.html"
}
],
"nodes" : [
{
"rel" : "self",
"href" : "http://127.0.0.1:8181/v1/nodes/"
},
{
"rel" : "bookmark",
"href" : "http://127.0.0.1:8181/nodes/"
}
],
"systems" : [
{
"href" : "http://127.0.0.1:8181/v1/systems/",
"rel" : "self"
},
{
"rel" : "bookmark",
"href" : "http://127.0.0.1:8181/systems/"
}
],
"flavors" : [
{
"href" : "http://127.0.0.1:8181/v1/flavors/",
"rel" : "self"
},
{
"rel" : "bookmark",
"href" : "http://127.0.0.1:8181/flavors/"
}
],
"pooled" : [
{
"href" : "http://127.0.0.1:8181/v1/pooled/",
"rel" : "self"
},
{
"rel" : "bookmark",
"href" : "http://127.0.0.1:8181/pooled/"
}
],
"media_types" : [
{
"type" : "application/vnd.openstack.valence.v1+json",
"base" : "application/json"
}
]
}

4
api-ref/source/mockup/composed-node-create-request.json Normal file
View File

@ -0,0 +1,4 @@
{
"name": "test_node",
"description": "node1",
}

14
api-ref/source/mockup/composed-node-create-response.json Normal file
View File

@ -0,0 +1,14 @@
{
"uuid" : "eeeecccc-dddd-ffff-aaaa-uuuukkkk",
"name" : "Test-node-1",
"links" : [
{
"rel" : "self",
"href" : "https://127.0.0.1/v1/nodes/eeeecccc-dddd-ffff-aaaa-uuuukkkk"
},
{
"href" : "https://127.0.0.1/v1/nodes/eeeecccc-dddd-ffff-aaaa-uuuukkkk",
"rel" : "bookmark"
}
]
}

43
api-ref/source/mockup/composed-node-get-asset.json Normal file
View File

@ -0,0 +1,43 @@
{
"processor" : [
{
"device_type" : "CPU",
"instruction_set" : "x86-64",
"model" : "Multi-Core Intel(R) Xeon(R)Processor 7xxx Series",
"speed_mhz" : 3700,
"total_core" : 12
}
],
"memory" : [
{
"device_type" : "DDR3",
"data_width_bit" : 32,
"speed_mhz" : 1600,
"total_memory_gb" : 32
}
],
"network" : [
{
"device_type" : "ethernet",
"speed_mbps" : "40000"
}
],
"storage" : [
{
"protocol" : "SAS",
"volume_size_gb" : 40,
"pooled_resource" : false
},
{
"protocol" : "iSCSI",
"volume_size_gb" : 200,
"pooled_resource" : true
},
{
"protocol" : "NVMe",
"volume_size_gb" : 300,
"pooled_resource" : true
}
]
}

31
api-ref/source/mockup/composed-node-get-response.json Normal file
View File

@ -0,0 +1,31 @@
{
"uuid" : "4d8c3732-a248-40ed-bebc-539a6ffd25c0",
"node_power_state" : "Off",
"node_state" : "Allocated",
"boot_source" : "Hdd",
"target_boot_source": "Pxe",
"health_status" : "ok",
"name" : "Server-1",
"pooled_group_id" : "11z23344-0099-7766-5544-33225511",
"metadata" : {
"system_nic" : [
{"mac" : "f1:12:44:55:66:77"},
{"mac" : "f2:44:44:44:44:88"}
],
"mgmt_mac" : "00:AA:BB:CC:DD:EE",
"system_serialno" : "2M220100SL"
},
"url_id" : "node1",
"created_at" : "2016-04-20T15:40:00+00:00",
"updated_at" : "2016-04-20T15:40:00+00:00",
"links": [
{
"rel" : "self",
"href" : "https://127.0.0.1/v1/nodes/4d8c3732-a248-40ed-bebc-539a6ffd25c0"
},
{
"rel" : "boomark",
"href" : "https://127.0.0.1/nodes/4d8c3732-a248-40ed-bebc-539a6ffd25c0"
}
]
}

35
api-ref/source/mockup/composed-nodes-list-response.json Normal file
View File

@ -0,0 +1,35 @@
{
"nodes" : [
{
"uuid" : "ee1ecc3c-d3dd-f4ff-a6aa-uu7uk9k0",
"name" : "Server-1" ,
"nodes_power_state" : "On" ,
"links": [
{
"rel" : "self",
"href" : "https://127.0.0.1/v1/nodes/ee1ecc3c-d3dd-f4ff-a6aa-uu7uk9k0"
},
{
"href" : "https://127.0.0.1/nodes/ee1ecc3c-d3dd-f4ff-a6aa-uu7uk9k0",
"rel" : "bookmark"
}
]
},
{
"uuid" : "4d8c3732-a248-40ed-bebc-539a6ffd25c0" ,
"name" : "Server-2",
"node_power_state" : "Off" ,
"links" : [
{
"ref" : "self",
"href" : "https://127.0.0.1/v1/nodes/4d8c3732-a248-40ed-bebc-539a6ffd25c0"
},
{
"ref" : "bookmark",
"href" : "https://127.0.0.1/nodes/4d8c3732-a248-40ed-bebc-539a6ffd25c0"
}
]
}
]
}

21
api-ref/source/mockup/compute-system-get-response.json Normal file
View File

@ -0,0 +1,21 @@
{
"uuid" : "87e34f20-9c80-4e03-ba77-d836cfc26e70",
"power_state" : "Off",
"name" : "system-1",
"description": "description of compute system",
"chassis_id" : "sled2",
"assettag": "ComputeSystem-123"
"updated_at": "2016-08-25T01:13:16+00:00",
"created_at": "2016-08-25T01:13:16+00:00",
"links": [
{
"rel" : "self",
"href" : "https://127.0.0.1/v1/systems/87e34f20-9c80-4e03-ba77-d836cfc26e70"
},
{
"rel" : "boomark",
"href" : "https://127.0.0.1/systems/87e34f20-9c80-4e03-ba77-d836cfc26e70"
}
]
}

46
api-ref/source/mockup/compute-system-inventory-get-response.json Normal file
View File

@ -0,0 +1,46 @@
{
"processor" : [
{
"device_type": "cpu",
"instruction_set" : "x86-64",
"model" : "Multi-Core Intel(R) Xeon(R)Processor 7xxx Series",
"speed_mhz" : 3700,
"total_core": 12
}
],
"memory" : [
{
"device_type" : "DDR3",
"data_width_bit" : 32,
"speed_mhz" : 1600,
"total_memory_gb": 32
}
],
"storage" : [
{
"protocol" : "SAS",
"volume_size_gb": 300
},
{
"protocol" : "SATA",
"volume_size_gb": 240
}
],
"network" : [
{
"device_type" : "ethernet",
"speed_mbps" : "40000",
},
{
"device_type" : "ethernet",
"speed_mbps" : "40000"
}
],
"accelator": [
{
"device_type": "fpga",
"model": "Altera 3xxx series",
"gate_counte": "100000"
}
]
}

35
api-ref/source/mockup/compute-systems-list-response.json Normal file
View File

@ -0,0 +1,35 @@
{
"systems" : [
{
"uuid" : "87e34f20-9c80-4e03-ba77-d836cfc26e70",
"name" : "compute-system-1" ,
"power_state" : "On" ,
"links": [
{
"rel" : "self",
"href" : "https://127.0.0.1/v1/systems/87e34f20-9c80-4e03-ba77-d836cfc26e70"
},
{
"href" : "https://127.0.0.1/systems/87e34f20-9c80-4e03-ba77-d836cfc26e70",
"rel" : "bookmark"
}
]
},
{
"uuid" : "5a13e8a8-f8c7-480c-8098-0b6710b80709",
"name" : "compute-system-2" ,
"power_state" : "On" ,
"links": [
{
"rel" : "self",
"href" : "https://127.0.0.1/v1/systems/5a13e8a8-f8c7-480c-8098-0b6710b80709"
},
{
"href" : "https://127.0.0.1/systems/5a13e8a8-f8c7-480c-8098-0b6710b80709",
"rel" : "bookmark"
}
]
}
]
}

12
api-ref/source/mockup/flavor-criteria-get-response.json Normal file
View File

@ -0,0 +1,12 @@
{
"criteria": [
{
"name": "cpu",
"description": "Generates cpu based flavors"
},
{
"name": "default",
"description": "Generates 3 flavors(Tiny, Medium, Large) for each node considering all cpu cores, ram and storage"
}
]
}

3
api-ref/source/mockup/flavor-list-response.json Normal file
View File

@ -0,0 +1,3 @@
{
}

8
api-ref/source/mockup/flavor-post-response.json Normal file
View File

@ -0,0 +1,8 @@
[
[
"[{\"flavor\": {\"disk\": 0, \"vcpus\": 0, \"ram\": 16, \"name\": \"S_irsd-Rack1Block1\", \"id\": \"321a271b-ab30-4dfb-a098-6cfb8549a143\"}}, {\"extra_specs\": {\"Rack\": \"1\", \"Block\": \"1\"}}]",
"[{\"flavor\": {\"disk\": 0, \"vcpus\": 1, \"ram\": 32, \"name\": \"M_irsd-Rack1Block1\", \"id\": \"819ba7e5-1621-4bf1-b904-9a1a433fd338\"}}, {\"extra_specs\": {\"Rack\": \"1\", \"Block\": \"1\"}}]",
"[{\"flavor\": {\"disk\": 0, \"vcpus\": 2, \"ram\": 64, \"name\": \"L_irsd-Rack1Block1\", \"id\": \"79e27bb9-2a7e-4c10-8ded-9ec4cdd4856d\"}}, {\"extra_specs\": {\"Rack\": \"1\", \"Block\": \"1\"}}]"
]
]

4
api-ref/source/mockup/flavor-post.json Normal file
View File

@ -0,0 +1,4 @@
{
"criteria": "cpu, storage"
}

5
api-ref/source/mockup/node-post-action-attach-request.json Normal file
View File

@ -0,0 +1,5 @@
{
"attach": {
"uuid": "a698b7c2-0ca1-481a-87cd-4717a3d9c4d6"
}
}

5
api-ref/source/mockup/node-post-action-request.json Normal file
View File

@ -0,0 +1,5 @@
{
"Reset": {
"type": "On"
}
}

7
api-ref/source/mockup/node-update-name-info-request.json Normal file
View File

@ -0,0 +1,7 @@
[
{
"op": "replace",
"path": "/name",
"value": "composed-node1"
}
]

27
api-ref/source/mockup/resources-get-response.json Normal file
View File

@ -0,0 +1,27 @@
{
"uuid" : "4c16a45b-b029-49c4-af84-1abcf458a062",
"pooled_group_id" : "fabric2-1",
"state": "available",
"health_status" : "OK",
"type" : "storage",
"entity_link": "/chassis/PCIe/Drives/Disk.0",
"entity_capability" :
{
"volume_size_gb" : 200,
"protocol" : "NVMe",
"erase_on_detach": "true"
},
"updated_at": "2016-08-25T01:13:16+00:00",
"created_at": "2016-08-25T01:13:16+00:00",
"links": [
{
"rel" : "self",
"href" : "https://127.0.0.1/v1/pooled/4c16a45b-b029-49c4-af84-1abcf458a062"
},
{
"rel" : "boomark",
"href" : "https://127.0.0.1/pooled/4c16a45b-b029-49c4-af84-1abcf458a062"
}
]
}

37
api-ref/source/mockup/resources-list-response.json Normal file
View File

@ -0,0 +1,37 @@
{
"resources" : [
{
"uuid": "bbfddf09-4d7e-40d5-88a9-8acfb2f88c21",
"pooled_group_id" : "fabric2-1",
"state" : "available",
"type" : "storage",
"links" : [
{
"ref" : "self",
"href" : "https://127.0.0.1/v1/pooled/bbfddf09-4d7e-40d5-88a9-8acfb2f88c21"
},
{
"ref" : "bookmark",
"href" : "https://127.0.0.1/pooled/bbfddf09-4d7e-40d5-88a9-8acfb2f88c21"
}
]
},
{
"uuid" : "4c16a45b-b029-49c4-af84-1abcf458a062",
"pooled_group_id" : "fabric3-2",
"state" : "allocated",
"type" : "storage",
"links" : [
{
"ref" : "self",
"href" : "https://127.0.0.1/v1/pooled/4c16a45b-b029-49c4-af84-1abcf458a062"
},
{
"ref" : "bookmark",
"href" : "https://127.0.0.1/pooled/4c16a45b-b029-49c4-af84-1abcf458a062"
}
]
}
]
}

367
api-ref/source/parameters.yaml Normal file
View File

@ -0,0 +1,367 @@
# variables in header
openstack-request-id:
description: >
A unique ID for tracking the request. The request ID associated with the request
appears in the log lines for that request.
in: header
required: false
type: string
valence-api-header-version:
description: |
Specific API microversion used to generate this response.
in: header
required: true
type: string
x-openstack-valence-api-version:
description: >
A request SHOULD include this header to indicate to the Valence API controller what
version the client supports. The controller will transform the response object into
compliance with the requested version, if it is supported, or return a
406 Not Supported error.
If this header is not supplied, the server will default to ``min_version``
in all responses.
in: header
required: true
type: string
node_ident:
description: |
The UUID or name of composed node.
in: path
required: true
type: string
system_ident:
description: |
The UUID or name of Compute System.
in: path
required: true
type: string
#
fields:
description: |
One or more fields to be returned in response.
For example, the following request return only the "uuid", "node_state"
for each node
::
GET /v1/nodes?fields=uuid,node-state
in: query
required: true
type: array
# variables in common
created_at:
description: |
The date and time when the resource was created. The date and time
stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``. The ``±hh:mm``
value, if included, is the time zone as an offset from UTC. In
the previous example, the offset value is ``-05:00``.
in: body
required: true
type: string
criteria_list:
description: |
Criteria name for generated a new one.
in: body
required: true
type: string
criteria_object:
description: |
Criteria object including name and its description.
in: body
required: true
type: string
id:
description: |
Major API version, eg, "v1"
in: body
required: true
type: string
links:
description: |
A list of relative links, includes the slef and bookmark links.
in: body
required: true
type: array
node_attach_type:
description: |
type of action , including "attach" or "detach".
in: body
required: true
type: string
node_boot_source:
description: |
The value of this contain the source to boot the composed node, including
"pxe", "hdd", "none"
in: body
required: true
type: string
node_chassis_id:
description: |
The chassis id show the location id of a composed node.
ex: Rack12
in: body
required: true
type: string
node_description:
description: |
Description for new created composed node
in: body
required: true
type: string
node_health_status:
description: |
Composed node health status, support "ok", "warning", "critical"
in: body
required: true
type: string
node_memory_asset:
description: |
Memory asset (Object) info.
in: body
required: true
type: array
node_metadata:
description: |
Metadata of composed system, usually admin use this info to do basic
deployment in DataCenter.
in: body
required: true
type: array
node_name:
description: |
Name of composed name (a human-readable string)
in: body
required: true
type: string
node_network_asset:
description: |
Network asset (Object) info.
in: body
required: true
type: array
node_power_state:
description: |
The current composed node power state including
"On", "Off", "PoweringOn" ,"PoweringOff"
in: body
required: true
type: string
node_processor_asset:
description: |
Processor asset (Object) info.
in: body
required: true
type: array
node_property:
description: |
Property of composed node including processor , memory , storage info.
in: body
required: true
type: array
node_provision_state:
description: |
The composed node state value set by other orchestation tool, use this value
to help with orchestration software know its proviision progress.
in: body
required: true
type: string
node_request_description:
description: |
A description for a new composed node
in: body
required: tree
type: string
node_request_name:
description: |
Name of new composed node
in: body
required: true
type: string
node_reset_type:
description: |
Reset type for a composed , supported "ForceOn", "On", "ForceOff", "GracefulRestart"
in: body
required: true
type: string
node_state:
description: |
The current composed node state including
"Assembling", "Allocating", "Assembling" ,"Failed", "Assembled"
in: body
required: true
type: string
node_storage_asset:
description: |
Storage asset (Object) info.
in: body
required: true
type: array
node_target_boot_source:
description: |
The target ( pending ) boot source for next power reset.
in: body
required: true
type: string
node_url_id:
description: |
The URL id point to redfish API.
Ex: while url_id is "node1" ,the full path talk to redfish service should be "/redfish/v1/Nodes/node1"
in: body
required: true
type: string
node_uuid:
description: |
UUID of composed node
in: body
required: true
type: string
pooled_group_id:
description: |
The group id of pooled resource, resource can only be assigned to composed node while id matched.
This id combine with Switch doamin id + Fabric Id as a unique id
in: body
required: true
type: string
resource_entity_capability:
description: |
The resource capability , includes volume size, protocol
in: body
required: true
type: array
resource_health_status:
description: |
The healt status of pooled resource, supported "OK" , "Critical" , "Warning"
in: body
required: true
type: string
resource_link:
description: |
The Entity link of resource, this keep the string of EntityLink in EndPoint schema of Redfish.
in: body
required: true
type: string
resource_state:
description: |
The resource state , supported "allocated", "available", "busy", "failed"
in: body
required: true
type: string
resource_type:
description: |
The resource type , supported "storage", "network"
in: body
required: true
type: string
resource_uuid:
description: |
UUID of pooled resources, each pooled resources come with generated UUID.
in: body
required: true
type: string
system_assettag:
description: |
Asset Tag value of Compute System
in: body
required: true
type: string
system_chassis_id:
description: |
The chassis id that contained Compute system can be used to support location id
allocation if user want to specific a resource send to redfish service, ex: Sled2, meaning
it point to "/redfish/v1/Chassis/Sled2".
in: body
required: true
type: string
system_memory_object:
description: |
The memory (object) inventory of Compute system
in: body
required: true
type: array
system_name:
description: |
Name of Compute System (a human-readable string)
in: body
required: true
type: string
system_network_object:
description: |
The network (object) inventory of Compute System.
in: body
required: true
type: array
system_power_state:
description: |
The current Compute System power state including "On","Off"
"PoweredOn", "PoweredOff"
in: body
required: true
type: array
system_processor_object:
description: |
The Processor (object) inventory of a Compute System.
in: body
required: true
type: array
system_storage_object:
description: |
The Storage (object) inventory of a Compute System.
in: body
required: string
type: array
system_url_id:
description: |
The URL id point to redfish API.
For example, while url_id is "system1" ,the full path talk to redfish service should be "/redfish/v1/Systems/system1"
in: body
required: true
type: string
system_uuid:
description: |
UUID of Compute System
in: body
required: true
type: string
updated_at:
description: |
The date and time when the resource was created. The date and time
stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``. The ``±hh:mm``
value, if included, is the time zone as an offset from UTC. In
the previous example, the offset value is ``-05:00``.
in: body
required: true
type: string
version:
description: |
Versioning of this API response, eg. "1.0".
in: body
required: true
type: string
versions:
description: |
Array of information about currently supported versions.
in: body
required: true
type: array
x-openstack-valence-api-max-version:
description: |
Maximum API microversion supported by this endpoint, eg. "1.2"
in: body
required: true
type: string
x-openstack-valence-api-min-version:
description: |
Minimum API microversion supported by this endpoint, eg. "1.0"
in: body
required: true
type: string

90
api-ref/source/valence-api-v1-flavor.inc Normal file
View File

@ -0,0 +1,90 @@
.. -*- rst -*-
============
Flavors
============
List, Searching of Flavors through the ``/v1/flavor``
List Flavor
============
.. rest_method:: GET /v1/flavor/
Leaving this empty for discussion due to there isn't a DB to keep generated flavor.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
Response
--------
**Example list of Flavor :**
.. literalinclude:: mockup/flavor-list-response.json
:language: javascript
Generate Flavor
===============
.. rest_method:: POST /v1/flavor
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), 404, 409
Request
-------
.. rest_parameters:: parameters.yaml
- criterial: criteria_list
**Example generate flavor :**
.. literalinclude:: mockup/flavor-post.json
:language: javascript
Response
---------
**Example list of Flavor :**
.. literalinclude:: mockup/flavor-post-response.json
:language: javascript
List Flavor criteria
=====================
.. rest_method:: GET /v1/flavor/criteria
Get all supported flavor generation criteria along with their description.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
Response
--------
.. rest_parameters:: parameters.yaml
- criteria: criteria_object
**Example JSON representation of a Compute System:**
.. literalinclude:: mockup/flavor-criteria-get-response.json
:language: javascript

313
api-ref/source/valence-api-v1-nodes.inc Normal file
View File

@ -0,0 +1,313 @@
.. -*- rst -*-
==================
Composed nodes
==================
List, Searching, Creating, Updating, and Deleting of Composed Node resources
are done through the ``/v1/nodes`` resource.
A Composed node may be referenced both by its UUID and by a unique "name".
Send feedback to Valence team or [chester.kuo@gmail.com]
Create Node
===========
.. rest_method:: POST /v1/nodes
Creates a new Composed node with specific resources or empty request in json request
file.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- name: node_request_name
- description: node_request_description
**Example Node creation request:**
.. literalinclude:: mockup/composed-node-create-request.json
:language: javascript
Response
--------
The response will contain the complete node uuid and name record
The list and example below are representative of the response as of API
.. rest_parameters:: parameters.yaml
- uuid: node_uuid
- name: node_name
- links: links
**Example JSON representation of a Node:**
.. literalinclude:: mockup/composed-node-create-response.json
:language: javascript
List Nodes
==========
.. rest_method:: GET /v1/nodes/
Return a list of Composed nodes.
some filtering is possible by passing in flags with the request.
By default, this query will return node object with the name, uuid and node_power_state
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
Response
--------
.. rest_parameters:: parameters.yaml
- uuid: node_uuid
- name: node_name
- node_power_state: node_power_state
- links: links
**Example list of composed nodes:**
.. literalinclude:: mockup/composed-nodes-list-response.json
:language: javascript
List Composed node Details
=============================
.. rest_method:: GET /v1/nodes/{node-ident}
Shows details for a composed node.
This will return the full representation of the resources
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
- fields: fields
Response
--------
.. rest_parameters:: parameters.yaml
- uuid: node_uuid
- description: node_description
- name: node_name
- node_power_state: node_power_state
- node_state: node_state
- metadata: node_metadata
- boot_source: node_boot_source
- target_boot_source: node_target_boot_source
- pooled_group_id: pooled_group_id
- health_status: node_health_status
- url_id : node_url_id
- created_at: created_at
- updated_at: updated_at
- provision_state: node_provision_state
- links: links
**Example JSON representation of a Node:**
.. literalinclude:: mockup/composed-node-get-response.json
:language: javascript
Update Node
===========
.. rest_method:: PATCH /v1/nodes/{node_ident}
Updates the property stored about a composed node.
Note that this endpoint can not be used to request state changes, which are
managed through sub-resources.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), 404
Request
-------
The BODY of the PATCH request must be a JSON PATCH document, adhering to
`RFC 6902 <https://tools.ietf.org/html/rfc6902>`_.
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
**Example PATCH document updating composed node :**
.. literalinclude:: mockup/node-update-name-info-request.json
Response
--------
.. rest_parameters:: parameters.yaml
- uuid: node_uuid
- description: node_description
- name: node_name
- node_power_state: node_power_state
- metadata: node_metadata
- boot_source: node_boot_source
- target_boot_source: node_target_boot_source
- pooled_group_id: pooled_group_id
- health_status: node_health_status
- url_id : node_url_id
- created_at: created_at
- updated_at: updated_at
- provision_state: node_provision_state
- links: links
**Example JSON representation of a Node:**
.. literalinclude:: mockup/composed-node-get-response.json
:language: javascript
Response
--------
There is no body content for the response of a successful POST operation.
Delete Node
===========
.. rest_method:: DELETE /v1/nodes/{node_ident}
Deletes a node.
Normal response codes: 204
Error response codes: 401,403, 404 ,409
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
Node reset
===========
.. rest_method:: POST /v1/nodes/{node_ident}/action
Send a POST (reset) cmd to a composed node.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
- reset_type: node_reset_type
**Example POST action cmd for composed node :**
.. literalinclude:: mockup/node-post-action-request.json
:language: javascript
Response
--------
There is no body content for the response of a successful POST operation.
Resource attach/detach
==========================
.. rest_method:: POST /v1/nodes/{node_ident}/action
Send a attach/detach cmd to a composed node.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
- type: node_attach_type
- uuid: resource_uuid
**Example POST action cmd for composed node :**
.. literalinclude:: mockup/node-post-action-attach-request.json
:language: javascript
Response
--------
There is no body content for the response of a successful POST operation.
Once attach action successful, the resources state need to be updated to "allocated",
and the new resources can show up as asset under a composde node.
Node Assets
===========
.. rest_method:: GET /v1/nodes/{node_ident}/assets
Get all of Assets info of Composed node , Asset included pooled resource
and fixed inventory of Compute System.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Requet
------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
Response
--------
.. rest_parameters:: parameters.yaml
- memory: node_memory_asset
- network: node_network_asset
- processor: node_processor_asset
- storage: node_storage_asset
**Example JSON representation of a Node:**
.. literalinclude:: mockup/composed-node-get-asset.json
:language: javascript

79
api-ref/source/valence-api-v1-pooled.inc Normal file
View File

@ -0,0 +1,79 @@
.. -*- rst -*-
==================
Pooled Resources
==================
List, Searching of Pooled resources are done through the ``/v1/pooled``
List Pooled Resources
======================
.. rest_method:: GET /v1/pooled/
Return a list of Pooled Resources, this list generated by Valence controller from resource pool.
By default, this query will return resources object with the uuid and group_id.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
Response
--------
.. rest_parameters:: parameters.yaml
- pooled_group_id: pooled_group_id
- state: resource_state
- type: resource_type
- uuid: resource_uuid
- links: links
**Example list of Pooled Resources:**
.. literalinclude:: mockup/resources-list-response.json
:language: javascript
List Pooled Resource Details
=============================
.. rest_method:: GET /v1/pooled/{resource_ident}
Shows details for a pooled resources.
This will return the full representation of the resources
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- resources_ident: resource_uuid
- fields: fields
Response
--------
.. rest_parameters:: parameters.yaml
- uuid: resource_uuid
- pooled_group_id: pooled_group_id
- state: resource_state
- health_status: resource_health_status
- entity_type: resource_type
- entity_link: resource_link
- entity_capability: resource_entity_capability
- links: links
**Example JSON representation of a resource entity:**
.. literalinclude:: mockup/resources-get-response.json
:language: javascript

119
api-ref/source/valence-api-v1-system.inc Normal file
View File

@ -0,0 +1,119 @@
.. -*- rst -*-
==============
Compute System
==============
List, Searching of Composed Node resources are done through the ``/v1/systems``
A Compute node may be referenced both by its UUID and by a unique "name".
Send feedback to Valence team or [chester.kuo@gmail.com]
List Compute System
===================
.. rest_method:: GET /v1/systems/
Return a list of Compute System.
some filtering is possible by passing in flags with the request.
By default, this query will return compute system object with the name, uuid and power_state
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
Response
--------
.. rest_parameters:: parameters.yaml
- uuid: system_uuid
- name: system_name
- power_state: system_power_state
- links: links
**Example list of Compute System:**
.. literalinclude:: mockup/compute-systems-list-response.json
:language: javascript
List Compute System Details
===========================
.. rest_method:: GET /v1/systems/{system_ident}
Shows details for a Compute System.
This will return the full representation of the resources
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- system_ident: system_ident
- fields: fields
Response
--------
.. rest_parameters:: parameters.yaml
- uuid: system_uuid
- description: node_description
- name: system_name
- power_state: system_power_state
- chassis_id : system_chassis_id
- assettag: system_assettag
- url_id : system_url_id
- created_at: created_at
- updated_at: updated_at
- links: links
**Example JSON representation of a Compute System:**
.. literalinclude:: mockup/compute-system-get-response.json
:language: javascript
List Compute System Inventory Details
=====================================
.. rest_method:: GET /v1/systems/{system_ident}/inventory
Shows invneotyr data for a Compute System.
This will return the full representation of the resources include processor
memory, storage objects
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- system_ident: system_ident
Response
--------
.. rest_parameters:: parameters.yaml
- processor: system_processor_object
- memory: system_memory_object
- storage: system_storage_object
- network: system_network_object
**Example JSON representation of a Node:**
.. literalinclude:: mockup/compute-system-inventory-get-response.json
:language: javascript

74
api-ref/source/valence-api-version.inc Normal file
View File

@ -0,0 +1,74 @@
.. -*- rst -*-
================
API versions v1
================
Concepts
========
In order to bring new features to users over time, the Valence API
supports versioning. There are two kinds of versions in Ironic.
- ''major versions'', which have dedicated urls.
- ''microversions'', which can be requested through the use of the
``OpenStack-API-Version`` header.
The Version APIs work differently from other APIs as they do not require authentication.
Alll API requests support the ``OpenStack-API-Version`` header.
This header SHALL be supplied with every request.
This help to provide backwards compatibility as we introduced new features in the server.
List API versions
=================
.. rest_method:: GET /
This fetches all the information about all known major API versions in the
deployment. Links to more specific information will be provided for each major
API version, as well as information about supported min and max microversions.
Normal response codes: 200
Request
-------
Response Example
----------------
.. rest_parameters:: parameters.yaml
- versions: versions
- id: id
- links: links
- max_version: x-openstack-valence-api-max-version
- min_version: x-openstack-valence-api-min-version
.. literalinclude:: mockup/api-root-response.json
:language: javascript
Show v1 API
===========
.. rest_method:: GET /v1/
Show all the resources within the Valence v1 API.
Normal response codes: 200
Request
-------
Response Example
----------------
.. rest_parameters:: parameters.yaml
- id: id
- links: links
- openstack-request-id: openstack-request-id
.. literalinclude:: mockup/api-v1-root-response.json
:language: javascript

7
tox.ini
View File

@ -55,6 +55,13 @@ commands = oslo_debug_helper {posargs}
install_command = {[testenv:common-constraints]install_command} install_command = {[testenv:common-constraints]install_command}
commands = oslo_debug_helper {posargs} commands = oslo_debug_helper {posargs}
[testenv:api-ref]
# This environment is called from CI scripts to test and publish
# the API Ref to developer.openstack.org.
commands =
rm -rf api-ref/build
sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
[flake8] [flake8]
# E123, E125 skipped as they are invalid PEP-8. # E123, E125 skipped as they are invalid PEP-8.