SupportConsoleDevelopersStart a trialContact

Chapter 13. Red Hat Quay quota management and enforcement overview

With Red Hat Quay quota management, superusers can track storage consumption and set soft or hard limits for organizations, repositories, or the entire registry.

Red Hat Quay superusers can manage capacity limits in the following ways:

  • Quota reporting: An administrator can track the storage consumption of all organizations. Users can track the storage consumption of their assigned organization.
  • Quota management: An administrator can define soft and hard checks for Red Hat Quay users. Soft checks tell users if the storage consumption of an organization reaches their configured threshold. Hard checks prevent users from pushing to the registry when storage consumption reaches the configured limit.

These features help service owners of a Red Hat Quay registry define service level agreements and support a healthy resource budget.

13.1. Quota management limitations
Copy link

Quota management in Red Hat Quay has limits related to push-time calculation and database-backed maximum sizes. Review these constraints before you set organization quotas.

One limitation of the quota management feature is that calculating resource consumption on the push of an artifact results in the calculation becoming part of the push’s critical path. Without this, usage data might drift.

The maximum storage quota size depends on the selected database:

Table 13.1. Maximum storage quota by database
DatabaseMaximum quota size

Postgres

8388608 TB

MySQL

8388608 TB

SQL Server

16777216 TB

13.2. Setting a system-wide default quota
Copy link

To specify a system-wide default storage quota that is applied to every organization and user, you can use the DEFAULT_SYSTEM_REJECT_QUOTA_BYTES configuration flag. When this field is set, and the quota limit has been met, the system automatically rejects new artifacts. By default, this configuration field is disabled.

If you configure a specific quota for an organization or user, and then delete that quota, the system-wide default quota applies if one has been set. Similarly, if you have configured a specific quota for an organization or user, and then modify the system-wide default quota, the updated system-wide default overrides any specific settings.

The following procedure shows you how to configure a system-wide default quota.

Procedure

  1. Set a system-wide default storage quota by including the DEFAULT_SYSTEM_REJECT_QUOTA_BYTES field in your config.yaml file. For example: 

    # ...
DEFAULT_SYSTEM_REJECT_QUOTA_BYTES: 100gb
# ...
  2. Restart your Red Hat Quay registry.

To establishing quota for an organization by using the Red Hat Quay UI in Red Hat Quay, you can follow the steps in this procedure.

The following procedure describes how you can report storage consumption and establish storage quota limits for a repository.

Prerequisites

  • A superuser account.
  • Enough storage to meet the demands of quota limitations.

Procedure

  1. Set FEATURE_QUOTA_MANAGEMENT: True in your config.yaml file and then restart your registry. For example: 

    # ...
FEATURE_QUOTA_MANAGEMENT: True
# ...
  2. Create a new organization or choose an existing one.
  3. Log in to the registry as a superuser and navigate to the Manage Organizations tab on the Super User Admin Panel. Click the Options icon of the organization for which you want to create storage quota limits.
  4. Click Configure Quota.
  5. For Set storage quota, enter the initial quota, for example, 10 MiB. You can then click Apply.

  6. Optional: For Quota policy select one of the following Actions. You can then enter a Quota Threshold and click Add Limit.

    • Reject: When this option is selected, any artifact that exceeds the established quota is rejected.

    • Warning: When this option is selected, users are notified of pushed artifacts that exceed the configured quota, however, the artifact successfully pushes.

      Note

      The quota threshold percent determines when Red Hat Quay starts warning users that the repository is approaching its assigned storage quota.

Verification

  1. Pull a sample artifact by entering the following command: 

    $ podman pull busybox

  2. Tag the sample artifact by entering the following command: 

    $ podman tag docker.io/library/busybox quay-server.example.com/testorg/busybox:test

  3. Push the sample artifact to the organization by entering the following command: 

    $ podman push --tls-verify=false quay-server.example.com/testorg/busybox:test
  4. Navigate to the Super User Admin Panel on the Red Hat Quay UI, then click Manage Organizations. The Organizations page shows the total proportion of the quota used by the artifact.

  5. Optional: Pull a second sample artifact with intentions of exceeding the established quota by entering the following command: 

    $ podman pull nginx

  6. Optional: Tag the second artifact by entering the following command: 

    $ podman tag docker.io/library/nginx quay-server.example.com/testorg/nginx

  7. Optional: Push the second artifact to the organization by entering the following command: 

    $ podman push --tls-verify=false quay-server.example.com/testorg/nginx

    If the artifact exceeds the defined quota, and you set the Quota policy to Reject, the following error message is returned: 

    denied: Quota has been exceeded on namespace

    If the artifact exceeds the defined quota, and you set the Quota policy to Warning, no error message is returned, and the image is successfully pushed.

    Notifications for both Reject and Warning policies are also returned on the Red Hat Quay UI by clicking the bell icon.

