mc qos rule add

The mc qos rule add command adds a single new Quality of Service (QoS) rule to an AIStor deployment.

For more information, see Bucket-level Quality of Service.

Syntax

Example

The following command adds a QoS rule to limit the s3.GetObject API to 100 requests per second for the bucket1 bucket:

mc qos rule add myaistor/bucket1 --api "s3.GetObject" --rate "100" --burst "50" --id "rule1" --limit rps --priority 1

Syntax

The command has the following syntax:

mc [GLOBALFLAGS] qos rule add           \
                         TARGET         \
                         --api string   \
                         --limit string \
                         --priority int \  
                         --rate int     \                     
                         [--burst int]  \
                         [--id string]  \
                         [--label string]

Brackets [] indicate optional parameters.
Parameters sharing a line are mutually dependent.
Parameters separated using the pipe | operator are mutually exclusive.

Copy the example to a text editor and modify as-needed before running the command in the terminal/shell.

Parameters

TARGET

Required

The alias and bucket for the QoS rule.

The target cannot include wildcards. To add an individual rule to an object prefix, append the prefix name to the target.

For example:

mc qos rule add myaistor/bucket1/prefix2 --api "s3.GetObject" --rate "100" --burst "50" --id "rule1" --limit rps --priority 1

--api

Required

The API operation to which the rule applies.

You can use wildcards to match multiple APIs:

s3.GetObject - Specific API
s3.List* - All List APIs

Common S3 API operations:

s3.GetObject
s3.PutObject
s3.ListObjectsV2
s3.ListObjectsV1
s3.DeleteObject
s3.HeadObject

--limit

Required

The type of rate limiting to apply.

Valid values:

rps - Requests per second (default)
concurrency - Concurrent requests

--priority

Required

The priority level for the rule.

Rules with lower priority numbers are applied first.

--rate

Required

The rate limit value.

The meaning depends on the --limit type:

For rps (requests per second): Maximum number of requests per second
For concurrency: Maximum number of concurrent requests

--burst

Optional

The burst limit in requests.

Required when --limit is set to rps. Specifies the maximum number of requests that can be processed in a burst above the configured rate. Ignored if --limit is set to concurrency.

--id

Optional

A unique identifier for the rule.

If not provided, a UUID is automatically generated. Duplicate values are allowed but can produce unexpected results with mc qos rule remove.

--label

Optional

A descriptive label for the rule.

Global flags

This command supports any of the global flags.

Examples

Add a concurrency limit rule

The following command adds a QoS rule to limit all List APIs to 50 concurrent requests per AIStor node:

mc qos rule add myaistor/mybucket --api "s3.List*" --rate "50" --id "rule1" --limit concurrency --priority 1

Add a rule with object prefix

The following command adds a QoS rule to limit the s3.GetObject API on the mybucket bucket with the myprefix prefix to 10 requests per second with a burst of 20 requests:

mc qos rule add myaistor/mybucket/myprefix --api "s3.GetObject" --rate "10" --burst "20" --id "rule3" --limit rps --priority 2

S3 compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with AIStor and AWS S3 for expected functionality and behavior.

MinIO provides no guarantees for other S3-compatible services, as their S3 API implementation is unknown and therefore unsupported.

While mc commands may work as documented, any such usage is at your own risk.

Permissions

You must have appropriate permissions on the deployment to add QoS rules.