x/nova-dpm
Code Issues Proposed changes

Docs: Add Feature Support Matrix

Browse Source 
To give customers a glimpse of what to expect from this driver,
this change adds a feature support matrix.
As the nova-dpm driver is out-of-tree, we cannot add it to the
in-tree documentation at
    http://docs.openstack.org/developer/nova/support-matrix.html
Having *all* drivers in this change would add too much maintenance
and manual sync-up between the two repositories (novavs. nova-dpm),
therefore we list only the dpm-driver here.

Closes bug: 1657700

Change-Id: Ie65cb50dc54ce8116f608c3a5280407cf820a2b0
This commit is contained in:
Markus Zoeller 2017-01-30 10:31:08 +01:00
parent 8f82f0a442
commit ec9ad7dbcc
8 changed files with 1254 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.rst
View File

@ -31,7 +31,3 @@ management platform on z Systems.
* Source: http://git.openstack.org/cgit/openstack/nova-dpm
* Bugs: http://bugs.launchpad.net/nova-dpm
Features
--------
* TODO

0
doc/ext/__init__.py Normal file
View File

519
doc/ext/support_matrix.py Normal file
View File

@ -0,0 +1,519 @@
# Copyright (C) 2014 Red Hat, Inc.
#
# 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.
"""
This provides a sphinx extension able to render the source/support-matrix.ini
file into the developer documentation.
It is used via a single directive in the .rst file
.. support_matrix::
"""
import re
import sys
import six
from six.moves import configparser
from docutils import nodes
from docutils.parsers import rst
class SupportMatrix(object):
"""Represents the entire support matrix for Nova virt drivers
"""
def __init__(self):
# List of SupportMatrixFeature instances, describing
# all the features present in Nova virt drivers
self.features = []
# Dict of (name, SupportMatrixTarget) enumerating
# all the hypervisor drivers that have data recorded
# for them in self.features. The 'name' dict key is
# the value from the SupportMatrixTarget.key attribute
self.targets = {}
class SupportMatrixFeature(object):
STATUS_MANDATORY = "mandatory"
STATUS_CHOICE = "choice"
STATUS_CONDITION = "condition"
STATUS_OPTIONAL = "optional"
STATUS_ALL = [STATUS_MANDATORY, STATUS_CHOICE,
STATUS_CONDITION, STATUS_OPTIONAL]
def __init__(self, key, title, status=STATUS_OPTIONAL,
group=None, notes=None, cli=[]):
# A unique key (eg 'foo.bar.wizz') to identify the feature
self.key = key
# A human friendly short title for the feature
self.title = title
# One of the status constants
self.status = status
# Detail string if status was choice/condition
self.group = group
# Arbitrarily long string describing the feature in detail
self.notes = notes
# Dict of (name, SupportMatrixImplementation) detailing
# the implementation for each hypervisor driver. The
# 'name' dict key is the value from SupportMatrixTarget.key
# for the hypervisor in question
self.implementations = {}
# A list of CLI commands which are related to that feature
self.cli = cli
class SupportMatrixImplementation(object):
STATUS_COMPLETE = "complete"
STATUS_PARTIAL = "partial"
STATUS_MISSING = "missing"
STATUS_UKNOWN = "unknown"
STATUS_ALL = [STATUS_COMPLETE, STATUS_PARTIAL, STATUS_MISSING,
STATUS_UKNOWN]
def __init__(self, status=STATUS_MISSING, notes=None):
# One of the status constants detailing the implementation
# level
self.status = status
# Arbitrary string describing any caveats of the implementation.
# Mandatory if status is 'partial', optional otherwise.
self.notes = notes
class SupportMatrixTarget(object):
def __init__(self, key, title, driver, hypervisor=None, architecture=None):
""":param key: Unique identifier for the hypervisor driver
:param title: Human friendly name of the hypervisor
:param driver: Name of the Nova driver
:param hypervisor: (optional) Name of the hypervisor, if many
:param architecture: (optional) Name of the architecture, if many
"""
self.key = key
self.title = title
self.driver = driver
self.hypervisor = hypervisor
self.architecture = architecture
class SupportMatrixDirective(rst.Directive):
# The argument is the filename, e.g. support-matrix.ini
required_arguments = 1
def run(self):
matrix = self._load_support_matrix()
return self._build_markup(matrix)
def _load_support_matrix(self):
"""Reads the support-matrix.ini file and populates an instance
of the SupportMatrix class with all the data.
:returns: SupportMatrix instance
"""
# SafeConfigParser was deprecated in Python 3.2
if sys.version_info >= (3, 2):
cfg = configparser.ConfigParser()
else:
cfg = configparser.SafeConfigParser()
env = self.state.document.settings.env
fname = self.arguments[0]
rel_fpath, fpath = env.relfn2path(fname)
with open(fpath) as fp:
cfg.readfp(fp)
# This ensures that the docs are rebuilt whenever the
# .ini file changes
env.note_dependency(rel_fpath)
matrix = SupportMatrix()
matrix.targets = self._get_targets(cfg)
matrix.features = self._get_features(cfg, matrix.targets)
return matrix
def _get_targets(self, cfg):
# The 'targets' section is special - it lists all the
# hypervisors that this file records data for
targets = {}
for item in cfg.options("targets"):
if not item.startswith("driver-impl-"):
continue
# The driver string will optionally contain
# a hypervisor and architecture qualifier
# so we expect between 1 and 3 components
# in the name
key = item[12:]
title = cfg.get("targets", item)
name = key.split("-")
if len(name) == 1:
target = SupportMatrixTarget(key,
title,
name[0])
elif len(name) == 2:
target = SupportMatrixTarget(key,
title,
name[0],
name[1])
elif len(name) == 3:
target = SupportMatrixTarget(key,
title,
name[0],
name[1],
name[2])
else:
raise Exception("'%s' field is malformed in '[%s]' section" %
(item, "DEFAULT"))
targets[key] = target
return targets
def _get_features(self, cfg, targets):
# All sections except 'targets' describe some feature of
# the Nova hypervisor driver implementation
features = []
for section in cfg.sections():
if section == "targets":
continue
if not cfg.has_option(section, "title"):
raise Exception(
"'title' field missing in '[%s]' section" % section)
title = cfg.get(section, "title")
status = SupportMatrixFeature.STATUS_OPTIONAL
if cfg.has_option(section, "status"):
# The value is a string "status(group)" where
# the 'group' part is optional
status = cfg.get(section, "status")
offset = status.find("(")
group = None
if offset != -1:
group = status[offset + 1:-1]
status = status[0:offset]
if status not in SupportMatrixFeature.STATUS_ALL:
raise Exception(
"'status' field value '%s' in ['%s']"
"section must be %s" %
(status, section,
",".join(SupportMatrixFeature.STATUS_ALL)))
notes = None
if cfg.has_option(section, "notes"):
notes = cfg.get(section, "notes")
cli = []
if cfg.has_option(section, "cli"):
cli = cfg.get(section, "cli")
feature = SupportMatrixFeature(section,
title,
status,
group,
notes,
cli)
# Now we've got the basic feature details, we must process
# the hypervisor driver implementation for each feature
for item in cfg.options(section):
if not item.startswith("driver-impl-"):
continue
key = item[12:]
if key not in targets:
raise Exception(
"Driver impl '%s' in '[%s]' not declared" %
(item, section))
status = cfg.get(section, item)
if status not in SupportMatrixImplementation.STATUS_ALL:
raise Exception(
"'%s' value '%s' in '[%s]' section must be %s" %
(item, status, section,
",".join(SupportMatrixImplementation.STATUS_ALL)))
noteskey = "driver-notes-" + item[12:]
notes = None
if cfg.has_option(section, noteskey):
notes = cfg.get(section, noteskey)
target = targets[key]
impl = SupportMatrixImplementation(status,
notes)
feature.implementations[target.key] = impl
for key in targets:
if key not in feature.implementations:
raise Exception("'%s' missing in '[%s]' section" %
(target.key, section))
features.append(feature)
return features
def _build_markup(self, matrix):
"""Constructs the docutils content for the support matrix
"""
content = []
self._build_summary(matrix, content)
self._build_details(matrix, content)
self._build_notes(content)
return content
def _build_summary(self, matrix, content):
"""Constructs the docutils content for the summary of
the support matrix.
The summary consists of a giant table, with one row
for each feature, and a column for each hypervisor
driver. It provides an 'at a glance' summary of the
status of each driver
"""
summarytitle = nodes.subtitle(text="Summary")
summary = nodes.table()
cols = len(matrix.targets.keys())
cols += 2
summarygroup = nodes.tgroup(cols=cols)
summarybody = nodes.tbody()
summaryhead = nodes.thead()
for i in range(cols):
summarygroup.append(nodes.colspec(colwidth=1))
summarygroup.append(summaryhead)
summarygroup.append(summarybody)
summary.append(summarygroup)
content.append(summarytitle)
content.append(summary)
# This sets up all the column headers - two fixed
# columns for feature name & status
header = nodes.row()
blank = nodes.entry()
blank.append(nodes.emphasis(text="Feature"))
header.append(blank)
blank = nodes.entry()
blank.append(nodes.emphasis(text="Status"))
header.append(blank)
summaryhead.append(header)
# then one column for each hypervisor driver
impls = list(matrix.targets.keys())
impls.sort()
for key in impls:
target = matrix.targets[key]
implcol = nodes.entry()
header.append(implcol)
implcol.append(nodes.strong(text=target.title))
# We now produce the body of the table, one row for
# each feature to report on
for feature in matrix.features:
item = nodes.row()
# the hyperlink target name linking to details
id = re.sub("[^a-zA-Z0-9_]", "_",
feature.key)
# first the to fixed columns for title/status
keycol = nodes.entry()
item.append(keycol)
keyref = nodes.reference(refid=id)
keytxt = nodes.inline()
keycol.append(keytxt)
keytxt.append(keyref)
keyref.append(nodes.strong(text=feature.title))
statuscol = nodes.entry()
item.append(statuscol)
statuscol.append(nodes.inline(
text=feature.status,
classes=["sp_feature_" + feature.status]))
# and then one column for each hypervisor driver
impls = list(matrix.targets.keys())
impls.sort()
for key in impls:
target = matrix.targets[key]
impl = feature.implementations[key]
implcol = nodes.entry()
item.append(implcol)
id = re.sub("[^a-zA-Z0-9_]", "_",
feature.key + "_" + key)
implref = nodes.reference(refid=id)
impltxt = nodes.inline()
implcol.append(impltxt)
impltxt.append(implref)
status = ""
if impl.status == SupportMatrixImplementation.STATUS_COMPLETE:
status = u"\u2714"
elif impl.status == SupportMatrixImplementation.STATUS_MISSING:
status = u"\u2716"
elif impl.status == SupportMatrixImplementation.STATUS_PARTIAL:
status = u"\u2714"
elif impl.status == SupportMatrixImplementation.STATUS_UKNOWN:
status = u"?"
implref.append(nodes.literal(
text=status,
classes=["sp_impl_summary", "sp_impl_" + impl.status]))
summarybody.append(item)
def _build_details(self, matrix, content):
"""Constructs the docutils content for the details of
the support matrix.
This is generated as a bullet list of features.
Against each feature we provide the description of
the feature and then the details of the hypervisor
impls, with any driver specific notes that exist
"""
detailstitle = nodes.subtitle(text="Details")
details = nodes.bullet_list()
content.append(detailstitle)
content.append(details)
# One list entry for each feature we're reporting on
for feature in matrix.features:
item = nodes.list_item()
status = feature.status
if feature.group is not None:
status += "(" + feature.group + ")"
# The hypervisor target name linked from summary table
id = re.sub("[^a-zA-Z0-9_]", "_",
feature.key)
# Highlight the feature title name
item.append(nodes.strong(text=feature.title,
ids=[id]))
para = nodes.paragraph()
para.append(nodes.strong(text="Status: " + status + ". "))
if feature.notes is not None:
para.append(nodes.inline(text=feature.notes))
item.append(para)
if feature.cli:
item.append(self._create_cli_paragraph(feature))
para_divers = nodes.paragraph()
para_divers.append(nodes.strong(text="drivers:"))
# A sub-list giving details of each hypervisor target
impls = nodes.bullet_list()
for key in feature.implementations:
target = matrix.targets[key]
impl = feature.implementations[key]
subitem = nodes.list_item()
id = re.sub("[^a-zA-Z0-9_]", "_",
feature.key + "_" + key)
subitem += [
nodes.strong(text=target.title + ": "),
nodes.literal(text=impl.status,
classes=["sp_impl_" + impl.status],
ids=[id]),
]
if impl.notes is not None:
subitem.append(self._create_notes_paragraph(impl.notes))
impls.append(subitem)
para_divers.append(impls)
item.append(para_divers)
details.append(item)
def _build_notes(self, content):
"""Constructs a list of notes content for the support matrix.
This is generated as a bullet list.
"""
notestitle = nodes.subtitle(text="Notes")
notes = nodes.bullet_list()
content.append(notestitle)
content.append(notes)
NOTES = []
for note in NOTES:
item = nodes.list_item()
item.append(nodes.strong(text=note))
notes.append(item)
def _create_cli_paragraph(self, feature):
''' Create a paragraph which represents the CLI commands of the feature
The paragraph will have a bullet list of CLI commands.
'''
para = nodes.paragraph()
para.append(nodes.strong(text="CLI commands:"))
commands = nodes.bullet_list()
for c in feature.cli.split(";"):
cli_command = nodes.list_item()
cli_command += nodes.literal(text=c, classes=["sp_cli"])
commands.append(cli_command)
para.append(commands)
return para
def _create_notes_paragraph(self, notes):
""" Constructs a paragraph which represents the implementation notes
The paragraph consists of text and clickable URL nodes if links were
given in the notes.
"""
para = nodes.paragraph()
# links could start with http:// or https://
link_idxs = [m.start() for m in re.finditer('https?://', notes)]
start_idx = 0
for link_idx in link_idxs:
# assume the notes start with text (could be empty)
para.append(nodes.inline(text=notes[start_idx:link_idx]))
# create a URL node until the next text or the end of the notes
link_end_idx = notes.find(" ", link_idx)
if link_end_idx == -1:
# In case the notes end with a link without a blank
link_end_idx = len(notes)
uri = notes[link_idx:link_end_idx + 1]
para.append(nodes.reference("", uri, refuri=uri))
start_idx = link_end_idx + 1
# get all text after the last link (could be empty) or all of the
# text if no link was given
para.append(nodes.inline(text=notes[start_idx:]))
return para
def setup(app):
app.add_directive('support_matrix', SupportMatrixDirective)
app.add_stylesheet('support-matrix.css')