13.4. Configuring quota notifications
Copy link

After you set FEATURE_QUOTA_NOTIFICATIONS to true, you can configure external notification channels to receive alerts when quota thresholds are reached.

Prerequisites

  • You have a superuser account so that you can configure the config.yaml file.
  • You have an account with org:admin access so that you can configure notifications.
  • You have administrative privileges for the organization or user namespace.

Procedure

  1. Set FEATURE_QUOTA_NOTIFICATIONS: true in your config.yaml file and then restart your registry. 

    # ...
FEATURE_QUOTA_NOTIFICATIONS: true
# ...
  2. Configure quota limits for your organization or user namespace. See "Establishing quota for an organization by using the Red Hat Quay UI".
  3. In the Red Hat Quay UI, open your organization or user settings page.
  4. Click Create Notification.

  5. Select one of the following notification events:

    • Quota Warning: Triggers when storage usage crosses a Warning quota limit (quota_warning event).
    • Quota Error: Triggers when storage usage crosses a Reject quota limit (quota_error event).

  6. Select one of the following notification methods:

    • Email: Sends a notification to an organization contact email or admin email address.
    • Slack: Sends a notification to a Slack webhook.
    • Webhook: Sends a notification to a custom webhook URL.
    • Quay Notification: Creates an in-app notification in Red Hat Quay.
  7. Configure the method-specific settings for your chosen notification method.
  8. Click the Create Notification button.

Verification

  • Verify that the notification shows in the Notifications list for your namespace.
  • If quota thresholds are exceeded, notifications get sent to configured channels. Check the Failures count to verify notification delivery status.

13.5. Managing quota limits by using the API
Copy link

You can use the Red Hat Quay API to check, create, change, or delete organization quota limits when an organization does not yet have a quota configured.

Before you begin, you must have generated an OAuth access token.

13.5.1. Setting quota by using the API
Copy link

To create, view, or update an organization storage quota in Red Hat Quay, you can call the organization quota API endpoints with an OAuth access token.

Procedure

  1. To set a quota for an organization, you can use the POST /api/v1/organization/{orgname}/quota endpoint: 

    $ curl -X POST "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota" \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
         "limit_bytes": 10737418240,
         "limits": "10 Gi"
     }'

    Example output:

    "Created"

  2. Use the GET /api/v1/organization/{orgname}/quota command to see if your organization already has an established quota: 

    $ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json'  https://<quay-server.example.com>/api/v1/organization/<organization_name>/quota  | jq

    Example output:

    [{"id": 1, "limit_bytes": 10737418240, "limit": "10.0 GiB", "default_config": false, "limits": [], "default_config_exists": false}]

  3. You can use the PUT /api/v1/organization/{orgname}/quota/{quota_id} command to modify the existing quota limitation. For example: 

    $ curl -X PUT "https://<quay-server.example.com>/api/v1/organization/<orgname>/quota/<quota_id>" \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
         "limit_bytes": <limit_in_bytes>
     }'

    Example output:

    {"id": 1, "limit_bytes": 21474836480, "limit": "20.0 GiB", "default_config": false, "limits": [], "default_config_exists": false}

13.5.2. Viewing quota usage by using the API
Copy link

To view organization and repository storage consumption in Red Hat Quay, you can query the repository list and organization API endpoints.

