Merge "Add API docs for network.v2"

doc/source/users/index.rst

@@ -74,6 +74,7 @@ The following services have exposed *Resource* classes.
 
    Compute <resources/compute/index>
    Database <resources/database/index>
+   Network <resources/network/index>
    Object Store <resources/object_store/index>
 
 Low-Level Classes

doc/source/users/resources/network/index.rst

@@ -0,0 +1,22 @@
+Network Resources
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   v2/extension
+   v2/floatingip
+   v2/health_monitor
+   v2/listener
+   v2/load_balancer
+   v2/metering_label
+   v2/metering_label_rule
+   v2/network
+   v2/pool
+   v2/pool_member
+   v2/port
+   v2/quota
+   v2/router
+   v2/security_group
+   v2/security_group_rule
+   v2/subnet

doc/source/users/resources/network/v2/extension.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.extension
+==============================
+
+.. automodule:: openstack.network.v2.extension
+
+The Extension Class
+-------------------
+
+The ``Extension`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.extension.Extension
+   :members:

doc/source/users/resources/network/v2/floating_ip.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.floating_ip
+================================
+
+.. automodule:: openstack.network.v2.floating_ip
+
+The FloatingIP Class
+--------------------
+
+The ``FloatingIP`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.floating_ip.FloatingIP
+   :members:

doc/source/users/resources/network/v2/health_monitor.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.health_monitor
+===================================
+
+.. automodule:: openstack.network.v2.health_monitor
+
+The HealthMonitor Class
+-----------------------
+
+The ``HealthMonitor`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.health_monitor.HealthMonitor
+   :members:

doc/source/users/resources/network/v2/listener.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.listener
+=============================
+
+.. automodule:: openstack.network.v2.listener
+
+The Listener Class
+------------------
+
+The ``Listener`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.listener.Listener
+   :members:

doc/source/users/resources/network/v2/load_balancer.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.load_balancer
+==================================
+
+.. automodule:: openstack.network.v2.load_balancer
+
+The LoadBalancer Class
+----------------------
+
+The ``LoadBalancer`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.load_balancer.LoadBalancer
+   :members:

doc/source/users/resources/network/v2/metering_label.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.metering_label
+===================================
+
+.. automodule:: openstack.network.v2.metering_label
+
+The MeteringLabel Class
+-----------------------
+
+The ``MeteringLabel`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.metering_label.MeteringLabel
+   :members:

doc/source/users/resources/network/v2/metering_label_rule.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.metering_label_rule
+========================================
+
+.. automodule:: openstack.network.v2.metering_label_rule
+
+The MeteringLabelRule Class
+---------------------------
+
+The ``MeteringLabelRule`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.metering_label_rule.MeteringLabelRule
+   :members:

doc/source/users/resources/network/v2/network.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.network
+============================
+
+.. automodule:: openstack.network.v2.network
+
+The Network Class
+-----------------
+
+The ``Network`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.network.Network
+   :members:

doc/source/users/resources/network/v2/pool.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.pool
+=========================
+
+.. automodule:: openstack.network.v2.pool
+
+The Pool Class
+--------------
+
+The ``Pool`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.pool.Pool
+   :members:

doc/source/users/resources/network/v2/pool_member.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.pool_member
+================================
+
+.. automodule:: openstack.network.v2.pool_member
+
+The PoolMember Class
+--------------------
+
+The ``PoolMember`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.pool_member.PoolMember
+   :members:

doc/source/users/resources/network/v2/port.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.port
+=========================
+
+.. automodule:: openstack.network.v2.port
+
+The Port Class
+--------------
+
+The ``Port`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.port.Port
+   :members:

doc/source/users/resources/network/v2/quota.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.quota
+==========================
+
+.. automodule:: openstack.network.v2.quota
+
+The Quota Class
+---------------
+
+The ``Quota`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.quota.Quota
+   :members:

doc/source/users/resources/network/v2/router.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.router
+===========================
+
+.. automodule:: openstack.network.v2.router
+
+The Router Class
+----------------
+
+The ``Router`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.router.Router
+   :members:

doc/source/users/resources/network/v2/security_group.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.security_group
+===================================
+
+.. automodule:: openstack.network.v2.security_group
+
+The SecurityGroup Class
+-----------------------
+
+The ``SecurityGroup`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.security_group.SecurityGroup
+   :members:

