From 9d019ba777e5cead8e1427ca32f0e276d33a22de Mon Sep 17 00:00:00 2001 From: Peter Razumovsky Date: Wed, 10 Feb 2016 20:19:26 +0300 Subject: [PATCH] Add descriptions to openstack resources (Part 3) 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: * heat * neutron implements bp docstring-improvements Change-Id: I069c7889d3b4067602ee10c026625733c16a9ad2 --- .../resources/openstack/heat/access_policy.py | 13 +++++--- .../openstack/heat/resource_chain.py | 11 ------- .../openstack/heat/scaling_policy.py | 3 ++ .../resources/openstack/heat/swiftsignal.py | 10 ++++++ .../openstack/heat/wait_condition.py | 8 +++++ .../openstack/heat/wait_condition_handle.py | 7 ++++ .../resources/openstack/neutron/firewall.py | 20 +++++++++-- .../resources/openstack/neutron/floatingip.py | 14 ++++++++ .../openstack/neutron/loadbalancer.py | 33 ++++++++++++++++--- .../resources/openstack/neutron/metering.py | 17 ++++++++-- .../engine/resources/openstack/neutron/net.py | 6 ++++ .../openstack/neutron/network_gateway.py | 5 ++- .../resources/openstack/neutron/port.py | 9 +++++ .../openstack/neutron/provider_net.py | 11 +++++-- .../resources/openstack/neutron/router.py | 4 +++ .../openstack/neutron/security_group.py | 8 +++++ .../resources/openstack/neutron/subnet.py | 7 ++++ .../resources/openstack/neutron/vpnservice.py | 25 +++++++++++--- 18 files changed, 178 insertions(+), 33 deletions(-) diff --git a/heat/engine/resources/openstack/heat/access_policy.py b/heat/engine/resources/openstack/heat/access_policy.py index 0298236bde..5201c05e5b 100644 --- a/heat/engine/resources/openstack/heat/access_policy.py +++ b/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, ) = ( diff --git a/heat/engine/resources/openstack/heat/resource_chain.py b/heat/engine/resources/openstack/heat/resource_chain.py index 07639e7cfd..13b4ccfbd1 100644 --- a/heat/engine/resources/openstack/heat/resource_chain.py +++ b/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: # resource types to add to the chain's stack - concurrent: # optional; default is false - resource_properties: - # properties to pass each template in the chain """ support_status = support.SupportStatus(version='6.0.0') diff --git a/heat/engine/resources/openstack/heat/scaling_policy.py b/heat/engine/resources/openstack/heat/scaling_policy.py index 9a45b7af2d..bb9f2c50ff 100644 --- a/heat/engine/resources/openstack/heat/scaling_policy.py +++ b/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, diff --git a/heat/engine/resources/openstack/heat/swiftsignal.py b/heat/engine/resources/openstack/heat/swiftsignal.py index 39001bdb91..69c358bc83 100644 --- a/heat/engine/resources/openstack/heat/swiftsignal.py +++ b/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" diff --git a/heat/engine/resources/openstack/heat/wait_condition.py b/heat/engine/resources/openstack/heat/wait_condition.py index 6287795db6..3fb1dc1d3e 100644 --- a/heat/engine/resources/openstack/heat/wait_condition.py +++ b/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') diff --git a/heat/engine/resources/openstack/heat/wait_condition_handle.py b/heat/engine/resources/openstack/heat/wait_condition_handle.py index e6c2d94f19..556156b544 100644 --- a/heat/engine/resources/openstack/heat/wait_condition_handle.py +++ b/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') diff --git a/heat/engine/resources/openstack/neutron/firewall.py b/heat/engine/resources/openstack/neutron/firewall.py index 22f8ee0b96..c5d730426e 100644 --- a/heat/engine/resources/openstack/neutron/firewall.py +++ b/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' diff --git a/heat/engine/resources/openstack/neutron/floatingip.py b/heat/engine/resources/openstack/neutron/floatingip.py index 035315f622..9e6d5f51fe 100644 --- a/heat/engine/resources/openstack/neutron/floatingip.py +++ b/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, @@ -253,6 +262,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, ) = ( diff --git a/heat/engine/resources/openstack/neutron/loadbalancer.py b/heat/engine/resources/openstack/neutron/loadbalancer.py index 109129732c..b2cb65096a 100644 --- a/heat/engine/resources/openstack/neutron/loadbalancer.py +++ b/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' diff --git a/heat/engine/resources/openstack/neutron/metering.py b/heat/engine/resources/openstack/neutron/metering.py index 39e3381ccd..c9c78ce317 100644 --- a/heat/engine/resources/openstack/neutron/metering.py +++ b/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') diff --git a/heat/engine/resources/openstack/neutron/net.py b/heat/engine/resources/openstack/neutron/net.py index f4ea809339..0c0703e696 100644 --- a/heat/engine/resources/openstack/neutron/net.py +++ b/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, diff --git a/heat/engine/resources/openstack/neutron/network_gateway.py b/heat/engine/resources/openstack/neutron/network_gateway.py index 876bb89bc2..2a54e6ff96 100644 --- a/heat/engine/resources/openstack/neutron/network_gateway.py +++ b/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') diff --git a/heat/engine/resources/openstack/neutron/port.py b/heat/engine/resources/openstack/neutron/port.py index 411cdb4687..3f09f88316 100644 --- a/heat/engine/resources/openstack/neutron/port.py +++ b/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, diff --git a/heat/engine/resources/openstack/neutron/provider_net.py b/heat/engine/resources/openstack/neutron/provider_net.py index 780206b75a..a9753e13a9 100644 --- a/heat/engine/resources/openstack/neutron/provider_net.py +++ b/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], diff --git a/heat/engine/resources/openstack/neutron/router.py b/heat/engine/resources/openstack/neutron/router.py index b6966c8ab4..eedcce967a 100644 --- a/heat/engine/resources/openstack/neutron/router.py +++ b/heat/engine/resources/openstack/neutron/router.py @@ -290,6 +290,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' diff --git a/heat/engine/resources/openstack/neutron/security_group.py b/heat/engine/resources/openstack/neutron/security_group.py index bc83eb31bd..9d73565327 100644 --- a/heat/engine/resources/openstack/neutron/security_group.py +++ b/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' diff --git a/heat/engine/resources/openstack/neutron/subnet.py b/heat/engine/resources/openstack/neutron/subnet.py index b88917b246..35d9e87c02 100644 --- a/heat/engine/resources/openstack/neutron/subnet.py +++ b/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, diff --git a/heat/engine/resources/openstack/neutron/vpnservice.py b/heat/engine/resources/openstack/neutron/vpnservice.py index 9ae786636a..0016de8789 100644 --- a/heat/engine/resources/openstack/neutron/vpnservice.py +++ b/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'