Document network throttling improvements (VPC public gateway rate)

source/adminguide/networking/virtual_private_cloud_config.rst

@@ -222,6 +222,11 @@ addresses in the form of a Classless Inter-Domain Routing (CIDR) block.
       .. note::
          In case Conserve Mode is enabled on VPC Offering and VPC Network Tier Offerings, then the Source NAT IP address of the VPC can be reused for multiple services.
 
+      .. note::
+         Since 24.0.0, a VPC offering can limit the bandwidth of the public
+         gateway of the VPCs created with it. See
+         :ref:`throttling-vpc-public-gateway`.
+
 
    -  **DNS**: A set of custom DNS that will be used by this VPC. If not provided then DNS specified for the zone will be used. Available only when the selected VPC offering supports DNS service.
 
@@ -1500,6 +1505,11 @@ Editing, Restarting, and Removing a Virtual Private Cloud
    To restart a VPC, select the VPC, then click the Restart button.
    |restart-vpc.png|
 
+   Since 24.0.0, a change of the public network rate of the VPC, for example
+   after the global parameter vpc.public.network.throttling.rate was
+   changed, is applied only when the VPC is restarted with the **Clean up**
+   option. See :ref:`throttling-vpc-public-gateway`.
+
 
 Working with Domain VPCs
 ~~~~~~~~~~~~~~~~~~~~~~~~

source/adminguide/service_offerings.rst

@@ -687,14 +687,22 @@ configured on the following:
 
 -  Network Offering
 
--  Service Offering
+-  Service Offering (the compute offering of an instance, and the
+   system offering of a virtual router)
+
+-  VPC Offering (the public gateway of a VPC), since 24.0.0
 
 -  Global parameter
 
-If network rate is set to NULL in service offering, the value provided
-in the vm.network.throttling.rate global parameter is applied. If the
-value is set to NULL for network offering, the value provided in the
-network.throttling.rate global parameter is considered.
+For an instance, if network rate is set to NULL in the compute offering,
+the value provided in the vm.network.throttling.rate global parameter is
+applied. For the guest network of a virtual router, the network rate of
+the system offering of the router is used if it is set. Otherwise the
+network rate of the guest network offering is used, and if that is NULL,
+the value provided in the network.throttling.rate global parameter is
+considered. If a VPC offering has no public network rate, the value
+provided in the vpc.public.network.throttling.rate global parameter is
+used for the VPCs created with it.
 
 For the default public, storage, and management networks, network rate
 is set to 0. This implies that the public, storage, and management
@@ -707,11 +715,15 @@ on different types of networks in CloudStack.
 
 .. cssclass:: table-striped table-bordered table-hover
 
-============================================ ===============================
+============================================ =========================================================
 Networks                                     Network Rate Is Taken from
-============================================ ===============================
-Guest network of Virtual Router              Guest Network Offering
-Public network of Virtual Router             Guest Network Offering
+============================================ =========================================================
+Guest network of Virtual Router              System Offering of the Virtual Router, if it sets a
+                                             network rate; otherwise Guest Network Offering
+Public network of Virtual Router in a VPC    VPC Offering (public network rate), or the
+                                             vpc.public.network.throttling.rate global parameter
+                                             if not set
+Public network of Virtual Router (not VPC)   Guest Network Offering
 Storage network of Secondary Storage VM      System Network Offering
 Management network of Secondary Storage VM   System Network Offering
 Storage network of Console Proxy VM          System Network Offering
@@ -721,11 +733,16 @@ Management network of Virtual Router         System Network Offering
 Public network of Secondary Storage instance System Network Offering
 Public network of Console Proxy instance     System Network Offering
 Default network of a guest instance          Compute Offering
-Additional networks of a guest instance      Corresponding Network Offerings
-============================================ ===============================
+Additional networks of a guest instance      Compute Offering
+============================================ =========================================================
+
+Since 24.0.0, the Compute Offering network rate applies to every network of
+an instance, not only the default network. If the Compute Offering has no
+network rate, vm.network.throttling.rate is used.
 
 A guest instance must have a default network, and can also have many
