Configure bucket QoS by using put-bucket-qos-info - Object Storage Service

Sets the Quality of Service (QoS) bandwidth limits for a bucket. All six bandwidth fields are required in the request body.

Important

The resource pool QoS feature is in invitational preview. To apply, your Object Storage Service (OSS) throughput in a specific region must be at or above 500 Gbit/s. Contact technical support to request access.

Prerequisites

Before you begin, ensure that you have:

A bucket that belongs to a resource pool
The oss:PutBucketQoSInfo permission (required when using a Resource Access Management (RAM) user or Security Token Service (STS); Alibaba Cloud root accounts have this permission by default). For setup instructions, see Attach a custom policy to a RAM user

Syntax

ossutil api invoke-operation --op-name put-bucket-qos-info \
    --method PUT \
    --bucket <bucket-name> \
    --parameters qosInfo \
    --body=file://<path-to-xml-file>

Parameters

Parameter	Type	Required	Description
`--bucket`	string	Yes	The bucket name
`--parameters`	stringArray	Yes	Request parameters in `k[=v]` format. For this operation, pass `qosInfo`
`--body`	string	Yes	The request body. Use `file://<path>` to read from a file, or `-` to read from stdin

For global options, see Global command-line options.

Request body

The --body parameter accepts an XML file with the following structure:

<QoSConfiguration>
  <TotalUploadBandwidth>integer</TotalUploadBandwidth>
  <IntranetUploadBandwidth>integer</IntranetUploadBandwidth>
  <ExtranetUploadBandwidth>integer</ExtranetUploadBandwidth>
  <TotalDownloadBandwidth>integer</TotalDownloadBandwidth>
  <IntranetDownloadBandwidth>integer</IntranetDownloadBandwidth>
  <ExtranetDownloadBandwidth>integer</ExtranetDownloadBandwidth>
</QoSConfiguration>

All fields are integers in Gbit/s. Two special values apply across all fields:

-1: No limit. This is the default when a field is omitted.
0: Block all requests of that type.

Field reference

Field	Required	Description
`TotalUploadBandwidth`	Yes	Total upload bandwidth cap. Combined upload bandwidth across internal and external networks cannot exceed this value
`IntranetUploadBandwidth`	Yes	Upload bandwidth over internal networks (classic network and virtual private clouds (VPCs)). Cannot exceed `TotalUploadBandwidth`
`ExtranetUploadBandwidth`	Yes	Upload bandwidth over external networks (Internet and Alibaba Cloud CDN). Cannot exceed `TotalUploadBandwidth`
`TotalDownloadBandwidth`	Yes	Total download bandwidth cap. Combined download bandwidth across internal and external networks cannot exceed this value
`IntranetDownloadBandwidth`	Yes	Download bandwidth over internal networks (classic network and VPCs). Cannot exceed `TotalDownloadBandwidth`
`ExtranetDownloadBandwidth`	Yes	Download bandwidth over external networks (Internet and Alibaba Cloud CDN). Cannot exceed `TotalDownloadBandwidth`

A bucket's bandwidth threshold cannot exceed the bandwidth threshold of the resource pool it belongs to.

Example

Set upload and download caps to 10 Gbit/s with no sub-limits

Create a configuration file named qos.xml:

<QoSConfiguration>
  <TotalUploadBandwidth>10</TotalUploadBandwidth>
  <IntranetUploadBandwidth>-1</IntranetUploadBandwidth>
  <ExtranetUploadBandwidth>-1</ExtranetUploadBandwidth>
  <TotalDownloadBandwidth>10</TotalDownloadBandwidth>
  <IntranetDownloadBandwidth>-1</IntranetDownloadBandwidth>
  <ExtranetDownloadBandwidth>-1</ExtranetDownloadBandwidth>
</QoSConfiguration>

This configuration caps total upload and download at 10 Gbit/s each. Internal and external network sub-limits are set to -1 (unlimited), so each sub-limit can use up to the full 10 Gbit/s total.

Apply the configuration to examplebucket:

ossutil api invoke-operation --op-name put-bucket-qos-info --method PUT --bucket examplebucket --parameters qosInfo --body=file://qos.xml

Output

This command produces no output on success. To verify the configuration was applied, run the corresponding get-bucket-qos-info operation.