Docker Hub introduced rate limits for image pulls earlier this month. Being the default registry for Docker images, this is one of the biggest in the ecosystem in the last few years, and it will affect not only Docker users but also Kubernetes setups.
The new limits affect free users. No more unlimited free pulls, the party is over.
- Anonymous free users: 100 container pulls every 6 hours.
- Authenticated free users: 200 container pulls every 6 hours.
- Paid accounts: unlimited.
At first, 100 pulls may sound like a lot. But think what happens when you start a Kubernetes deployment. Each pod pulls independently: if you spin up a ReplicaSet with 100 replicas, that’s 100 pulls at once.
The same thing happens when we’re doing a rolling update, a rollback, a canary release, or a blue-green deployment. As pods keep spawning, the chance of hitting the limit increases, and we face the most annoying of problems: random, unexpected, avoidable failures.
What can you do? To see if you’re affected, check if you’re pulling images from Docker Hub with the following command:
kubectl get pods --all-namespaces -ojson | jq -r '.items.spec | .containers //  += .initContainers //  | .image' | sort -u
If you see images with no registry (just the image name) or where the registry is
docker.io, you’re pulling from Docker Hub, so keep reading.
Next, check if you’re using authentication. All images should be pulled with authentication. Anonymous pulls are rate limited by IP. Even if you don’t need a lot of pulls, you may still be affected by other users sharing the network.
The bright side is that adding authentication is really easy. It only takes two steps. Here’s how to do it.
The first step is to add your Docker Hub username and password to the cluster. We can do this with kubectl. You only have to do this once per cluster.
$ kubectl create secret docker-registry my-dockerhub-account \ --docker-server=docker.io \ --docker-username=DOCKER_HUB_USERNAME \ --docker-password=DOCKER_HUB_PASSWORD
Once the secret is safely stored in Kubernetes, we only need to mention it on the deployment manifest. For this, add
imagePullSecrets in the
imagePullSecrets: - name: my-dockerhub-account
For example, if I want to run a deployment with three nginx pods, the end result would be:
apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment labels: app: nginx spec: replicas: 3 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: imagePullSecrets: - name: my-dockerhub-secret containers: - name: nginx image: nginx:1.14.2 ports: - containerPort: 80
That’s all you need. When you have the chance,
kubectl apply the new manifest to start using authentication.
I hope this helps you to prevent avoidable errors. Once authenticated, you should have a more consistent experience and a higher limit.
I’ve not heard of anyone hitting the limit yet. Docker Hub said they’ll enforce them gradually, so I’m sure it’s a matter of time until someone gets bitten by the new caps.