47
doc/source/_static/support-matrix.css Normal file
View File

@ -0,0 +1,47 @@
.sp_feature_mandatory {
font-weight: bold;
}
.sp_feature_optional {
}
.sp_feature_choice {
font-style: italic;
font-weight: bold;
}
.sp_feature_condition {
font-style: italic;
font-weight: bold;
}
.sp_impl_complete {
color: rgb(0, 120, 0);
font-weight: normal;
}
.sp_impl_missing {
color: rgb(120, 0, 0);
font-weight: normal;
}
.sp_impl_partial {
color: rgb(170, 170, 0);
font-weight: normal;
}
.sp_impl_unknown {
color: rgb(170, 170, 170);
font-weight: normal;
}
.sp_impl_summary {
font-size: 2em;
}
.sp_cli {
font-family: monospace;
background-color: #F5F5F5;
}

5
doc/source/conf.py
View File

@ -18,11 +18,14 @@ import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
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.
extensions = [
'ext.support_matrix',
'sphinx.ext.autodoc',
#'sphinx.ext.intersphinx',
'sphinxcontrib.seqdiag',
@ -64,7 +67,7 @@ pygments_style = 'sphinx'
# Sphinx are currently 'default' and 'sphinxdoc'.
# html_theme_path = ["."]
# html_theme = '_theme'
# html_static_path = ['static']
html_static_path = ['_static']
# Output file base name for HTML help builder.
htmlhelp_basename = '%sdoc' % project

1
doc/source/index.rst
View File

@ -49,6 +49,7 @@ Contents:
:maxdepth: 2
readme
support-matrix
installation
usage
contributing

642
doc/source/support-matrix.ini Normal file
View File

@ -0,0 +1,642 @@
# Copyright (C) 2014 Red Hat, Inc.
#
# 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.
#
#
#
# =========================================
# Nova Hypervisor Feature Capability Matrix
# =========================================
#
# This obsoletes the information previously at
#
# https://wiki.openstack.org/wiki/HypervisorSupportMatrix
#
# This file contains a specification of what feature capabilities each
# hypervisor driver in Nova is able to support. Feature capabilities include
# what API operations are supported, what storage / networking features can be
# used and what aspects of the guest machine can be configured. The capabilities
# can be considered to be structured into nested groups, but in this file they
# have been flattened for ease of representation. The section names represent
# the group structure. At the top level there are the following groups defined
#
# - operation - public API operations
# - storage - host storage configuration options
# - networking - host networking configuration options
# - guest - guest hardware configuration options
#
# When considering which capabilities should be marked as mandatory,
# consider the general guiding principles listed in the support-matrix.rst
# file
#
# The 'status' field takes possible values
#
# - mandatory - unconditionally required to be implemented
# - optional - optional to support, nice to have
# - choice(group) - at least one of the options within the named group
# must be implemented
# - conditional(cond) - required, if the referenced condition is met.
#
# The value against each 'driver-impl-XXXX' entry refers to the level
# of the implementation of the feature in that driver
#
# - complete - fully implemented, expected to work at all times
# - partial - implemented, but with caveats about when it will work
# eg some configurations or hardware or guest OS may not
# support it
# - missing - not implemented at all
#
# In the case of the driver being marked as 'partial', then
# 'driver-notes-XXX' entry should be used to explain the caveats
# around the implementation.
#
# The 'cli' field takes a list of nova client commands, separated by semicolon.
# These CLi commands are related to that feature.
# Example:
# cli=nova list;nova show <server>
#
[targets]
# List of driver impls we are going to record info for later
# This list only covers drivers that are in the Nova source
# tree. Out of tree drivers should maintain their own equivalent
# document, and merge it with this when their code merges into
# Nova core.
driver-impl-ibm-dpm=IBM DPM
[operation.attach-volume]
title=Attach block volume to instance
status=optional
notes=The attach volume operation provides a means to hotplug
additional block storage to a running instance. This allows
storage capabilities to be expanded without interruption of
service. In a cloud model it would be more typical to just
spin up a new instance with large storage, so the ability to
hotplug extra storage is for those cases where the instance
is considered to be more of a pet than cattle. Therefore
this operation is not considered to be mandatory to support.
cli=nova volume-attach <server> <volume>
driver-impl-ibm-dpm=missing
[operation.detach-volume]
title=Detach block volume from instance
status=optional
notes=See notes for attach volume operation.
cli=nova volume-detach <server> <volume>
driver-impl-ibm-dpm=missing
[operation.attach-interface]
title=Attach virtual network interface to instance
status=optional
notes=The attach interface operation provides a means to hotplug
additional interfaces to a running instance. Hotplug support
varies between guest OSes and some guests require a reboot for
new interfaces to be detected. This operation allows interface
capabilities to be expanded without interruption of service.
In a cloud model it would be more typical to just spin up a
new instance with more interfaces.
cli=nova interface-attach <server>
driver-impl-ibm-dpm=missing
[operation.detach-interface]
title=Detach virtual network interface from instance
status=optional
notes=See notes for attach-interface operation.
cli=nova interface-detach <server> <port_id>
driver-impl-ibm-dpm=missing
[operation.maintenance-mode]
title=Set the host in a maintenance mode
status=optional
notes=This operation allows a host to be placed into maintenance
mode, automatically triggering migration of any running
instances to an alternative host and preventing new
instances from being launched. This is not considered
to be a mandatory operation to support.
The driver methods to implement are "host_maintenance_mode" and
"set_host_enabled".
cli=nova host-update <host>
driver-impl-ibm-dpm=missing
[operation.evacuate]
title=Evacuate instances from a host
status=optional
notes=A possible failure scenario in a cloud environment is the outage
of one of the compute nodes. In such a case the instances of the down
host can be evacuated to another host. It is assumed that the old host
is unlikely ever to be powered back on, otherwise the evacuation
attempt will be rejected. When the instances get moved to the new
host, their volumes get re-attached and the locally stored data is
dropped. That happens in the same way as a rebuild.
This is not considered to be a mandatory operation to support.
cli=nova evacuate <server>;nova host-evacuate <host>
driver-impl-ibm-dpm=missing
[operation.rebuild]
title=Rebuild instance
status=optional
notes=A possible use case is additional attributes need to be set
to the instance, nova will purge all existing data from the system
and remakes the VM with given information such as 'metadata' and
'personalities'. Though this is not considered to be a mandatory
operation to support.
cli=nova rebuild <server> <image>
driver-impl-ibm-dpm=missing
[operation.get-guest-info]
title=Guest instance status
status=mandatory
notes=Provides a quick report on information about the guest instance,
including the power state, memory allocation, CPU allocation, number
of vCPUs and cummulative CPU execution time. As well as being
informational, the power state is used by the compute manager for
tracking changes in guests. Therefore this operation is considered
mandatory to support.
cli=
driver-impl-ibm-dpm=complete
[operation.get-host-info]
title=Guest host status
status=optional
notes=Unclear what this refers to
cli=
driver-impl-ibm-dpm=missing
[operation.live-migrate]
title=Live migrate instance across hosts
status=optional
notes=Live migration provides a way to move an instance off one
compute host, to another compute host. Administrators may use
this to evacuate instances from a host that needs to undergo
maintenance tasks, though of course this may not help if the
host is already suffering a failure. In general instances are
considered cattle rather than pets, so it is expected that an
instance is liable to be killed if host maintenance is required.
It is technically challenging for some hypervisors to provide
support for the live migration operation, particularly those
built on the container based virtualization. Therefore this
operation is not considered mandatory to support.
cli=nova live-migration <server>;nova host-evacuate-live <host>
driver-impl-ibm-dpm=missing
[operation.force-live-migration-to-complete]
title=Force live migration to complete
status=optional
notes=Live migration provides a way to move a running instance to another
compute host. But it can sometimes fail to complete if an instance has
a high rate of memory or disk page access.
This operation provides the user with an option to assist the progress
of the live migration. The mechanism used to complete the live
migration depends on the underlying virtualization subsystem
capabilities. If libvirt/qemu is used and the post-copy feature is
available and enabled then the force complete operation will cause
a switch to post-copy mode. Otherwise the instance will be suspended
until the migration is completed or aborted.
cli=nova live-migration-force-complete <server> <migration>
driver-impl-ibm-dpm=missing
[operation.launch]
title=Launch instance
status=mandatory
notes=Importing pre-existing running virtual machines on a host is
considered out of scope of the cloud paradigm. Therefore this
operation is mandatory to support in drivers.
cli=
driver-impl-ibm-dpm=complete
[operation.pause]
title=Stop instance CPUs (pause)
status=optional
notes=Stopping an instances CPUs can be thought of as roughly
equivalent to suspend-to-RAM. The instance is still present
in memory, but execution has stopped. The problem, however,
is that there is no mechanism to inform the guest OS that
this takes place, so upon unpausing, its clocks will no
longer report correct time. For this reason hypervisor vendors
generally discourage use of this feature and some do not even
implement it. Therefore this operation is considered optional
to support in drivers.
cli=nova pause <server>
driver-impl-ibm-dpm=missing
[operation.reboot]
title=Reboot instance
status=optional
notes=It is reasonable for a guest OS administrator to trigger a
graceful reboot from inside the instance. A host initiated
graceful reboot requires guest co-operation and a non-graceful
reboot can be achieved by a combination of stop+start. Therefore
this operation is considered optional.
cli=nova reboot <server>
driver-impl-ibm-dpm=complete
driver-notes-ibm-dpm=Please note that this is will always be a hard reboot,
as the hypervisor doesn't support soft reboots.
[operation.rescue]
title=Rescue instance
status=optional
notes=The rescue operation starts an instance in a special
configuration whereby it is booted from an special root
disk image. The goal is to allow an administrator to
recover the state of a broken virtual machine. In general
the cloud model considers instances to be cattle, so if
an instance breaks the general expectation is that it be
thrown away and a new instance created. Therefore this
operation is considered optional to support in drivers.
cli=nova rescue <server>
driver-impl-ibm-dpm=missing
[operation.resize]
title=Resize instance
status=optional
notes=The resize operation allows the user to change a running
instance to match the size of a different flavor from the one
it was initially launched with. There are many different
flavor attributes that potentially need to be updated. In
general it is technically challenging for a hypervisor to
support the alteration of all relevant config settings for a
running instance. Therefore this operation is considered
optional to support in drivers.
cli=nova resize <server> <flavor>
driver-impl-ibm-dpm=missing
[operation.resume]
title=Restore instance
status=optional
notes=See notes for the suspend operation
cli=nova resume <server>
driver-impl-ibm-dpm=missing
[operation.service-control.wtf.com]
title=Service control
status=optional
notes=Something something, dark side, something something.
Hard to claim this is mandatory when no one seems to know
what "Service control" refers to in the context of virt
drivers.
cli=
driver-impl-ibm-dpm=missing
[operation.set-admin-password]
title=Set instance admin password
status=optional
notes=Provides a mechanism to (re)set the password of the administrator
account inside the instance operating system. This requires that the
hypervisor has a way to communicate with the running guest operating
system. Given the wide range of operating systems in existence it is
unreasonable to expect this to be practical in the general case. The
configdrive and metadata service both provide a mechanism for setting
the administrator password at initial boot time. In the case where this
operation were not available, the administrator would simply have to
login to the guest and change the password in the normal manner, so
this is just a convenient optimization. Therefore this operation is
not considered mandatory for drivers to support.
cli=nova set-password <server>
driver-impl-ibm-dpm=missing
[operation.snapshot]
title=Save snapshot of instance disk
status=optional
notes=The snapshot operation allows the current state of the
instance root disk to be saved and uploaded back into the
glance image repository. The instance can later be booted
again using this saved image. This is in effect making
the ephemeral instance root disk into a semi-persistent
storage, in so much as it is preserved even though the guest
is no longer running. In general though, the expectation is
that the root disks are ephemeral so the ability to take a
snapshot cannot be assumed. Therefore this operation is not
considered mandatory to support.
cli=nova image-create <server> <name>
driver-impl-ibm-dpm=missing
[operation.suspend]
title=Suspend instance
status=optional
notes=Suspending an instance can be thought of as roughly
equivalent to suspend-to-disk. The instance no longer
consumes any RAM or CPUs, with its live running state
having been preserved in a file on disk. It can later
be restored, at which point it should continue execution
where it left off. As with stopping instance CPUs, it suffers from the fact
that the guest OS will typically be left with a clock that
is no longer telling correct time. For container based
virtualization solutions, this operation is particularly
technically challenging to implement and is an area of
active research. This operation tends to make more sense
when thinking of instances as pets, rather than cattle,
since with cattle it would be simpler to just terminate
the instance instead of suspending. Therefore this operation
is considered optional to support.
cli=nova suspend <server>
driver-impl-ibm-dpm=missing
[operation.swap-volume]
title=Swap block volumes
status=optional
notes=The swap volume operation is a mechanism for changing a running
instance so that its attached volume(s) are backed by different
storage in the host. An alternative to this would be to simply
terminate the existing instance and spawn a new instance with the
new storage. In other words this operation is primarily targeted towards
the pet use case rather than cattle, however, it is required for volume
migration to work in the volume service. This is considered optional to
support.
cli=nova volume-update <server> <attachment> <volume>
driver-impl-ibm-dpm=missing
[operation.terminate]
title=Shutdown instance
status=mandatory
notes=The ability to terminate a virtual machine is required in
order for a cloud user to stop utilizing resources and thus
avoid indefinitely ongoing billing. Therefore this operation
is mandatory to support in drivers.
cli=nova delete <server>
driver-impl-ibm-dpm=complete
[operation.trigger-crash-dump]
title=Trigger crash dump
status=optional
notes=The trigger crash dump operation is a mechanism for triggering
a crash dump in an instance. The feature is typically implemented by
injecting an NMI (Non-maskable Interrupt) into the instance. It provides
a means to dump the production memory image as a dump file which is useful
for users. Therefore this operation is considered optional to support.
cli=
driver-impl-ibm-dpm=missing
[operation.unpause]
title=Resume instance CPUs (unpause)
status=optional
notes=See notes for the "Stop instance CPUs" operation
cli=nova unpause <server>
driver-impl-ibm-dpm=missing
[guest.disk.autoconfigure.wtf.com]
title=Auto configure disk
status=optional
notes=something something, dark side, something something.
Unclear just what this is about.
cli=
driver-impl-ibm-dpm=missing
[guest.disk.rate-limit]
title=Instance disk I/O limits
status=optional
notes=The ability to set rate limits on virtual disks allows for
greater performance isolation between instances running on the
same host storage. It is valid to delegate scheduling of I/O
operations to the hypervisor with its default settings, instead
of doing fine grained tuning. Therefore this is not considered
to be an mandatory configuration to support.
cli=nova limits
driver-impl-ibm-dpm=missing
[guest.setup.configdrive]
title=Config drive support
status=choice(guest.setup)
notes=The config drive provides an information channel into
the guest operating system, to enable configuration of the
administrator password, file injection, registration of
SSH keys, etc. Since cloud images typically ship with all
login methods locked, a mechanism to set the administrator
password of keys is required to get login access. Alternatives
include the metadata service and disk injection. At least one
of the guest setup mechanisms is required to be supported by
drivers, in order to enable login access.
cli=
driver-impl-ibm-dpm=missing
[guest.setup.inject.file]
title=Inject files into disk image
status=optional
notes=This allows for the end user to provide data for multiple
files to be injected into the root filesystem before an instance
is booted. This requires that the compute node understand the
format of the filesystem and any partitioning scheme it might
use on the block device. This is a non-trivial problem considering
the vast number of filesystems in existence. The problem of injecting
files to a guest OS is better solved by obtaining via the metadata
service or config drive. Therefore this operation is considered
optional to support.
cli=
driver-impl-ibm-dpm=missing
[guest.setup.inject.networking]
title=Inject guest networking config
status=optional
notes=This allows for static networking configuration (IP
address, netmask, gateway and routes) to be injected directly
into the root filesystem before an instance is booted. This
requires that the compute node understand how networking is
configured in the guest OS which is a non-trivial problem
considering the vast number of operating system types. The
problem of configuring networking is better solved by DHCP
or by obtaining static config via
config drive. Therefore this operation is considered optional
to support.
cli=
driver-impl-ibm-dpm=missing
driver-notes-ibm-dpm=Only DHCP is supported.
[console.rdp]
title=Remote desktop over RDP
status=choice(console)
notes=This allows the administrator to interact with the graphical
console of the guest OS via RDP. This provides a way to see boot
up messages and login to the instance when networking configuration
has failed, thus preventing a network based login. Some operating
systems may prefer to emit messages via the serial console for
easier consumption. Therefore support for this operation is not
mandatory, however, a driver is required to support at least one
of the listed console access operations.
cli=nova get-rdp-console <server> <console-type>
driver-impl-ibm-dpm=missing
[console.serial.log]
title=View serial console logs
status=choice(console)
notes=This allows the administrator to query the logs of data
emitted by the guest OS on its virtualized serial port. For
UNIX guests this typically includes all boot up messages and
so is useful for diagnosing problems when an instance fails
to successfully boot. Not all guest operating systems will be
able to emit boot information on a serial console, others may
only support graphical consoles. Therefore support for this
operation is not mandatory, however, a driver is required to
support at least one of the listed console access operations.
cli=
driver-impl-ibm-dpm=missing
[console.serial.interactive]
title=Remote interactive serial console
status=choice(console)
notes=This allows the administrator to interact with the serial
console of the guest OS. This provides a way to see boot
up messages and login to the instance when networking configuration
has failed, thus preventing a network based login. Not all guest
operating systems will be able to emit boot information on a serial
console, others may only support graphical consoles. Therefore support
for this operation is not mandatory, however, a driver is required to
support at least one of the listed console access operations.
This feature was introduced in the Juno release with blueprint
https://blueprints.launchpad.net/nova/+spec/serial-ports
cli=nova get-serial-console <server>
driver-impl-ibm-dpm=missing
[console.spice]
title=Remote desktop over SPICE
status=choice(console)
notes=This allows the administrator to interact with the graphical
console of the guest OS via SPICE. This provides a way to see boot
up messages and login to the instance when networking configuration
has failed, thus preventing a network based login. Some operating
systems may prefer to emit messages via the serial console for
easier consumption. Therefore support for this operation is not
mandatory, however, a driver is required to support at least one
of the listed console access operations.
cli=nova get-spice-console <server> <console-type>
driver-impl-ibm-dpm=missing
[console.vnc]
title=Remote desktop over VNC
status=choice(console)
notes=This allows the administrator to interact with the graphical
console of the guest OS via VNC. This provides a way to see boot
up messages and login to the instance when networking configuration
has failed, thus preventing a network based login. Some operating
systems may prefer to emit messages via the serial console for
easier consumption. Therefore support for this operation is not
mandatory, however, a driver is required to support at least one
of the listed console access operations.
cli=nova get-vnc-console <server> <console-type>
driver-impl-ibm-dpm=missing
[storage.block]
title=Block storage support
status=optional
notes=Block storage provides instances with direct attached
virtual disks that can be used for persistent storage of data.
As an alternative to direct attached disks, an instance may
choose to use network based persistent storage. OpenStack provides
object storage via the Swift service, or a traditional filesystem
such as NFS/GlusterFS may be used. Some types of instances may
not require persistent storage at all, being simple transaction
processing systems reading requests & sending results to and from
the network. Therefore support for this configuration is not
considered mandatory for drivers to support.
cli=
driver-impl-ibm-dpm=complete
[storage.block.backend.fibrechannel]
title=Block storage over fibre channel
status=optional
notes=To maximise performance of the block storage, it may be desirable
to directly access fibre channel LUNs from the underlying storage
technology on the compute hosts. Since this is just a performance
optimization of the I/O path it is not considered mandatory to support.
cli=
driver-impl-ibm-dpm=complete
[storage.block.backend.iscsi]
title=Block storage over iSCSI
status=condition(storage.block==missing)
notes=If the driver wishes to support block storage, it is common to
provide an iSCSI based backend to access the storage from cinder.
This isolates the compute layer for knowledge of the specific storage
technology used by Cinder, albeit at a potential performance cost due
to the longer I/O path involved. If the driver chooses to support
block storage, then this is considered mandatory to support, otherwise
it is considered optional.
cli=
driver-impl-ibm-dpm=missing
[storage.block.backend.iscsi.auth.chap]
title=CHAP authentication for iSCSI
status=optional
notes=If accessing the cinder iSCSI service over an untrusted LAN it
is desirable to be able to enable authentication for the iSCSI
protocol. CHAP is the commonly used authentication protocol for
iSCSI. This is not considered mandatory to support. (?)
cli=
driver-impl-ibm-dpm=missing
[storage.image]
title=Image storage support
status=mandatory
notes=This refers to the ability to boot an instance from an image
stored in the glance image repository. Without this feature it
would not be possible to bootstrap from a clean environment, since
there would be no way to get block volumes populated and reliance
on external PXE servers is out of scope. Therefore this is considered
a mandatory storage feature to support.
cli=nova boot --image <image> <name>
driver-impl-ibm-dpm=partial
driver-notes-ibm-dpm=The image needs to be deployed into a volume first.
As the system z DPM machine doesn't provide local storage, booting from
image, which gets downloaded to local storage first, is not supported.
[networking.firewallrules]
title=Network firewall rules
status=optional
notes=Unclear how this is different from security groups
cli=
driver-impl-ibm-dpm=missing
[networking.routing]
title=Network routing
status=optional
notes=Unclear what this refers to
cli=
driver-impl-ibm-dpm=missing
[networking.securitygroups]
title=Network security groups
status=optional
notes=The security groups feature provides a way to define rules
to isolate the network traffic of different instances running
on a compute host. This would prevent actions such as MAC and
IP address spoofing, or the ability to setup rogue DHCP servers.
In a private cloud environment this may be considered to be a
superfluous requirement. Therefore this is considered to be an
optional configuration to support.
cli=
driver-impl-ibm-dpm=missing
[networking.topology.flat]
title=Flat networking
status=choice(networking.topology)
notes=Provide network connectivity to guests using a
flat topology across all compute nodes. At least one
of the networking configurations is mandatory to
support in the drivers.
cli=
driver-impl-ibm-dpm=complete
[networking.topology.vlan]
title=VLAN networking
status=choice(networking.topology)
notes=Provide network connectivity to guests using VLANs
to define the topology. At least one of the networking
configurations is mandatory to support in the drivers.
cli=
driver-impl-ibm-dpm=missing
driver-notes-ibm-dpm=A config driver, which is not yet supported, is
a prerequisite for that.
[operation.uefi-boot]
title=uefi boot
status=optional
notes=This allows users to boot a guest with uefi firmware.
cli=
driver-impl-ibm-dpm=missing

41
doc/source/support-matrix.rst Normal file
View File

@ -0,0 +1,41 @@
Feature Support Matrix
======================
.. warning::
Please note, while this document is still being maintained, this is slowly
being updated to re-group and classify features.
When considering which capabilities should be marked as mandatory the
following general guiding principles were applied
* **Inclusivity** - people have shown ability to make effective
use of a wide range of virtualization technologies with broadly
varying featuresets. Aiming to keep the requirements as inclusive
as possible, avoids second-guessing what a user may wish to use
the cloud compute service for.
* **Bootstrapping** - a practical use case test is to consider that
starting point for the compute deploy is an empty data center
with new machines and network connectivity. The look at what
are the minimum features required of a compute service, in order
to get user instances running and processing work over the
network.
* **Competition** - an early leader in the cloud compute service space
was Amazon EC2. A sanity check for whether a feature should be
mandatory is to consider whether it was available in the first
public release of EC2. This had quite a narrow featureset, but
none the less found very high usage in many use cases. So it
serves to illustrate that many features need not be considered
mandatory in order to get useful work done.
* **Reality** - there are many virt drivers currently shipped with
Nova, each with their own supported feature set. Any feature which is
missing in at least one virt driver that is already in-tree, must
by inference be considered optional until all in-tree drivers
support it. This does not rule out the possibility of a currently
optional feature becoming mandatory at a later date, based on other
principles above.
.. support_matrix:: support-matrix.ini