Add descriptions to all openstack resources (Part 1)

Add description of resources in openstack folder
of heat engine. It should help users to understand
which resource is need to.

Resources' services updated in this patch:
 * barbican
 * ceilometer
 * cinder
 * designate
 * glance
 * heat (partial)
 * keystone
 * magnum
 * mistral
 * monasca
 * neutron (one resource)

implements bp docstring-improvements

Change-Id: I68813427ef8944cc7b05f1d8dcf12190d3ca45d1
This commit is contained in:
Peter Razumovsky 2015-10-12 13:02:04 +03:00
parent 7ae4b3212d
commit 6294168760
26 changed files with 169 additions and 13 deletions

View File

@ -21,6 +21,13 @@ from heat.engine import support
class Order(resource.Resource):
"""A resource allowing for the generation secret material by Barbican.
The resource allows to generate some secret material. It can be, for
example, some key or certificate. The order encapsulates the workflow
and history for the creation of a secret. The time to generate a secret can
vary depending on the type of secret.
"""
support_status = support.SupportStatus(version='2014.2')

View File

@ -20,6 +20,13 @@ from heat.engine import support
class Secret(resource.Resource):
"""The resource provides access to the secret/keying stored material.
A secret is a singular item that stored within Barbican. A secret is
anything you want it to be; however, the formal use case is a key that you
wish to store away from prying eyes. Secret may include private keys,
passwords and so on.
"""
support_status = support.SupportStatus(version='2014.2')

View File