Procedure

  • To view storage consumed by repositories in an organization, send a GET request to the /api/v1/repository endpoint: 

    $ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' 'https://<quay-server.example.com>/api/v1/repository?last_modified=true&namespace=<organization_name>&popularity=true&public=true'  | jq

    Example output: 

    {
  "repositories": [
    {
      "namespace": "testorg",
      "name": "ubuntu",
      "description": null,
      "is_public": false,
      "kind": "image",
      "state": "NORMAL",
      "quota_report": {
        "quota_bytes": 27959066,
        "configured_quota": 104857600
      },
      "last_modified": 1651225630,
      "popularity": 0,
      "is_starred": false
    }
  ]
}

  • To view the quota report for multiple repositories in the organization, send a GET request to the /api/v1/repository endpoint: 

    $ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' 'https://<quay-server.example.com>/api/v1/repository?last_modified=true&namespace=<organization_name>&popularity=true&public=true'

    Example output: 

    {
  "repositories": [
    {
      "namespace": "testorg",
      "name": "ubuntu",
      "description": null,
      "is_public": false,
      "kind": "image",
      "state": "NORMAL",
      "quota_report": {
        "quota_bytes": 27959066,
        "configured_quota": 104857600
      },
      "last_modified": 1651225630,
      "popularity": 0,
      "is_starred": false
    },
    {
      "namespace": "testorg",
      "name": "nginx",
      "description": null,
      "is_public": false,
      "kind": "image",
      "state": "NORMAL",
      "quota_report": {
        "quota_bytes": 59231659,
        "configured_quota": 104857600
      },
      "last_modified": 1651229507,
      "popularity": 0,
      "is_starred": false
    }
  ]
}

  • To view quota information in the organization details, send a GET request to the /api/v1/organization/<organization_name> endpoint: 

    $ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' 'https://<quay-server.example.com>/api/v1/organization/<organization_name>' | jq

    Example output: 

    {
  "name": "testorg",
  ...
  "quotas": [
    {
      "id": 1,
      "limit_bytes": 104857600,
      "limits": []
    }
  ],
  "quota_report": {
    "quota_bytes": 87190725,
    "configured_quota": 104857600
  }
}

To configure reject and warning thresholds for an organization quota in Red Hat Quay, you can post limit definitions to the organization quota limit API endpoint.

Procedure

  1. To set a reject limit, send a POST request to the /api/v1/organization/<organization_name>/quota/<quota_id>/limit endpoint. For example: 

    $ curl -k -X POST -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"type":"Reject","threshold_percent":80}'  https://<quay-server.example.com>/api/v1/organization/<organization_name>/quota/1/limit

    • To set a warning limit, send a POST request to the same endpoint. For example: 

      $ curl -k -X POST -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"type":"Warning","threshold_percent":50}'  https://<quay-server.example.com>/api/v1/organization/<organization_name>/quota/1/limit

To view reject and warning thresholds configured for an organization quota in Red Hat Quay, you can send a GET request to the organization quota API endpoint.

Procedure

  • View the reject and warning limits by using the /api/v1/organization/<organization_name>/quota endpoint. For example: 

    $ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json'  https://<quay-server.example.com>/api/v1/organization/<organization_name>/quota | jq

    Example output:

    [
  {
    "id": 1,
    "limit_bytes": 104857600,
    "default_config": false,
    "limits": [
      {
        "id": 2,
        "type": "Warning",
        "limit_percent": 50
      },
      {
        "id": 1,
        "type": "Reject",
        "limit_percent": 80
      }
    ],
    "default_config_exists": false
  }
]

13.6. Calculating the total registry size
Copy link

To calculate the total size of a Red Hat Quay registry, you can run an on-demand calculation from the Super User Admin Panel.

Note

This feature is done on-demand. Calculating a registry total is database intensive. Use with caution.

Prerequisites

  • You are logged in as a Red Hat Quay superuser.

Procedure

  1. On the Red Hat Quay UI, click your username Super User Admin Panel.
  2. In the navigation pane, click Manage Organizations.
  3. Click Calculate Ok.
  4. After a few minutes, depending on the size of your registry, refresh the page. The Total Registry Size is now calculated.

13.7. Permanently deleting an image tag
Copy link

In Red Hat Quay, you can permanently delete an image tag outside of the time machine window when soft deletion is not enough.

Important

Permanent tag deletion cannot be undone. Use with caution.

To permanently delete an image tag in Red Hat Quay by using the v2 UI, you can select the tag in a repository and choose Permanently Delete.

Prerequisites

  • You have set FEATURE_UI_V2 to true in your config.yaml file.

Procedure

  1. Ensure that the PERMANENTLY_DELETE_TAGS and RESET_CHILD_MANIFEST_EXPIRATION parameters are set to true in your config.yaml file. For example: 

    PERMANENTLY_DELETE_TAGS: true
RESET_CHILD_MANIFEST_EXPIRATION: true
  2. In the navigation pane, click Repositories.
  3. Click the name of the repository, for example, quayadmin/busybox.
  4. Select the check box of the image tag that you want to delete, for example, test.

  5. Click Actions Permanently Delete.

    Important

    This action is permanent and cannot be undone.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top