From 7e89a7137de5fe6b9b5466cfd176cdc9f95dd81b Mon Sep 17 00:00:00 2001 From: Craig Date: Mon, 24 Feb 2025 15:50:28 -0800 Subject: [PATCH] hub: refresh usage Signed-off-by: Craig --- .../docker-hub/{usage/pulls.md => usage.md} | 178 +++++++++++++----- content/manuals/docker-hub/usage/_index.md | 50 ----- content/manuals/docker-hub/usage/manage.md | 46 ----- .../manuals/docker-hub/usage/repositories.md | 22 --- content/manuals/subscription/details.md | 4 +- 5 files changed, 129 insertions(+), 171 deletions(-) rename content/manuals/docker-hub/{usage/pulls.md => usage.md} (69%) delete mode 100644 content/manuals/docker-hub/usage/_index.md delete mode 100644 content/manuals/docker-hub/usage/manage.md delete mode 100644 content/manuals/docker-hub/usage/repositories.md diff --git a/content/manuals/docker-hub/usage/pulls.md b/content/manuals/docker-hub/usage.md similarity index 69% rename from content/manuals/docker-hub/usage/pulls.md rename to content/manuals/docker-hub/usage.md index cd1c4d2b765..811e706a7a9 100644 --- a/content/manuals/docker-hub/usage/pulls.md +++ b/content/manuals/docker-hub/usage.md @@ -1,29 +1,61 @@ --- -description: Learn about pull usage and limits for Docker Hub. -keywords: Docker Hub, pulls, usage, limit -title: Docker Hub pull usage and limits -linkTitle: Pulls -weight: 10 +description: Learn about usage and limits for Docker Hub. +keywords: Docker Hub, limit, usage +title: Docker Hub usage and limits +linkTitle: Usage and limits +weight: 30 +aliases: + - /docker-hub/download-rate-limit/ + - /docker-hub/usage/storage/ + - /docker-hub/usage/repositories/ + - /docker-hub/usage/manage/ + --- {{% include "hub-limits.md" %}} -Unauthenticated and Docker Personal users are subject to hourly pull rate limits -on Docker Hub. In contrast, Docker Pro, Team, and Business users benefit from -unlimited pulls per hour. +Docker imposes limits for Docker Hub to ensure fair resource consumption and +maintain service quality. Understanding your usage and limits helps you manage +your usage effectively. + +## Overview of limits + +The following table provides an overview of the limits for each user type, +subject to fair use: + +| User type | Pull rate limit per hour | Number of public repositories | Number of private repositories | +|----------------------------------------|----------------------------------------|-------------------------------|--------------------------------| +| Pro, Team, or Business (authenticated) | Unlimited | Unlimited | Unlimited | +| Personal (authenticated) | 100 | Unlimited | Up to 1 | +| Unauthenticated users | 10 per IPv4 address or IPv6 /64 subnet | Not applicable | Not applicable | + +## Fair use + +When utilizing the Docker Platform, users should be aware that excessive data +transfer, pull rates, or data storage can lead to throttling, or additional +charges. To ensure fair resource usage and maintain service quality, we reserve +the right to impose restrictions or apply additional charges to accounts +exhibiting excessive data and storage consumption. + +### Abuse rate limit -The following pull usage and limits apply based on your subscription, subject to -fair use: +Docker Hub has an abuse rate limit to protect the application and +infrastructure. This limit applies to all requests to Hub properties including +web pages, APIs, and image pulls. The limit is applied per IPv4 address or per +IPv6 /64 subnet, and while the limit changes over time depending on load and +other factors, it's in the order of thousands of requests per minute. The abuse +limit applies to all users equally regardless of account level. -| User type | Pull rate limit per hour | -|--------------------------|----------------------------------------| -| Business (authenticated) | Unlimited | -| Team (authenticated) | Unlimited | -| Pro (authenticated) | Unlimited | -| Personal (authenticated) | 100 | -| Unauthenticated Users | 10 per IPv4 address or IPv6 /64 subnet | +You can differentiate between the pull rate limit and abuse rate limit by +looking at the error code. The abuse limit returns a simple `429 Too Many +Requests` response. The pull limit returns a longer error message that includes +a link to documentation. -## Pull definition +## Understand pulls + +The follow sections define a pull and how it is attributed. + +### Pull definition A pull is defined as the following: @@ -37,7 +69,7 @@ A pull is defined as the following: - A pull for a multi-arch image will count as one pull for each different architecture. -## Pull attribution +### Pull attribution Pulls from authenticated users can be attributed to either a personal or an organization @@ -55,7 +87,7 @@ Attribution is based on the following: - Single organization membership: - If the owner of the verified domain is a company and the user is part of only one organization within that - [company](../../admin/faqs/company-faqs.md#what-features-are-supported-at-the-company-level), + [company](/manuals/admin/faqs/company-faqs.md#what-features-are-supported-at-the-company-level), the pull is attributed to that specific organization. - If the user is part of only one organization, the pull is attributed to that specific organization. @@ -67,13 +99,13 @@ When pulling Docker Verified Publisher images, attribution towards rate limiting is not applied. For more details, see [Docker Verified Publisher Program](/manuals/docker-hub/repos/manage/trusted-content/dvp-program.md). -### Authentication +#### Authenticate for pull attribution -To ensure correct attribution of your pulls, you must authenticate with Docker +To attribute your pulls to you user account, you must authenticate with Docker Hub. The following sections provide information on how to sign in to Docker Hub to authenticate your pulls. -#### Docker Desktop +##### Docker Desktop If you are using Docker Desktop, you can sign in to Docker Hub from the Docker Desktop menu. @@ -81,13 +113,13 @@ Desktop menu. Select **Sign in / Create Docker ID** from the Docker Desktop menu and follow the on-screen instructions to complete the sign-in process. -#### Docker Engine +##### Docker Engine If you're using a standalone version of Docker Engine, run the `docker login` command from a terminal to authenticate with Docker Hub. For information on how to use the command, see [docker login](/reference/cli/docker/login.md). -#### Docker Swarm +##### Docker Swarm If you're running Docker Swarm, you must use the `--with-registry-auth` flag to authenticate with Docker Hub. For more information, see [Create a @@ -95,21 +127,21 @@ service](/reference/cli/docker/service/create.md#with-registry-auth). If you are using a Docker Compose file to deploy an application stack, see [docker stack deploy](/reference/cli/docker/stack/deploy.md). -#### GitHub Actions +##### GitHub Actions If you're using GitHub Actions to build and push Docker images to Docker Hub, see [login action](https://github.com/docker/login-action#dockerhub). If you are using another Action, you must add your username and access token in a similar way for authentication. -#### Kubernetes +##### Kubernetes If you're running Kubernetes, follow the instructions in [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) for information on authentication. -#### Third-party platforms +##### Third-party platforms If you're using any third-party platforms, follow your provider’s instructions on using registry authentication. @@ -132,32 +164,15 @@ If you're using any third-party platforms, follow your provider’s instructions - [LayerCI](https://layerci.com/docs/advanced-workflows#logging-in-to-docker) - [TeamCity](https://www.jetbrains.com/help/teamcity/integrating-teamcity-with-docker.html#Conforming+with+Docker+download+rate+limits) -## View monthly pulls and included usage +## Monitor usage -You can view your monthly pulls on the [Usage page](https://hub.docker.com/usage/pulls) in Docker Hub. +Learn how to monitor your usage in the following sections. -On that page, you can also send a report to your email that contains a comma -separated file with the following detailed information. +### View pull rate and limit -| CSV column | Definition | Usage guidance | -|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `datehour` | The date and hour (`yyyy/mm/dd/hh`) of the pull that resulted in the data transfer. | This helps in identifying peak usage times and patterns. | -| `user_name` | The Docker ID of the user that pulled the image | This lets organization owners track data consumption per user and manage resources effectively. | -| `repository` | The name of the repository of the image that was pulled. | This lets you identify which repositories are most frequently accessed and consume most of the data transfer. | -| `access_token_name` | Name of the access token that was used for authentication with Docker CLI. `generated` tokens are automatically generated by the Docker client when a user signs in. | Personal access tokens are usually used to authenticate automated tools (Docker Desktop, CI/CD tools, etc.). This is useful for identifying which automated system issued the pull. | -| `ips` | The IP address that was used to pull the image. This field is aggregated, so more than one IP address may appear, representing all the IPs used to pull an image within the same date and hour. | This helps you understand the origin of the data transfer, which is useful for diagnosing and identifying patterns in automated or manual pulls. | -| `repository_privacy` | The privacy state of the image repository that was pulled. This can either be `public` or `private`. | This distinguishes between public and private repositories to identify which data transfer threshold the pull impacts. | -| `tag` | The tag for the image. The tag is only available if the pull included a tag. | This helps in identifying the image. Tags are often used to identify specific versions or variants of an image. | -| `digest` | The unique image digest for the image. | This helps in identifying the image. | -| `version_checks` | The number of version checks accumulated for the date and hour of each image repository. Depending on the client, a pull can do a version check to verify the existence of an image or tag without downloading it. | This helps identify the frequency of version checks, which you can use to analyze usage trends and potential unexpected behaviors. | -| `pulls` | The number of pulls accumulated for the date and hour of each image repository. | This helps identify the frequency of repository pulls, which you can use to analyze usage trends and potential unexpected behaviors. | - -## View hourly pull rate and limit - -The pull rate limit is calculated on a per hour basis. There is no pull rate -limit for users or automated systems with a paid subscription. Unauthenticated -and Docker Personal users using Docker Hub will experience rate limits on image -pulls. +Rate limits apply to image pulls by unauthenticated and Docker Personal users. +There is no pull rate limit for users or automated systems with a paid +subscription. When you issue a pull and you are over the limit, Docker Hub returns a `429` response code with the following body when the manifest is requested: @@ -215,3 +230,64 @@ To view your current pull rate and limit: paid Docker plan. Pulling that image won't count toward pull rate limits if you don't see these headers. +### View monthly usage + +For authenticated users, you can view your usage on the [Usage +page](https://hub.docker.com/usage/pulls) in Docker Hub. + +On the **Pulls** tab, you can also send a report to your email that contains a comma +separated file with the following detailed information. + +| CSV column | Definition | Usage guidance | +|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `datehour` | The date and hour (`yyyy/mm/dd/hh`) of the pull that resulted in the data transfer. | This helps in identifying peak usage times and patterns. | +| `user_name` | The Docker ID of the user that pulled the image | This lets organization owners track data consumption per user and manage resources effectively. | +| `repository` | The name of the repository of the image that was pulled. | This lets you identify which repositories are most frequently accessed and consume most of the data transfer. | +| `access_token_name` | Name of the access token that was used for authentication with Docker CLI. `generated` tokens are automatically generated by the Docker client when a user signs in. | Personal access tokens are usually used to authenticate automated tools (Docker Desktop, CI/CD tools, etc.). This is useful for identifying which automated system issued the pull. | +| `ips` | The IP address that was used to pull the image. This field is aggregated, so more than one IP address may appear, representing all the IPs used to pull an image within the same date and hour. | This helps you understand the origin of the data transfer, which is useful for diagnosing and identifying patterns in automated or manual pulls. | +| `repository_privacy` | The privacy state of the image repository that was pulled. This can either be `public` or `private`. | This distinguishes between public and private repositories to identify which data transfer threshold the pull impacts. | +| `tag` | The tag for the image. The tag is only available if the pull included a tag. | This helps in identifying the image. Tags are often used to identify specific versions or variants of an image. | +| `digest` | The unique image digest for the image. | This helps in identifying the image. | +| `version_checks` | The number of version checks accumulated for the date and hour of each image repository. Depending on the client, a pull can do a version check to verify the existence of an image or tag without downloading it. | This helps identify the frequency of version checks, which you can use to analyze usage trends and potential unexpected behaviors. | +| `pulls` | The number of pulls accumulated for the date and hour of each image repository. | This helps identify the frequency of repository pulls, which you can use to analyze usage trends and potential unexpected behaviors. + +## Optimize usage + +Use the following steps to help optimize and manage your Docker Hub usage for +both individuals and organizations: + +1. [View your Docker Hub usage](https://hub.docker.com/usage). + +2. Use the Docker Hub usage data to identify which accounts consume the most + data, determine peak usage times, and identify which images are related to + the most data usage. In addition, look for usage trends, such as the + following: + + - Inefficient pull behavior: Identify frequently accessed repositories to + assess whether you can optimize caching practices or consolidate usage to + reduce pulls. + - Inefficient automated systems: Check which automated tools, such as CI/CD + pipelines, may be causing higher pull rates, and configure them to avoid + unnecessary image pulls. + +3. Optimize image pulls by: + + - Using caching: Implement local image caching via + [mirroring](/docker-hub/mirror/) or within your CI/CD pipelines to reduce + redundant pulls. + - Automating manual workflows: Avoid unnecessary pulls by configuring automated + systems to pull only when a new version of an image is available. + +4. Optimize your storage by: + + - Regularly auditing and [removing entire repositories](/manuals/docker-hub/repos/delete.md) with untagged, unused, or outdated images. + - Using [Image Management](/manuals/docker-hub/repos/manage/hub-images/manage.md) to remove stale and outdated images within a repository. + +5. For organizations, monitor and enforce organizational policies by doing the + following: + + - Routinely [view Docker Hub usage](https://hub.docker.com/usage) to monitor usage. + - [Enforce sign-in](/security/for-admins/enforce-sign-in/) to ensure that you + can monitor the usage of your users and users receive higher usage limits. + - Look for duplicate user accounts in Docker and remove accounts from your organization + as needed. \ No newline at end of file diff --git a/content/manuals/docker-hub/usage/_index.md b/content/manuals/docker-hub/usage/_index.md deleted file mode 100644 index e543d267855..00000000000 --- a/content/manuals/docker-hub/usage/_index.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -description: Learn about usage and limits for Docker Hub. -keywords: Docker Hub, limit, usage -title: Docker Hub usage and limits -linkTitle: Usage and limits -weight: 30 -aliases: - /docker-hub/download-rate-limit/ ---- - -{{% include "hub-limits.md" %}} - -The following table provides an overview of the included usage and limits for each -user type, subject to fair use: - - -| User type | Pull rate limit per hour | Number of public repositories | Number of private repositories | -|--------------------------|----------------------------------------|---------------------|----------------------| -| Business (authenticated) | Unlimited | Unlimited | Unlimited | -| Team (authenticated) | Unlimited | Unlimited | Unlimited | -| Pro (authenticated) | Unlimited | Unlimited | Unlimited | -| Personal (authenticated) | 100 | Unlimited | Up to 1 | -| Unauthenticated users | 10 per IPv4 address or IPv6 /64 subnet | Not applicable | Not applicable | - -For more details, see the following: - -- [Pull usage and limits](./pulls.md) -- [Docker Hub repositories](./repositories.md) - -## Fair use - -When utilizing the Docker Platform, users should be aware that excessive data -transfer, pull rates, or data storage can lead to throttling, or additional -charges. To ensure fair resource usage and maintain service quality, we reserve -the right to impose restrictions or apply additional charges to accounts -exhibiting excessive data and storage consumption. - -### Abuse rate limit - -Docker Hub has an abuse rate limit to protect the application and -infrastructure. This limit applies to all requests to Hub properties including -web pages, APIs, and image pulls. The limit is applied per IPv4 address or per -IPv6 /64 subnet, and while the limit changes over time depending on load and -other factors, it's in the order of thousands of requests per minute. The abuse -limit applies to all users equally regardless of account level. - -You can differentiate between the pull rate limit and abuse rate limit by -looking at the error code. The abuse limit returns a simple `429 Too Many -Requests` response. The pull limit returns a longer error message that includes -a link to documentation. diff --git a/content/manuals/docker-hub/usage/manage.md b/content/manuals/docker-hub/usage/manage.md deleted file mode 100644 index 14a01e7187f..00000000000 --- a/content/manuals/docker-hub/usage/manage.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -description: Learn how to optimize and manage your Docker Hub usage. -keywords: Docker Hub, limit, usage -title: Best practices for optimizing Docker Hub usage -linkTitle: Optimize usage -weight: 40 ---- - -Use the following steps to help optimize and manage your Docker Hub usage for -both individuals and organizations: - -1. [View your Docker Hub usage](https://hub.docker.com/usage). - -2. Use the Docker Hub usage data to identify which accounts consume the most - data, determine peak usage times, and identify which images are related to - the most data usage. In addition, look for usage trends, such as the - following: - - - Inefficient pull behavior: Identify frequently accessed repositories to - assess whether you can optimize caching practices or consolidate usage to - reduce pulls. - - Inefficient automated systems: Check which automated tools, such as CI/CD - pipelines, may be causing higher pull rates, and configure them to avoid - unnecessary image pulls. - -3. Optimize image pulls by: - - - Using caching: Implement local image caching via - [mirroring](/docker-hub/mirror/) or within your CI/CD pipelines to reduce - redundant pulls. - - Automating manual workflows: Avoid unnecessary pulls by configuring automated - systems to pull only when a new version of an image is available. - -4. Optimize your storage by: - - - Regularly auditing and [removing entire repositories](../repos/delete.md) with untagged, unused, or outdated images. - - Using [Image Management](../repos/manage/hub-images/manage.md) to remove stale and outdated images within a repository. - -5. For organizations, monitor and enforce organizational policies by doing the - following: - - - Routinely [view Docker Hub usage](https://hub.docker.com/usage) to monitor usage. - - [Enforce sign-in](/security/for-admins/enforce-sign-in/) to ensure that you - can monitor the usage of your users and users receive higher usage limits. - - Look for duplicate user accounts in Docker and remove accounts from your organization - as needed. \ No newline at end of file diff --git a/content/manuals/docker-hub/usage/repositories.md b/content/manuals/docker-hub/usage/repositories.md deleted file mode 100644 index 5ea200845ba..00000000000 --- a/content/manuals/docker-hub/usage/repositories.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -description: Learn about storage usage limits for Docker Hub. -keywords: Docker Hub, usage, storage, repository -title: Docker Hub repositories -linkTitle: Number of repositories -weight: 20 -aliases: - - /docker-hub/usage/storage/ ---- - -The following number of repositories apply based on your subscription, subject to fair use: - -| Plan | Number of public repositories | Number of private repositories | -|----------|-------------------------------|----------------------------| -| Personal | Unlimited | Up to 1 private repository | -| Pro | Unlimited | Unlimited | -| Team | Unlimited | Unlimited | -| Business | Unlimited | Unlimited | - -## View storage usage and repositories - -You can view your storage usage on the [Usage page](https://hub.docker.com/usage/storage) in Docker Hub. diff --git a/content/manuals/subscription/details.md b/content/manuals/subscription/details.md index 29eaa2f0b61..484f3b6e998 100644 --- a/content/manuals/subscription/details.md +++ b/content/manuals/subscription/details.md @@ -185,7 +185,7 @@ Legacy Docker Pro includes: - Unlimited [collaborators](/docker-hub/repos/manage/access/#collaborators) for public repositories at no cost per month. - Access to [Legacy Docker Scout Free](#legacy-docker-scout-free) to get started with software supply chain security. - Unlimited private repositories -- 5000 image [pulls per day](/manuals/docker-hub/usage/pulls.md) +- 5000 image [pulls per day](/manuals/docker-hub/usage.md) - [Auto Builds](/docker-hub/builds/) with 5 concurrent builds - 300 [Vulnerability Scans](/docker-hub/vulnerability-scanning/) @@ -216,7 +216,7 @@ Legacy Docker Team includes: - Unlimited teams - [Auto Builds](/docker-hub/builds/) with 15 concurrent builds - Unlimited [Vulnerability Scanning](/docker-hub/vulnerability-scanning/) -- 5000 image [pulls per day](/manuals/docker-hub/usage/pulls.md) for each team member +- 5000 image [pulls per day](/manuals/docker-hub/usage.md) for each team member There are also advanced collaboration and management tools, including organization and team management with [Role Based Access Control (RBAC)](/security/for-admins/roles-and-permissions/), [activity logs](/admin/organization/activity-logs/), and more.