doc/source/users/resources/network/v2/security_group_rule.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.security_group_rule
+========================================
+
+.. automodule:: openstack.network.v2.security_group_rule
+
+The SecurityGroupRule Class
+---------------------------
+
+The ``SecurityGroupRule`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.security_group_rule.SecurityGroupRule
+   :members:

doc/source/users/resources/network/v2/subnet.rst

@@ -0,0 +1,12 @@
+openstack.network.v2.subnet
+===========================
+
+.. automodule:: openstack.network.v2.subnet
+
+The Subnet Class
+----------------
+
+The ``Subnet`` class inherits from :class:`~openstack.resource.Resource`.
+
+.. autoclass:: openstack.network.v2.subnet.Subnet
+   :members:

openstack/network/v2/extension.py

@@ -24,9 +24,15 @@ class Extension(resource.Resource):
     allow_list = True
 
     # Properties
+    #: An alias the extension is known under.
     alias = resource.prop('alias')
+    #: Text describing what the extension does.
     description = resource.prop('description')
+    #: Links pertaining to this extension.
     links = resource.prop('links')
+    #: The name of this extension.
     name = resource.prop('name')
+    #: A URL pointing to the namespace for this extension.
     namespace = resource.prop('namespace')
+    #: Timestamp when the extension was last updated.
     updated = resource.prop('updated')

openstack/network/v2/floating_ip.py

@@ -32,11 +32,22 @@ class FloatingIP(resource.Resource):
     put_update = True
 
     # Properties
+    #: The fixed IP address associated with the floating IP. If you
+    #: intend to associate the floating IP with a fixed IP at creation
+    #: time, then you must indicate the identifier of the internal port.
+    #: If an internal port has multiple associated IP addresses, the
+    #: service chooses the first IP unless you explicitly specify the
+    #: parameter fixed_ip_address to select a specific IP.
     fixed_ip_address = resource.prop('fixed_ip_address')
+    #: The floating IP address.
     floating_ip_address = resource.prop('floating_ip_address')
+    #: The ID of the network associated with the floating IP.
     floating_network_id = resource.prop('floating_network_id')
+    #: The port ID.
     port_id = resource.prop('port_id')
+    #: The project this floating IP is associated with.
     project_id = resource.prop('tenant_id')
+    #: The ID of an associated router.
     router_id = resource.prop('router_id')
 
     @classmethod

openstack/network/v2/health_monitor.py

@@ -29,13 +29,28 @@ class HealthMonitor(resource.Resource):
     put_update = True
 
     # Properties
+    #: The administrative state of the health monitor, which is up
+    #: ``True`` or down ``False``. *Type: bool*
     admin_state_up = resource.prop('admin_state_up', type=bool)
+    #: The time, in seconds, between sending probes to members.
     delay = resource.prop('delay')
+    #: Expected HTTP codes for a passing HTTP(S) monitor.
     expected_codes = resource.prop('expected_codes')
+    #: The HTTP method that the monitor uses for requests.
     http_method = resource.prop('http_method')
+    #: Maximum consecutive health probe tries.
     max_retries = resource.prop('max_retries')
+    #: Owner of the VIP
     project_id = resource.prop('tenant_id')
+    #: The status of the health monitor. Indicates whether the health
+    #: monitor is operational.
     status = resource.prop('status')
+    #: The maximum number of seconds for a monitor to wait for a connection
+    #: to be established before it times out. This value must be less than
+    #: the delay value.
     timeout = resource.prop('timeout')
+    #: The type of probe sent by the load balancer to verify the member
+    #: state, which is PING, TCP, HTTP, or HTTPS.
     type = resource.prop('type')
+    #: Path portion of URI that will be probed if type is HTTP(S).
     url_path = resource.prop('url_path')

openstack/network/v2/listener.py

@@ -29,6 +29,7 @@ class Listener(resource.Resource):
     put_update = True
 
     # Properties
+    # TODO(briancurtin): find documentation for these properties
     connection_limit = resource.prop('connection_limit')
     default_pool_id = resource.prop('default_pool_id')
     description = resource.prop('description')

openstack/network/v2/load_balancer.py

@@ -29,6 +29,7 @@ class LoadBalancer(resource.Resource):
     put_update = True
 
     # Properties
+    # TODO(briancurtin): find documentation for these properties
     admin_state_up = resource.prop('admin_state_up', type=bool)
     description = resource.prop('description')
     name = resource.prop('name')

openstack/network/v2/metering_label.py

@@ -29,6 +29,9 @@ class MeteringLabel(resource.Resource):
     put_update = True
 
     # Properties
+    #: Description of the label.
     description = resource.prop('description')
+    #: Name of the label.
     name = resource.prop('name')
+    #: Project this label is associated with.
     project_id = resource.prop('tenant_id')

openstack/network/v2/metering_label_rule.py

@@ -29,7 +29,15 @@ class MeteringLabelRule(resource.Resource):
     put_update = True
 
     # Properties
+    #: ingress or egress: The direction in which metering rule is
+    #: applied. Default: ``"ingress"``
     direction = resource.prop('direction')
+    #: Specify whether the ``remote_ip_prefix`` will be excluded or not
+    #: from traffic counters of the metering label, ie: to not count the
+    #: traffic of a specific IP address of a range. Default: ``False``,
+    #: *Type: bool*
     excluded = resource.prop('excluded', type=bool)
+    #: The meteting label ID to associate with this metering rule.
     metering_label_id = resource.prop('metering_label_id')
+    #: The remote IP prefix to be associated with this metering rule.
     remote_ip_prefix = resource.prop('remote_ip_prefix')

openstack/network/v2/network.py

@@ -29,14 +29,29 @@ class Network(resource.Resource):
     put_update = True
 
     # Properties
+    #: The administrative state of the network, which is up ``True`` or
+    #: down ``False``. *Type: bool*
     admin_state_up = resource.prop('admin_state_up', type=bool)
+    #: The network name.
     name = resource.prop('name')
+    #: The project this network is associated with.
     project_id = resource.prop('tenant_id')
+    # TODO(briancurtin): These provider_ explanations are made up because
+    # they're undocumented.
+    #: Type of network, such as vlan.
     provider_network_type = resource.prop('provider:network_type')
+    #: ID of the physical network.
     provider_physical_network = resource.prop('provider:physical_network')
+    #: Segmentation ID.
     provider_segmentation_id = resource.prop('provider:segmentation_id')
+    #: Whether or not the router is external. *Type: bool*
     router_external = resource.prop('router:external')
     segments = resource.prop('segments')
+    #: Indicates whether this network is shared across all tenants.
+    #: By default, only administrative users can change this value.
+    #: *Type: bool*
     shared = resource.prop('shared', type=bool)
+    #: The network status.
     status = resource.prop('status')
+    #: The associated subnets.
     subnets = resource.prop('subnets')

openstack/network/v2/pool.py

@@ -29,13 +29,27 @@ class Pool(resource.Resource):
     put_update = True
 
     # Properties
+    #: The administrative state of the pool, which is up ``True`` or down
+    #: ``False``. *Type: bool*
     admin_state_up = resource.prop('admin_state_up', type=bool)
+    #: Description for the pool.
     description = resource.prop('description')
+    #: The ID of the associated health monitor.
     healthmonitor_id = resource.prop('healthmonitor_id')
+    #: The load-balancer algorithm, which is round-robin, least-connections,
+    #: and so on. This value, which must be supported, is dependent on the
+    #: load-balancer provider. Round-robin must be supported.
     lb_algorithm = resource.prop('lb_algorithm')
+    #: List of members that belong to the pool. *Type: list*
     members = resource.prop('members')
+    #: Pool name. Does not have to be unique.
     name = resource.prop('name')
+    #: The project this pool is associated with.
     project_id = resource.prop('tenant_id')
+    #: The protocol of the pool, which is TCP, HTTP, or HTTPS.
     protocol = resource.prop('protocol')
+    #: Session persistence algorithm that should be used (if any).
+    #: *Type: dict with keys ``type`` and ``cookie_name``*
     session_persistence = resource.prop('session_persistence')
+    #: The status of the pool. Indicates whether the pool is operational.
     status = resource.prop('status')

openstack/network/v2/pool_member.py

@@ -29,6 +29,7 @@ class PoolMember(resource.Resource):
     put_update = True
 
     # Properties
+    # TODO(briancurtin): I can't find where this is documented.
     address = resource.prop('address')
     admin_state_up = resource.prop('admin_state_up', type=bool)
     project_id = resource.prop('tenant_id')

openstack/network/v2/port.py

@@ -29,20 +29,54 @@ class Port(resource.Resource):
     put_update = True
 
     # Properties
+    #: The administrative state of the port, which is up ``True`` or
+    #: down ``False``. *Type: bool*
     admin_state_up = resource.prop('admin_state_up', type=bool)
+    #: Allowed address pairs. *Type: dict*
     allowed_address_pairs = resource.prop('allowed_address_pairs', type=dict)
+    #: The ID of the host where the port is allocated. In some cases,
+    #: different implementations can run on different hosts.
     binding_host_id = resource.prop('binding:host_id')
+    #: A dictionary the enables the application running on the specified
+    #: host to pass and receive vif port-specific information to the plug-in.
     binding_profile = resource.prop('binding:profile')
+    #: Read-only. A dictionary that enables the application to pass
+    #: information about functions that the Networking API provides.
+    #: To enable or disable port filtering features such as security group
+    #: and anti-MAC/IP spoofing, specify ``port_filter: True`` or
+    #: ``port_filter: False``.
     binding_vif_details = resource.prop('binding:vif_details', type=dict)
+    #: Read-only. The vif type for the specified port.
     binding_vif_type = resource.prop('binding:vif_type')
+    #: The vnic type that is bound to the neutron port.
+    #:
+    #: In POST and PUT operations, specify a value of ``normal`` (virtual nic),
+    #: ``direct`` (pci passthrough), or ``macvtap``
+    #: (virtual interface with a tap-like software interface).
+    #: These values support SR-IOV PCI passthrough networking.
+    #: The ML2 plug-in supports the vnic_type.
+    #:
+    #: In GET operations, the binding:vnic_type extended attribute is
+    #: visible to only port owners and administrative users.
     binding_vnic_type = resource.prop('binding:vnic_type')
+    #: The ID of the device that uses this port. For example, a virtual server.
     device_id = resource.prop('device_id')
+    #: The ID of the entity that uses this port. For example, a dhcp agent.
     device_owner = resource.prop('device_owner')
+    #: Extra DHCP options.
     extra_dhcp_opts = resource.prop('extra_dhcp_opts', type=dict)
+    #: IP addresses for the port. Includes the IP address and subnet ID.
     fixed_ips = resource.prop('fixed_ips')
+    #: The MAC address of the port.
     mac_address = resource.prop('mac_address')
+    #: The port name.
     name = resource.prop('name')
+    #: The ID of the attached network.
     network_id = resource.prop('network_id')
+    #: The ID of the project who owns the network. Only administrative
+    #: users can specify a project ID other than their own.
     project_id = resource.prop('tenant_id')
+    #: The IDs of any attached security groups.
     security_groups = resource.prop('security_groups')
+    #: The port status. Value is ``ACTIVE`` or ``DOWN``.
     status = resource.prop('status')

openstack/network/v2/quota.py

@@ -24,9 +24,15 @@ class Quota(resource.Resource):
     allow_list = True
 
     # Properties
+    #: The maximum amount of floating IPs you can have. *Type: int*
     floating_ip = resource.prop('floatingip', type=int)
+    #: The maximum amount of networks you can create. *Type: int*
     network = resource.prop('network', type=int)
+    #: The maximum amount of ports you can create. *Type: int*
     port = resource.prop('port', type=int)
+    #: The project these quota values are for.
     project_id = resource.prop('tenant_id')
+    #: The maximum amount of routers you can create. *Type: int*
     router = resource.prop('router', type=int)
+    #: The maximum amount of subnets you can create. *Type: int*
     subnet = resource.prop('subnet', type=int)

openstack/network/v2/router.py

@@ -30,19 +30,41 @@ class Router(resource.Resource):
     put_update = True
 
     # Properties
+    #: The administrative state of the router, which is up ``True``
+    #: or down ``False``. *Type: bool*
     admin_state_up = resource.prop('admin_state_up', type=bool)
+    #: The ``network_id``, for the external gateway. *Type: dict*
     external_gateway_info = resource.prop('external_gateway_info', type=dict)
+    #: The router name.
     name = resource.prop('name')
+    #: The project this router is associated with.
     project_id = resource.prop('tenant_id')
+    #: The router status.
     status = resource.prop('status')
 
     def add_interface(self, session, subnet_id):
+        """Add an internal interface to a logical router.
+
+        :param session: The session to communicate through.
+        :type session: :class:`~openstack.session.Session`
+        :param str subnet_id: The ID of a subnet to add.
+
+        :returns: The body of the response as a dictionary.
+        """
         body = {'subnet_id': subnet_id}
         url = utils.urljoin(self.base_path, self.id, 'add_router_interface')
         resp = session.put(url, service=self.service, json=body).body
         return resp
 
     def remove_interface(self, session, subnet_id):
+        """Remove an internal interface from a logical router.
+
+        :param session: The session to communicate through.
+        :type session: :class:`~openstack.session.Session`
+        :param str subnet_id: The ID of a subnet to remove.
+
+        :returns: The body of the response as a dictionary.
+        """
         body = {'subnet_id': subnet_id}
         url = utils.urljoin(self.base_path, self.id, 'remove_router_interface')
         resp = session.put(url, service=self.service, json=body).body

openstack/network/v2/security_group.py

@@ -30,9 +30,15 @@ class SecurityGroup(resource.Resource):
     put_update = True
 
     # Properties
+    #: The security group description.
     description = resource.prop('description')
+    #: The security group name.
     name = resource.prop('name')
+    #: The project this security group is associated with.
     project_id = resource.prop('tenant_id')
+    #: A list of
+    #: :class:`~openstack.network.v2.security_group_rule.SecurityGroupRule`
+    #: objects. *Type: list*
     security_group_rules = resource.prop('security_group_rules')
 
     def __init__(self, attrs=None, loaded=False):

openstack/network/v2/security_group_rule.py

@@ -29,12 +29,37 @@ class SecurityGroupRule(resource.Resource):
     put_update = True
 
     # Properties
+    #: ``ingress`` or ``egress``: The direction in which the security group
+    #: rule is applied. For a compute instance, an ingress security group
+    #: rule is applied to incoming ingress traffic for that instance.
+    #: An egress rule is applied to traffic leaving the instance.
     direction = resource.prop('direction')
+    #: Must be IPv4 or IPv6, and addresses represented in CIDR must match
+    #: the ingress or egress rules.
     ethertype = resource.prop('ethertype')
+    #: The maximum port number in the range that is matched by the
+    #: security group rule. The port_range_min attribute constrains
+    #: the port_range_max attribute. If the protocol is ICMP, this
+    #: value must be an ICMP type.
     port_range_max = resource.prop('port_range_max')
+    #: The minimum port number in the range that is matched by the
+    #: security group rule. If the protocol is TCP or UDP, this value
+    #: must be less than or equal to the value of the port_range_max
+    #: attribute. If the protocol is ICMP, this value must be an ICMP type.
     port_range_min = resource.prop('port_range_min')
+    #: The project this rule is associated with.
     project_id = resource.prop('tenant_id')
+    #: The protocol that is matched by the security group rule.
+    #: Valid values are ``null``, ``tcp``, ``udp``, and ``icmp``.
     protocol = resource.prop('protocol')
+    #: The remote group ID to be associated with this security group rule.
+    #: You can specify either ``remote_group_id`` or ``remote_ip_prefix``
+    #: in the request body.
     remote_group_id = resource.prop('remote_group_id')
+    #: The remote IP prefix to be associated with this security group rule.
+    #: You can specify either ``remote_group_id`` or ``remote_ip_prefix``
+    #: in the request body. This attribute matches the specified IP prefix
+    #: as the source IP address of the IP packet.
     remote_ip_prefix = resource.prop('remote_ip_prefix')
+    #: The security group ID to associate with this security group rule.
     security_group_id = resource.prop('security_group_id')

openstack/network/v2/subnet.py

@@ -29,13 +29,24 @@ class Subnet(resource.Resource):
     put_update = True
 
     # Properties
+    #: The start and end addresses for the allocation pools.
     allocation_pools = resource.prop('allocation_pools')
+    #: The CIDR.
     cidr = resource.prop('cidr')
+    #: A list of DNS nameservers.
     dns_nameservers = resource.prop('dns_nameservers')
+    #: Set to ``True`` if DHCP is enabled and ``False`` if DHCP is disabled.
+    #: *Type: bool*
     enable_dhcp = resource.prop('enable_dhcp', type=bool)
+    #: The gateway IP address.
     gateway_ip = resource.prop('gateway_ip')
+    #: A list of host routes.
     host_routes = resource.prop('host_routes')
+    #: The IP version, which is ``4`` or ``6``.
     ip_version = resource.prop('ip_version')
+    #: The subnet name.
     name = resource.prop('name')
+    #: The ID of the attached network.
     network_id = resource.prop('network_id')
+    #: The project this subnet is associated with.
     project_id = resource.prop('tenant_id')