-additional networks. Depending on various parameters, such as the host
+additional networks. The compute offering network rate applies to all of
+them. Depending on various parameters, such as the host
 and virtual switch used, you can observe a difference in the network
 rate in your cloud. For example, on a VMware host the actual network
 rate varies based on where they are configured (compute offering,
@@ -749,12 +766,12 @@ network used in CloudStack. In shared networks, ingress traffic is
 unlimited for CloudStack, and egress traffic is limited to the rate that
 applies to the port group used by the instance if any. If the compute
 offering has a network rate configured, this rate applies to the egress
-traffic, otherwise the network rate set for the network offering
-applies. For isolated networks, the network rate set for the network
-offering, if any, effectively applies to the ingress traffic. This is
-mainly because the network rate set for the network offering applies to
-the egress traffic from the virtual router to the instance. The egress
-traffic is limited by the rate that applies to the port group used by
+traffic, otherwise the value of the vm.network.throttling.rate global
+parameter applies. For isolated networks, the network rate set for the
+network offering, if any, effectively applies to the ingress traffic.
+This is mainly because the network rate set for the network offering
+applies to the egress traffic from the virtual router to the instance.
+The egress traffic is limited by the rate that applies to the port group used by
 the instance if any, similar to shared networks.
 
 For example:
@@ -767,6 +784,117 @@ while egress traffic will be limited to 200 Mbps. In an isolated
 network, ingress traffic will be limited to 10 Mbps and egress to 200
 Mbps.
 
+.. note::
+   Since 24.0.0, the network rate of the network offering no longer applies
+   to the NICs of a user instance; the compute offering rate (or
+   vm.network.throttling.rate) does. The network offering rate still
+   applies to the guest interface of the virtual router, unless the
+   system offering of the router sets a rate.
+
+.. _throttling-vpc-public-gateway:
+
+Throttling the Public Gateway of a VPC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since 24.0.0, an administrator can limit the bandwidth of the public
+(internet-facing) gateway of a VPC. The limit is set on the VPC offering,
+so that different VPC offerings can give different tenants different
+levels of service. It is applied to the public interface of the VPC
+virtual router, independently of the network rate of the guest networks
+(tiers) of the VPC.
+
+To create a VPC offering with a public network rate:
+
+#. Log in to the CloudStack UI as an administrator.
+
+#. Navigate to Service Offerings and choose VPC Offerings.
+
+#. Click Add VPC Offering.
+
+#. In the dialog, set **Public network rate (Mb/s)** together with the
+   other settings of the offering:
+
+   -  Enter a positive number to limit the public gateway to that rate in
+      Mbps.
+
+   -  Enter -1 or 0 for unlimited bandwidth.
+
+   -  Leave the field empty if the offering should not set a rate.
+
+   .. image:: /_static/images/vpc_offering_dialog_public_network_rate.png
+      :width: 400px
+      :align: center
+      :alt: Add VPC Offering dialog box with the Public network rate field
+
+#. Click OK.
+
+The same can be done with the **publicnetworkrate** parameter of the
+createVPCOffering API.
+
+The public network rate cannot be changed after the VPC offering is
+created. To use another rate, create a new VPC offering.
+
+The rate that applies to a VPC is:
+
+-  the public network rate of its VPC offering, if the offering has one.
+   -1 or 0 means unlimited and the global parameter is not used;
+
+-  otherwise the value of the zone level global parameter
+   vpc.public.network.throttling.rate. Its default value is -1, which
+   means unlimited. The parameter accepts -1, 0 (both unlimited) or a
+   positive number.
+
+The rate of a VPC is updated when the VPC is restarted with the cleanup
+option, which recreates the virtual router. A restart without cleanup does
+not update it. Changing vpc.public.network.throttling.rate therefore
+affects an existing VPC only after a restart with cleanup. The rate of a
+VPC is shown as **Public network rate (Mb/s)** in the VPC details, and as
+**publicnetworkrate** in the listVPCs API response.
+
+.. image:: /_static/images/vpc_details_public_network_rate.png
+   :width: 335px
+   :align: center
+   :alt: VPC details showing the Public network rate
+
+The details of a VPC offering show the same field. An offering with an
+unlimited public network rate (-1) shows **Unlimited**. An offering that
+has no rate set does not show the field.
+
+.. image:: /_static/images/vpc_offering_details_unlimited_rate.png
+   :width: 300px
+   :align: center
+   :alt: VPC offering details showing an unlimited public network rate
+
+If a VPC is moved to another VPC offering with the migrateVPC API, it
+uses the public network rate of the new offering.
+
+.. note::
+   Converting a VPC to a redundant VPC (restartVPC with makeredundant=true)
+   moves it to the built-in Redundant VPC offering, which has no public
+   network rate. After the restart the VPC uses the value of
+   vpc.public.network.throttling.rate.
+
+Network Rates After Upgrading
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you upgrade to 24.0.0, CloudStack keeps the network rates of existing
+networks and NICs as they were before the upgrade. Running instances and
+virtual routers are not changed. Existing VPCs have no public network
+limit.
+
+The new rules described above apply to new networks and NICs. They apply
+to existing instances and virtual routers the next time they are started:
+stop and start an instance, or stop and start a virtual router, or restart
+its network or VPC with the cleanup option. At that point the rate of a NIC
+can increase or decrease, for example when the system offering of the
+router, or the compute offering of the instance, takes precedence.
+
+.. note::
+   The rate shown for a NIC is the rate CloudStack calculated for it. It is
+   not read from the hypervisor. Until an instance or virtual router is
+   restarted, the bandwidth in effect can differ from the rate shown, for
+   example if a throttling setting was changed after it was started.
+
 
 Changing the Default System Offering for System VMs
 ---------------------------------------------------

source/installguide/configuration.rst

@@ -1985,6 +1985,8 @@ zone      pool.storage.allocated.capacity.disablethreshold           The percent
                                                                      available allocated storage is below the threshold.
 zone      storage.overprovisioning.factor                            Used for storage over-provisioning calculation; available storage will be the mathematical product of actualStorageSize and                                                                                storage.overprovisioning.factor.
 zone      network.throttling.rate                                    Default data transfer rate in megabits per second allowed in a network.
+zone      vpc.public.network.throttling.rate                         Default data transfer rate in megabits per second allowed for a VPC's public network, used when the VPC offering does not
+                                                                     specify a rate. -1 or 0 means unlimited.
 zone      guest.domain.suffix                                        Default domain name for instances inside a virtual networks with a router.
 zone      router.template.xen                                        Name of the default router Template on Xenserver.
 zone      router.template.kvm                                        Name of the default router Template on KVM.