Merge "Add descriptions to openstack resources (Part 3)"

heat/engine/resources/openstack/heat/access_policy.py

@@ -16,13 +16,16 @@ from heat.common.i18n import _
 from heat.engine import properties
 from heat.engine import resource
 
-#
-# Notes: Now this resource is actually associated with an AWS user resource,
-# not any OS:: resource though it is registered under the OS namespace below
-#
-
 
 class AccessPolicy(resource.Resource):
+    """Resource for defining which resources can be accessed by users.
+
+    NOTE: Now this resource is actually associated with an AWS user resource,
+    not any OS:: resource though it is registered under the OS namespace below.
+
+    Resource for defining resources that users are allowed to access by the
+    DescribeStackResource API.
+    """
     PROPERTIES = (
         ALLOWED_RESOURCES,
     ) = (

heat/engine/resources/openstack/heat/resource_chain.py

@@ -35,17 +35,6 @@ class ResourceChain(stack_resource.StackResource):
     The ``concurrent`` property controls if the resources will be created
     concurrently. If omitted or set to false, each resource will be treated
     as having a dependency on the resource before it in the list.
-
-    Example::
-
-      resources:
-        MyChainResource:
-          type: OS::Heat::ResourceChain
-          properties:
-            resources: <list> # resource types to add to the chain's stack
-            concurrent: <boolean>  # optional; default is false
-            resource_properties:
-              # properties to pass each template in the chain
     """
 
     support_status = support.SupportStatus(version='6.0.0')

heat/engine/resources/openstack/heat/scaling_policy.py

@@ -36,6 +36,9 @@ class AutoScalingPolicy(signal_responder.SignalResponder,
     **Note** while it may incidentally support
     `AWS::AutoScaling::AutoScalingGroup` for now, please don't use it for that
     purpose and use `AWS::AutoScaling::ScalingPolicy` instead.
+
+    Resource to manage scaling for `OS::Heat::AutoScalingGroup`, i.e. define
+    which metric should be scaled and scaling adjustment, set cooldown etc.
     """
     PROPERTIES = (
         AUTO_SCALING_GROUP_NAME, SCALING_ADJUSTMENT, ADJUSTMENT_TYPE,

heat/engine/resources/openstack/heat/swiftsignal.py

@@ -50,6 +50,11 @@ class SwiftSignalTimeout(exception.Error):
 
 
 class SwiftSignalHandle(resource.Resource):
+    """Resource for managing signals from Swift resources.
+
+    This resource is same as WaitConditionHandle, but designed for using by
+    Swift resources.
+    """
 
     support_status = support.SupportStatus(version='2014.2')
     default_client_name = "swift"
@@ -137,6 +142,11 @@ class SwiftSignalHandle(resource.Resource):
 
 
 class SwiftSignal(resource.Resource):
+    """Resource for handling signals received by SwiftSignalHandle.
+
+    This resource handles signals received by SwiftSignalHandle and
+    is same as WaitCondition resource.
+    """
 
     support_status = support.SupportStatus(version='2014.2')
     default_client_name = "swift"

heat/engine/resources/openstack/heat/wait_condition.py

@@ -29,6 +29,14 @@ LOG = logging.getLogger(__name__)
 
 
 class HeatWaitCondition(resource.Resource):
+    """Resource for handling signals received by WaitConditionHandle.
+
+    Resource takes WaitConditionHandle and starts to create. Resource is in
+    CREATE_IN_PROGRESS status until WaitConditionHandle doesn't receive
+    sufficient number of successful signals (this number can be specified with
+    count property) and successfully creates after that, or fails due to
+    timeout.
+    """
 
     support_status = support.SupportStatus(version='2014.2')
 

heat/engine/resources/openstack/heat/wait_condition_handle.py

@@ -27,6 +27,13 @@ from heat.engine import support
 
 
 class HeatWaitConditionHandle(wc_base.BaseWaitConditionHandle):
+    """Resource for managing instance signals.
+
+    The main points of this resource are:
+      - have no dependencies (so the instance can reference it).
+      - create credentials to allow for signalling from the instance.
+      - handle signals from the instance, validate and store result.
+    """
 
     support_status = support.SupportStatus(version='2014.2')
 

heat/engine/resources/openstack/neutron/firewall.py

@@ -20,7 +20,12 @@ from heat.engine import support
 
 
 class Firewall(neutron.NeutronResource):
-    """A resource for the Firewall resource in Neutron FWaaS."""
+    """A resource for the Firewall resource in Neutron FWaaS.
+
+    Resource for using the Neutron firewall implementation. Firewall is a
+    network security system that monitors and controls the incoming and
+    outgoing network traffic based on predetermined security rules.
+    """
 
     required_service_extension = 'fwaas'
 
@@ -144,7 +149,11 @@ class Firewall(neutron.NeutronResource):
 
 
 class FirewallPolicy(neutron.NeutronResource):
-    """A resource for the FirewallPolicy resource in Neutron FWaaS."""
+    """A resource for the FirewallPolicy resource in Neutron FWaaS.
+
+    FirewallPolicy resource is an ordered collection of firewall rules. A
+    firewall policy can be shared across tenants.
+    """
 
     required_service_extension = 'fwaas'
 
@@ -251,7 +260,12 @@ class FirewallPolicy(neutron.NeutronResource):
 
 
 class FirewallRule(neutron.NeutronResource):
-    """A resource for the FirewallRule resource in Neutron FWaaS."""
+    """A resource for the FirewallRule resource in Neutron FWaaS.
+
+    FirewallRule represents a collection of attributes like ports,
+    ip addresses etc. which define match criteria and action (allow, or deny)
+    that needs to be taken on the matched data traffic.
+    """
 
     required_service_extension = 'fwaas'
 

heat/engine/resources/openstack/neutron/floatingip.py

@@ -25,6 +25,15 @@ from heat.engine import translation
 
 
 class FloatingIP(neutron.NeutronResource):
+    """A resource for managing Neutron floating ips.
+
+    Floating IP addresses can change their association between routers by
+    action of the user.  One of the most common use cases for floating IPs is
+    to provide public IP addresses to a private cloud, where there are a
+    limited number of IP addresses available. Another is for a public cloud
+    user to have a "static" IP address that can be reassigned when an instance
+    is upgraded or moved.
+    """
     PROPERTIES = (
         FLOATING_NETWORK_ID, FLOATING_NETWORK, VALUE_SPECS,
         PORT_ID, FIXED_IP_ADDRESS, FLOATING_IP_ADDRESS,
@@ -246,6 +255,11 @@ class FloatingIP(neutron.NeutronResource):
 
 
 class FloatingIPAssociation(neutron.NeutronResource):
+    """A resource for associating floating ips and ports.
+
+    This resource allows associating a floating IP to a port with at least one
+    IP address to associate with this floating IP.
+    """
     PROPERTIES = (
         FLOATINGIP_ID, PORT_ID, FIXED_IP_ADDRESS,
     ) = (

heat/engine/resources/openstack/neutron/loadbalancer.py

@@ -26,7 +26,18 @@ from heat.engine import translation
 
 
 class HealthMonitor(neutron.NeutronResource):
-    """A resource for managing health monitors for loadbalancers in Neutron."""
+    """A resource for managing health monitors for loadbalancers in Neutron.
+
+    A health monitor is used to determine whether or not back-end members of
+    the VIP's pool are usable for processing a request. A pool can have several
+    health monitors associated with it. There are different types of health
+    monitors supported by the OpenStack LBaaS service:
+
+      - PING: used to ping the members using ICMP.
+      - TCP: used to connect to the members using TCP.
+      - HTTP: used to send an HTTP request to the member.
+      - HTTPS: used to send a secure HTTP request to the member.
+    """
 
     required_service_extension = 'lbaas'
 
@@ -174,7 +185,14 @@ class HealthMonitor(neutron.NeutronResource):
 
 
 class Pool(neutron.NeutronResource):
-    """A resource for managing load balancer pools in Neutron."""
+    """A resource for managing load balancer pools in Neutron.
+
+    A load balancing pool is a logical set of devices, such as web servers,
+    that you group together to receive and process traffic. The loadbalancing
+    function chooses a member of the pool according to the configured load
+    balancing method to handle the new requests or connections received on the
+    VIP address. There is only one pool for a VIP.
+    """
 
     required_service_extension = 'lbaas'
 
@@ -554,7 +572,10 @@ class Pool(neutron.NeutronResource):
 
 
 class PoolMember(neutron.NeutronResource):
-    """A resource to handle loadbalancer members."""
+    """A resource to handle loadbalancer members.
+
+    A pool member represents the application running on backend server.
+    """
 
     required_service_extension = 'lbaas'
 
@@ -679,7 +700,11 @@ class PoolMember(neutron.NeutronResource):
 
 
 class LoadBalancer(resource.Resource):
-    """A resource to link a neutron pool with servers."""
+    """A resource to link a neutron pool with servers.
+
+    A loadbalancer allows linking a neutron pool with specified servers to some
+    port.
+    """
 
     required_service_extension = 'lbaas'
 

heat/engine/resources/openstack/neutron/metering.py

@@ -20,7 +20,16 @@ from heat.engine import support
 
 
 class MeteringLabel(neutron.NeutronResource):
-    """A resource for creating neutron metering label."""
+    """A resource for creating neutron metering label.
+
+    The idea is to meter this at the L3 routers levels. The point is to allow
+    operators to configure IP ranges and to assign a label to them. For example
+    we will be able to set two labels; one for the internal traffic, and the
+    other one for the external traffic. Each label will measure the traffic for
+    a specific set of IP range. Then, bandwidth measurement will be sent for
+    each label to the Oslo notification system and could be collected by
+    Ceilometer.
+    """
 
     support_status = support.SupportStatus(version='2014.1')
 
@@ -93,7 +102,11 @@ class MeteringLabel(neutron.NeutronResource):
 
 
 class MeteringRule(neutron.NeutronResource):
-    """A resource to create rule for some label."""
+    """A resource to create rule for some label.
+
+    Resource for allowing specified label to measure the traffic for a specific
+    set of ip range.
+    """
 
     support_status = support.SupportStatus(version='2014.1')
 

heat/engine/resources/openstack/neutron/net.py

@@ -20,6 +20,12 @@ from heat.engine import support
 
 
 class Net(neutron.NeutronResource):
+    """A resource for managing Neutron net.
+
+    A network is a virtual isolated layer-2 broadcast domain which is typically
+    reserved to the tenant who created it, unless the network has been
+    explicitly configured to be shared.
+    """
     PROPERTIES = (
         NAME, VALUE_SPECS, ADMIN_STATE_UP, TENANT_ID, SHARED,
         DHCP_AGENT_IDS, PORT_SECURITY_ENABLED, QOS_POLICY,

heat/engine/resources/openstack/neutron/network_gateway.py

@@ -27,7 +27,10 @@ from heat.engine import translation
 
 
 class NetworkGateway(neutron.NeutronResource):
-    """Network Gateway resource in Neutron Network Gateway."""
+    """Network Gateway resource in Neutron Network Gateway.
+
+    Resource for connecting internal networks with specified devices.
+    """
 
     support_status = support.SupportStatus(version='2014.1')
 

heat/engine/resources/openstack/neutron/port.py

@@ -30,6 +30,15 @@ LOG = logging.getLogger(__name__)
 
 
 class Port(neutron.NeutronResource):
+    """A resource for managing Neutron ports.
+
+    A port represents a virtual switch port on a logical network switch.
+    Virtual instances attach their interfaces into ports. The logical port also
+    defines the MAC address and the IP address(es) to be assigned to the
+    interfaces plugged into them. When IP addresses are associated to a port,
+    this also implies the port is associated with a subnet, as the IP address
+    was taken from the allocation pool for a specific subnet.
+    """
 
     PROPERTIES = (
         NAME, NETWORK_ID, NETWORK, FIXED_IPS, SECURITY_GROUPS,

heat/engine/resources/openstack/neutron/provider_net.py

@@ -21,6 +21,11 @@ from heat.engine import support
 
 
 class ProviderNet(net.Net):
+    """A resource for managing Neutron provider networks.
+
+    Provider networks specify details of physical realisation of the existing
+    network.
+    """
 
     required_service_extension = 'provider'
 
@@ -47,7 +52,7 @@ class ProviderNet(net.Net):
         PROVIDER_NETWORK_TYPE: properties.Schema(
             properties.Schema.STRING,
             _('A string specifying the provider network type for the '
-                'network.'),
+              'network.'),
             update_allowed=True,
             required=True,
             constraints=[
@@ -57,14 +62,14 @@ class ProviderNet(net.Net):
         PROVIDER_PHYSICAL_NETWORK: properties.Schema(
             properties.Schema.STRING,
             _('A string specifying physical network mapping for the '
-                'network.'),
+              'network.'),
             update_allowed=True,
             required=True,
         ),
         PROVIDER_SEGMENTATION_ID: properties.Schema(
             properties.Schema.STRING,
             _('A string specifying the segmentation id for the '
-                'network.'),
+              'network.'),
             update_allowed=True
         ),
         ADMIN_STATE_UP: net.Net.properties_schema[ADMIN_STATE_UP],

heat/engine/resources/openstack/neutron/router.py

@@ -282,6 +282,10 @@ class Router(neutron.NeutronResource):
 
 
 class RouterInterface(neutron.NeutronResource):
+    """A resource for managing Neutron router interfaces.
+
+    Router interfaces associate routers with existing subnets or ports.
+    """
 
     required_service_extension = 'router'
 

heat/engine/resources/openstack/neutron/security_group.py

@@ -20,6 +20,14 @@ from heat.engine import support
 
 
 class SecurityGroup(neutron.NeutronResource):
+    """A resource for managing Neutron security groups.
+
+    Security groups are sets of IP filter rules that are applied to an
+    instance's networking. They are project specific, and project members can
+    edit the default rules for their group and add new rules sets. All projects
+    have a "default" security group, which is applied to instances that have no
+    other security group defined.
+    """
 
     required_service_extension = 'security-group'
 

heat/engine/resources/openstack/neutron/subnet.py

@@ -24,6 +24,13 @@ from heat.engine import translation
 
 
 class Subnet(neutron.NeutronResource):
+    """A resource for managing Neutron subnets.
+
+    A subnet represents an IP address block that can be used for assigning IP
+    addresses to virtual instances. Each subnet must have a CIDR and must be
+    associated with a network. IPs can be either selected from the whole subnet
+    CIDR, or from "allocation pools" that can be specified by the user.
+    """
 
     PROPERTIES = (
         NETWORK_ID, NETWORK, SUBNETPOOL, PREFIXLEN, CIDR,

heat/engine/resources/openstack/neutron/vpnservice.py

@@ -21,7 +21,11 @@ from heat.engine import translation
 
 
 class VPNService(neutron.NeutronResource):
-    """A resource for VPN service in Neutron."""
+    """A resource for VPN service in Neutron.
+
+    VPN service is a high level object that associates VPN with a specific
+    subnet and router.
+    """
 
     required_service_extension = 'vpnaas'
 
@@ -187,7 +191,11 @@ class VPNService(neutron.NeutronResource):
 
 
 class IPsecSiteConnection(neutron.NeutronResource):
-    """A resource for IPsec site connection in Neutron."""
+    """A resource for IPsec site connection in Neutron.
+
+    This resource has details for the site-to-site IPsec connection, including
+    the peer CIDRs, MTU, peer address, DPD settings and status.
+    """
 
     required_service_extension = 'vpnaas'
 
@@ -431,7 +439,12 @@ class IPsecSiteConnection(neutron.NeutronResource):
 
 
 class IKEPolicy(neutron.NeutronResource):
-    """A resource for IKE policy in Neutron."""
+    """A resource for IKE policy in Neutron.
+
+    The Internet Key Exchange policy identifyies the authentication and
+    encryption algorithm used during phase one and phase two negotiation of a
+    VPN connection.
+    """
 
     required_service_extension = 'vpnaas'
 
@@ -599,7 +612,11 @@ class IKEPolicy(neutron.NeutronResource):
 
 
 class IPsecPolicy(neutron.NeutronResource):
-    """A resource for IPsec policy in Neutron."""
+    """A resource for IPsec policy in Neutron.
+
+    The IP security policy specifying the authentication and encryption
+    algorithm, and encapsulation mode used for the established VPN connection.
+    """
 
     required_service_extension = 'vpnaas'