From c35ec35dc00ae6a5401b2f0981a4e4c62a5e9dbe Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 17 Jul 2025 12:05:11 -0600 Subject: [PATCH 1/2] edit info on avoiding docker hub rate limits --- docs/enterprise/image-registry-rate-limits.md | 92 ++++++++++++++++--- .../kots-cli-docker-ensure-secret.md | 5 +- sidebars.js | 2 +- 3 files changed, 86 insertions(+), 13 deletions(-) diff --git a/docs/enterprise/image-registry-rate-limits.md b/docs/enterprise/image-registry-rate-limits.md index 6a50497d5e..86e08af34c 100644 --- a/docs/enterprise/image-registry-rate-limits.md +++ b/docs/enterprise/image-registry-rate-limits.md @@ -6,24 +6,94 @@ This topic describes how to avoid rate limiting for anonymous and free authentic On November 20, 2020, rate limits for anonymous and free authenticated use of Docker Hub went into effect. Anonymous and Free Docker Hub users are limited to 100 and 200 container image pull requests per six hours, respectively. -Docker Pro and Docker Team accounts continue to have unlimited access to pull container images from Docker Hub. +Docker Pro and Docker Team accounts continue to have unlimited access to pull container images from Docker Hub. For more information on rate limits, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website. -For more information on rate limits, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website. +If your application has public Docker Hub images that are rate limited, then an error occurs when the rate limit is reached. To avoid these errors, your users can pass a Docker Hub username and password to the `kots docker ensure-secret` command. This creates an `-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information about this command, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits). -If the application that you are installing or upgrading has public Docker Hub images that are rate limited, then an error occurs when the rate limit is reached. +If you are deploying a Helm chart with Docker Hub images that could be rate limited, any Pod definitions in your Helm chart templates that reference the rate-limited image must be updated to access the `-kotsadm-dockerhub` pull secret. + +## Inject the Docker Hub Pull Secret + +For installations with HelmChart v2, you need to configure the `values` key of the HelmChart v2 custom resource to ensure that the KOTS Docker Hub pull secret is added to any Pod definitions that reference rate-limited Docker Hub images. This allows your users to run the `kots docker ensure-secret` command. + +To configure the HelmChart v2 custom resource: + +1. For each HelmChart v2 resource in your release, configure the [`values`](/reference/custom-resource-helmchart-v2#values) key to add a new value with the KOTS `APP_SLUG-kotsadm-dockerhub` pull secret, where `APP_SLUG` is your unique application slug. + + **Example:** + + ```yaml + # kots.io/v1beta2 HelmChart custom resource + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: + values: + image: + registry: docker.io + repository: your-org/example-docker-hub-image + # Add a new pullSecrets array with the -kotsadm-dockerhub pull secret + pullSecrets: + - name: your-app-slug-kotsadm-dockerhub + ``` + +1. Ensure that there is a matching value in each of the corresponding Helm chart `values.yaml` files. + + **Example:** + + ```yaml + # Helm chart values.yaml file + image: + registry: docker.io + repository: your-org/your-docker-hub-image + # include the new pullSecrets array + pullSecrets: [] + ``` + +1. In your Helm chart templates, update any Pod definitions that reference rate-limited Docker Hub images to include the pull secret. + + **Example:** + + ```yaml + apiVersion: v1 + kind: Pod + metadata: + name: example + spec: + containers: + - name: example + image: {{ .Values.image.registry }}/{{ .Values.image.repository }} + # the kotsadm-dockerhub pull secret is accessed from + # the Helm values and added to this array + {{- with .Values.image.pullSecrets }} + imagePullSecrets: + {{- toYaml . | nindent 2 }} + {{- end }} + ``` ## Provide Docker Hub Credentials -To avoid errors caused by reaching the Docker Hub rate limit, a Docker Hub username and password can be passed to the `kots docker ensure-secret` command. The Docker Hub username and password are used only to increase rate limits and do not need access to any private repositories on Docker Hub. +To create an image pull secret for pulling Docker Hub images and apply the secret to all + +1. Run the following command to create an image pull secret that KOTS can use when pulling Docker Hub images: -Example: + ```bash + kubectl kots docker ensure-secret --dockerhub-username USERNAME --dockerhub-password PASSWORD --namespace NAMESPACE + ``` -```bash -kubectl kots docker ensure-secret --dockerhub-username sentrypro --dockerhub-password password --namespace sentry-pro -``` + Where: + * `USERNAME` is the username for the Docker Pro or Docker Team account + * `PASSWORD` is the password for the account + :::note + The Docker Hub username and password are used only to increase rate limits and do not need access to any private repositories on Docker Hub. + ::: + * `NAMESPACE` is the namespace in the cluster where the application is installed. For Embedded Cluster installations, the application is installed in the `kotsadm` namespace by default. -The `kots docker ensure-secret` command creates an image pull secret that KOTS can use when pulling images. + For more information, see [docker ensure-secret](/reference/kots-cli-docker-ensure-secret) in the KOTS CLI documentation. -KOTS then creates a new release sequence for the application to apply the image pull secret to all Kubernetes manifests that have images. After running the `kots docker ensure-secret` command, deploy this new release sequence either from the Admin Console or the KOTS CLI. + After `kots docker ensure-secret` runs, KOTS automatically creates a new release sequence for the application. -For more information, see [docker ensure-secret](/reference/kots-cli-docker-ensure-secret) in the KOTS CLI documentation. +1. Deploy the new release sequence either from the Admin Console or the KOTS CLI. + + This ensures the image pull secret is applied to all Pod definitions that reference . \ No newline at end of file diff --git a/docs/reference/kots-cli-docker-ensure-secret.md b/docs/reference/kots-cli-docker-ensure-secret.md index 2e6271ec1a..89c2f93db2 100644 --- a/docs/reference/kots-cli-docker-ensure-secret.md +++ b/docs/reference/kots-cli-docker-ensure-secret.md @@ -1,10 +1,13 @@ # docker ensure-secret -Creates an image pull secret for Docker Hub that the Admin Console can utilize to avoid [rate limiting](/enterprise/image-registry-rate-limits). +Creates an image pull secret for Docker Hub that the Admin Console can utilize to avoid rate limiting. + The credentials are validated before creating the image pull secret. Running this command creates a new application version, based on the latest version, with the new image pull secret added to all Kubernetes manifests that have images. In order for this secret to take effect to avoid rate limiting, the new version must be deployed. +For more information, see [Avoid Docker Hub Rate Limits](/enterprise/image-registry-rate-limits). + ### Usage ```bash diff --git a/sidebars.js b/sidebars.js index ec652660b4..1624598949 100644 --- a/sidebars.js +++ b/sidebars.js @@ -408,9 +408,9 @@ const sidebars = { label: 'Configure Local Image Registries', items: [ 'enterprise/image-registry-settings', - 'enterprise/image-registry-rate-limits', ], }, + 'enterprise/image-registry-rate-limits', 'enterprise/updating-licenses', { type: 'category', From cbd1a6bb336e7d54317af6f3f3cc69d401db402c Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 18 Jul 2025 12:10:30 -0600 Subject: [PATCH 2/2] edits --- docs/enterprise/image-registry-rate-limits.md | 80 ++++++++++--------- 1 file changed, 44 insertions(+), 36 deletions(-) diff --git a/docs/enterprise/image-registry-rate-limits.md b/docs/enterprise/image-registry-rate-limits.md index 86e08af34c..bfd83a8727 100644 --- a/docs/enterprise/image-registry-rate-limits.md +++ b/docs/enterprise/image-registry-rate-limits.md @@ -1,44 +1,28 @@ # Avoid Docker Hub Rate Limits -This topic describes how to avoid rate limiting for anonymous and free authenticated use of Docker Hub by providing a Docker Hub username and password to the `kots docker ensure-secret` command. +This topic describes how to avoid rate limiting for Docker Hub images used by your application. + +The information in this topic applies to installations with a Replicated installer (Embedded Cluster, KOTS existing cluster, kURL). ## Overview On November 20, 2020, rate limits for anonymous and free authenticated use of Docker Hub went into effect. Anonymous and Free Docker Hub users are limited to 100 and 200 container image pull requests per six hours, respectively. -Docker Pro and Docker Team accounts continue to have unlimited access to pull container images from Docker Hub. For more information on rate limits, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website. - -If your application has public Docker Hub images that are rate limited, then an error occurs when the rate limit is reached. To avoid these errors, your users can pass a Docker Hub username and password to the `kots docker ensure-secret` command. This creates an `-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information about this command, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits). +Docker Pro and Docker Team accounts continue to have unlimited access to pull container images from Docker Hub. For more information, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website. -If you are deploying a Helm chart with Docker Hub images that could be rate limited, any Pod definitions in your Helm chart templates that reference the rate-limited image must be updated to access the `-kotsadm-dockerhub` pull secret. +If your application has Docker Hub images that are rate limited, then an error occurs when the rate limit is reached. To avoid rate limiting errors, your users can generate a Docker Hub pull secret (`-kotsadm-dockerhub`) by passing credentials for a Docker Pro and Docker Team with the `kots docker ensure-secret` command. -## Inject the Docker Hub Pull Secret +## Update Your Helm Chart to Access the KOTS Docker Hub Pull Secret -For installations with HelmChart v2, you need to configure the `values` key of the HelmChart v2 custom resource to ensure that the KOTS Docker Hub pull secret is added to any Pod definitions that reference rate-limited Docker Hub images. This allows your users to run the `kots docker ensure-secret` command. +If you are distributing a Helm chart with one or more rate-limited Docker Hub images, any Pod definitions in your chart templates that reference the images must be updated to access the `-kotsadm-dockerhub` pull secret. You can do this by configuring the HelmChart `values` key so that KOTS adds the pull secret in your Helm values during deployment, then updating your chart templates to access the value. -To configure the HelmChart v2 custom resource: +:::note +Skip this task if you distribute your chart with the [HelmChart v1 (Deprecated)](/reference/custom-resource-helmchart) resource, or if your application is not packaged with Helm. +::: -1. For each HelmChart v2 resource in your release, configure the [`values`](/reference/custom-resource-helmchart-v2#values) key to add a new value with the KOTS `APP_SLUG-kotsadm-dockerhub` pull secret, where `APP_SLUG` is your unique application slug. +To access the `-kotsadm-dockerhub` pull secret in your Helm chart: - **Example:** - - ```yaml - # kots.io/v1beta2 HelmChart custom resource - apiVersion: kots.io/v1beta2 - kind: HelmChart - metadata: - name: samplechart - spec: - values: - image: - registry: docker.io - repository: your-org/example-docker-hub-image - # Add a new pullSecrets array with the -kotsadm-dockerhub pull secret - pullSecrets: - - name: your-app-slug-kotsadm-dockerhub - ``` - -1. Ensure that there is a matching value in each of the corresponding Helm chart `values.yaml` files. +1. In your Helm chart `values.yaml` file, add a value for the KOTS Docker Hub pull secret. **Example:** @@ -72,11 +56,39 @@ To configure the HelmChart v2 custom resource: {{- end }} ``` -## Provide Docker Hub Credentials +1. If you deploy your application as multiple Helm charts, repeat these steps for each chart that references rate-limited Docker Hub images. + +1. Package the chart(s) and add them to a new release. + +1. In the [`values`](/reference/custom-resource-helmchart-v2#values) key of each [HelmChart v2](/reference/custom-resource-helmchart-v2) resource in the release, add a value with the same name as the one you added to the corresponding chart's `values.yaml`. Set this new value to the `APP_SLUG-kotsadm-dockerhub` pull secret, where `APP_SLUG` is the unique slug for your application. -To create an image pull secret for pulling Docker Hub images and apply the secret to all + **Example:** -1. Run the following command to create an image pull secret that KOTS can use when pulling Docker Hub images: + ```yaml + # HelmChart v2 custom resource + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: + values: + image: + registry: docker.io + repository: your-org/example-docker-hub-image + # Add a new pullSecrets array with the -kotsadm-dockerhub pull secret + pullSecrets: + - name: your-app-slug-kotsadm-dockerhub + ``` + +1. Promote the release and install in a development environment. Continue to [Generate the KOTS Docker Hub Pull Secret](#gen-pull-secret) below to test your changes. + +## Generate the KOTS Docker Hub Pull Secret {#gen-pull-secret} + +Your end users can pass a username and password for a Docker Hub Pro or Team account using the [`kots docker ensure-secret`](/reference/kots-cli-docker-ensure-secret) command. KOTS uses these credentials to create a Docker Hub image pull secret. + +To generate the Docker Hub image pull secret: + +1. In the cluster where the application is installed, run the following command to generate the pull secret: ```bash kubectl kots docker ensure-secret --dockerhub-username USERNAME --dockerhub-password PASSWORD --namespace NAMESPACE @@ -92,8 +104,4 @@ To create an image pull secret for pulling Docker Hub images and apply the secre For more information, see [docker ensure-secret](/reference/kots-cli-docker-ensure-secret) in the KOTS CLI documentation. - After `kots docker ensure-secret` runs, KOTS automatically creates a new release sequence for the application. - -1. Deploy the new release sequence either from the Admin Console or the KOTS CLI. - - This ensures the image pull secret is applied to all Pod definitions that reference . \ No newline at end of file +1. Deploy the new version either from the Admin Console or the KOTS CLI. \ No newline at end of file