@ -182,6 +182,15 @@ def actions_to_urls(stack, properties):
class CeilometerAlarm(resource.Resource):
"""A resource that implements alarming service of Ceilometer.
A resource that allows for the setting alarms based on threshold evaluation
for a collection of samples. Also, you can define actions to take if state
of watched resource will be satisfied specified conditions. For example, it
can watch for the memory consumption and when it reaches 70% on a given
instance if the instance has been up for more than 10 min, some action will
be called.
"""
PROPERTIES = (
COMPARISON_OPERATOR, EVALUATION_PERIODS, METER_NAME, PERIOD,
@ -425,6 +434,12 @@ class BaseCeilometerAlarm(resource.Resource):
class CombinationAlarm(BaseCeilometerAlarm):
"""A resource that implements combination of Ceilometer alarms.
Allows to use alarm as a combination of other alarms with some operator:
activate this alarm if any alarm in combination has been activated or
if all alarms in combination have been activated.
"""
support_status = support.SupportStatus(version='2014.1')

View File

@ -67,6 +67,11 @@ common_gnocchi_properties_schema = {
class CeilometerGnocchiResourcesAlarm(alarm.BaseCeilometerAlarm):
"""A resource allowing for the watch of some specified resource.
An alarm that evaluates threshold based on some metric for the
specified resource.
"""
support_status = support.SupportStatus(version='2015.1')
@ -105,6 +110,11 @@ class CeilometerGnocchiResourcesAlarm(alarm.BaseCeilometerAlarm):
class CeilometerGnocchiAggregationByMetricsAlarm(
CeilometerGnocchiResourcesAlarm):
"""A resource that implements alarm with specified metrics.
A resource that implements alarm which allows to use specified by user
metrics in metrics list.
"""
support_status = support.SupportStatus(version='2015.1')
@ -127,6 +137,12 @@ class CeilometerGnocchiAggregationByMetricsAlarm(
class CeilometerGnocchiAggregationByResourcesAlarm(
CeilometerGnocchiResourcesAlarm):
"""A resource that implements alarm as an aggregation of resources alarms.
A resource that implements alarm which uses aggregation of resources alarms
with some condition. If state of a system is satisfied alarm condition,
alarm is activated.
"""
support_status = support.SupportStatus(version='2015.1')

View File

@ -21,6 +21,9 @@ from heat.engine import support
class CinderEncryptedVolumeType(resource.Resource):
"""A resource for encrypting a cinder volume type.
A Volume Encryption Type is a collection of settings used to conduct
encryption for a specific volume type.
Note that default cinder security policy usage of this resource
is limited to being used by administrators only.
"""

View File

@ -30,6 +30,12 @@ LOG = logging.getLogger(__name__)
class CinderVolume(vb.BaseVolume, sh.SchedulerHintsMixin):
"""A resource that implements Cinder volumes.
Cinder volume is a storage in the form of block devices. It can be used,
for example, for providing storage to instance. Volume supports creation
from snapshot, backup or image. Also volume can be created only by size.
"""
PROPERTIES = (
AVAILABILITY_ZONE, SIZE, SNAPSHOT_ID, BACKUP_ID, NAME,

View File

@ -22,6 +22,10 @@ from heat.engine import support
class CinderVolumeType(resource.Resource):
"""A resource for creating cinder volume types.
Volume type resource allows to define, whether volume, which will be use
this type, will public and which projects are allowed to work with it.
Also, there can be some user-defined metadata.
Note that default cinder security policy usage of this resource
is limited to being used by administrators only.
"""

View File

@ -21,7 +21,11 @@ from heat.engine import support
class DesignateDomain(resource.Resource):
"""Heat Template Resource for Designate Domain."""
"""Heat Template Resource for Designate Domain.
Designate provides DNS-as-a-Service services for OpenStack. So, domain
is an realm with an identification string, unique in DNS.
"""
support_status = support.SupportStatus(
version='5.0.0')

View File

@ -21,7 +21,12 @@ from heat.engine import support
class DesignateRecord(resource.Resource):
"""Heat Template Resource for Designate Record."""
"""Heat Template Resource for Designate Record.
Designate provides DNS-as-a-Service services for OpenStack. Record is
storage unit in DNS. So, DNS name server is a server that stores the DNS
records for a domain. Each record has a type and type-specific data.
"""
support_status = support.SupportStatus(
version='5.0.0')

View File

@ -19,7 +19,11 @@ from heat.engine import support
class GlanceImage(resource.Resource):
"""A resource managing images in Glance."""
"""A resource managing images in Glance.
A resource provides managing images that are meant to be used with other
services.
"""
support_status = support.SupportStatus(version='2014.2')

View File

@ -23,7 +23,14 @@ from heat.engine import template
class AutoScalingResourceGroup(aws_asg.AutoScalingGroup):
"""An autoscaling group that can scale arbitrary resources."""
"""An autoscaling group that can scale arbitrary resources.
A resource allows to create desired count of similar resources, which
defined with resource property in HOT format. If there's necessity of
creating many of the same resources (e.g. one hundred sets of Server,
WaitCondition and WaitConditionHandle or even Neutron Nets),
AutoScalingGroup is the most convenient and easy way to do that.
"""
PROPERTIES = (
RESOURCE, MAX_SIZE, MIN_SIZE, COOLDOWN, DESIRED_CAPACITY,

View File

@ -32,6 +32,12 @@ from heat.scaling import template
class InstanceGroup(stack_resource.StackResource):
"""An instance group that can scale arbitrary instances.
A resource allowing for the creating number of defined with
AWS::AutoScaling::LaunchConfiguration instances. Allows to associate
scaled resources with loadbalancer resources.
"""
PROPERTIES = (
AVAILABILITY_ZONES, LAUNCH_CONFIGURATION_NAME, SIZE,

View File

@ -28,7 +28,13 @@ from heat.engine import support
class RandomString(resource.Resource):
"""A resource which generates a random string.
This is useful for configuring passwords and secrets on services.
This is useful for configuring passwords and secrets on services. Random
string can be generated from specified character sequences, which means
that all characters will be randomly chosen from specified sequences, or
with some classes, e.g. letterdigits, which means that all character will
be randomly chosen from union of ascii letters and digits. Output string
will be randomly generated string with specified length (or with length of
32, if length property doesn't specified).
"""
support_status = support.SupportStatus(version='2014.1')

View File

@ -33,7 +33,10 @@ LOG = logging.getLogger(__name__)
class RemoteStack(resource.Resource):
"""A Resource representing a stack.
Stack can be created using specified context.
A resource that allowing for the creating stack, where should be defined
stack template in HOT format, parameters (if template has any parameters
with no default value), and timeout of creating. After creating current
stack will have remote stack.
"""
default_client_name = 'heat'

View File

@ -19,7 +19,12 @@ from heat.engine import support
class KeystoneEndpoint(resource.Resource):
"""Heat Template Resource for Keystone Service Endpoint."""
"""Heat Template Resource for Keystone Service Endpoint.
Keystone endpoint is just the URL that can be used for accessing a service
within OpenStack. Endpoint can be accessed by admin, by services or public,
i.e. everyone can use this endpoint.
"""
support_status = support.SupportStatus(
version='5.0.0',

View File

@ -21,7 +21,12 @@ from heat.engine import support
class KeystoneGroup(resource.Resource,
role_assignments.KeystoneRoleAssignmentMixin):
"""Heat Template Resource for Keystone Group."""
"""Heat Template Resource for Keystone Group.
Groups are a container representing a collection of users. A group itself
must be owned by a specific domain, and hence all group names are not
globally unique, but only unique to their domain.
"""
support_status = support.SupportStatus(
version='2015.1',

View File

@ -19,7 +19,14 @@ from heat.engine import support
class KeystoneProject(resource.Resource):
"""Heat Template Resource for Keystone Project."""
"""Heat Template Resource for Keystone Project.
Projects represent the base unit of ownership in OpenStack, in that all
resources in OpenStack should be owned by a specific project. A project
itself must be owned by a specific domain, and hence all project names are
not globally unique, but unique to their domain. If the domain for a
project is not specified, then it is added to the default domain.
"""
support_status = support.SupportStatus(
version='2015.1',

View File

@ -18,7 +18,12 @@ from heat.engine import support
class KeystoneRole(resource.Resource):
"""Heat Template Resource for Keystone Role."""
"""Heat Template Resource for Keystone Role.
Roles dictate the level of authorization the end user can obtain. Roles can
be granted at either the domain or project level. Role can be assigned to
the individual user or at the group level. Role names are globally unique.
"""
support_status = support.SupportStatus(
version='2015.1',

View File

@ -18,7 +18,10 @@ from heat.engine import support
class KeystoneService(resource.Resource):
"""Heat Template Resource for Keystone Service."""
"""Heat Template Resource for Keystone Service.
A resource that allows to create new service and manage it by Keystone.
"""
support_status = support.SupportStatus(
version='5.0.0',

View File

@ -21,7 +21,12 @@ from heat.engine import support
class KeystoneUser(resource.Resource,
role_assignments.KeystoneRoleAssignmentMixin):
"""Heat Template Resource for Keystone User."""
"""Heat Template Resource for Keystone User.
Users represent an individual API consumer. A user itself must be owned by
a specific domain, and hence all user names are not globally unique, but
only unique to their domain.
"""
support_status = support.SupportStatus(
version='2015.1',

View File

@ -19,7 +19,11 @@ from heat.engine import support
class BayModel(resource.Resource):
"""A resource for the BayModel in Magnum."""
"""A resource for the BayModel in Magnum.
BayModel is an object that stores template information about the bay which
is used to create new bays consistently.
"""
support_status = support.SupportStatus(version='5.0.0')

View File

@ -20,6 +20,14 @@ from heat.engine import support
class CronTrigger(resource.Resource):
"""A resource implements Mistral cron trigger.
Cron trigger is an object allowing to run workflow on a schedule. User
specifies what workflow with what input needs to be run and also specifies
how often it should be run. Pattern property is used to describe the
frequency of workflow execution.
"""
support_status = support.SupportStatus(version='5.0.0')
PROPERTIES = (

View File

@ -27,6 +27,15 @@ from heat.engine import support
class Workflow(signal_responder.SignalResponder,
resource.Resource):
"""A resource that implements Mistral workflow.
Workflow represents a process that can be described in a various number of
ways and that can do some job interesting to the end user. Each workflow
consists of tasks (at least one) describing what exact steps should be made
during workflow execution.
For detailed description how to use Workflow, read Mistral documentation.
"""
support_status = support.SupportStatus(version='2015.1')

View File

@ -24,6 +24,11 @@ class MonascaAlarmDefinition(resource.Resource):
This plug-in requires python-monascaclient>=1.0.22. So to enable this
plug-in, install this client library and restart the heat-engine.
Alarm definitions is necessary to describe and manage alarms in a
one-to-many relationship in order to avoid having to manually declare each
alarm even though they may share many common attributes and differ in only
one, such as hostname.
"""
support_status = support.SupportStatus(

View File

@ -24,6 +24,8 @@ class MonascaNotification(resource.Resource):
This plug-in requires python-monascaclient>=1.0.22. So to enable this
plug-in, install this client library and restart the heat-engine.
A resource which is used to notificate if there is some alarm.
"""
support_status = support.SupportStatus(

View File

@ -24,6 +24,11 @@ from heat.engine import support
class Router(neutron.NeutronResource):
"""A resource that implements Neutron router.
Router is a physical or virtual network device that passes network traffic
between different networks.
"""
required_service_extension = 'router'