forked from TrueCloudLab/distribution
148 lines
5 KiB
Markdown
148 lines
5 KiB
Markdown
---
|
|
description: Setting-up a local mirror for Docker Hub images
|
|
keywords: registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced
|
|
title: Registry as a pull through cache
|
|
redirect_from:
|
|
- /engine/admin/registry_mirror/
|
|
---
|
|
|
|
## Use-case
|
|
|
|
If you have multiple instances of Docker running in your environment (e.g.,
|
|
multiple physical or virtual machines, all running the Docker daemon), each time
|
|
one of them requires an image that it doesn’t have it will go out to the
|
|
internet and fetch it from the public Docker registry. By running a local
|
|
registry mirror, you can keep most of the redundant image fetch traffic on your
|
|
local network.
|
|
|
|
### Alternatives
|
|
|
|
Alternatively, if the set of images you are using is well delimited, you can
|
|
simply pull them manually and push them to a simple, local, private registry.
|
|
|
|
Furthermore, if your images are all built in-house, not using the Hub at all and
|
|
relying entirely on your local registry is the simplest scenario.
|
|
|
|
### Gotcha
|
|
|
|
It's currently not possible to mirror another private registry. Only the central
|
|
Hub can be mirrored.
|
|
|
|
### Solution
|
|
|
|
The Registry can be configured as a pull through cache. In this mode a Registry
|
|
responds to all normal docker pull requests but stores all content locally.
|
|
|
|
## How does it work?
|
|
|
|
The first time you request an image from your local registry mirror, it pulls
|
|
the image from the public Docker registry and stores it locally before handing
|
|
it back to you. On subsequent requests, the local registry mirror is able to
|
|
serve the image from its own storage.
|
|
|
|
### What if the content changes on the Hub?
|
|
|
|
When a pull is attempted with a tag, the Registry will check the remote to
|
|
ensure if it has the latest version of the requested content. If it doesn't it
|
|
will fetch the latest content and cache it.
|
|
|
|
### What about my disk?
|
|
|
|
In environments with high churn rates, stale data can build up in the cache.
|
|
When running as a pull through cache the Registry will periodically remove old
|
|
content to save disk space. Subsequent requests for removed content will cause a
|
|
remote fetch and local re-caching.
|
|
|
|
To ensure best performance and guarantee correctness the Registry cache should
|
|
be configured to use the `filesystem` driver for storage.
|
|
|
|
## Run a Registry as a pull-through cache
|
|
|
|
The easiest way to run a registry as a pull through cache is to run the official
|
|
Registry image.
|
|
|
|
Multiple registry caches can be deployed over the same back-end. A single
|
|
registry cache will ensure that concurrent requests do not pull duplicate data,
|
|
but this property will not hold true for a registry cache cluster.
|
|
|
|
### Configure the cache
|
|
|
|
To configure a Registry to run as a pull through cache, the addition of a
|
|
`proxy` section is required to the config file.
|
|
|
|
In order to access private images on the Docker Hub, a username and password can
|
|
be supplied.
|
|
|
|
```yaml
|
|
proxy:
|
|
remoteurl: https://registry-1.docker.io
|
|
username: [username]
|
|
password: [password]
|
|
```
|
|
|
|
> **Warning**: If you specify a username and password, it's very important to
|
|
> understand that private resources that this user has access to Docker Hub will
|
|
> be made available on your mirror. **You must secure your mirror** by
|
|
> implementing authentication if you expect these resources to stay private!
|
|
|
|
> **Warning**: In order for the scheduler to clean up old entries, `delete` must
|
|
> be enabled in the registry configuration. See
|
|
> [Registry Configuration](/registry/configuration.md) for more details.
|
|
|
|
### Configure the Docker daemon
|
|
|
|
Either pass the `--registry-mirror` option when starting `dockerd` manually,
|
|
or edit `/etc/docker/daemon.json` and add the `registry-mirrors` key and value,
|
|
to make the change persistent.
|
|
|
|
```json
|
|
{
|
|
"registry-mirrors": ["https://<my-docker-mirror-host>"]
|
|
}
|
|
```
|
|
|
|
Save the file and restart Docker for the change to take effect.
|
|
|
|
> Some log messages that appear to be errors are actually informational messages.
|
|
>
|
|
> Check the `level` field to determine whether
|
|
> the message is warning you about an error or is giving you information.
|
|
> For example, this log message is informational:
|
|
>
|
|
> ```conf
|
|
> `time="2017-06-02T15:47:37Z" level=info msg="error statting local store, serving from upstream: unknown blob" go.version=go1.7.4`
|
|
> ```
|
|
>
|
|
> It's telling you that the file doesn't exist yet in the local cache and is
|
|
> being pulled from upstream.
|
|
|
|
|
|
## Use case: the China registry mirror
|
|
|
|
The URL of the registry mirror for China is `registry.docker-cn.com`. You can
|
|
pull images from this mirror just like you do for other registries by
|
|
specifying the full path, including the registry, in your `docker pull`
|
|
command, for example:
|
|
|
|
```bash
|
|
$ docker pull registry.docker-cn.com/library/ubuntu
|
|
```
|
|
|
|
You can configure the Docker daemon with the `--registry-mirror` startup
|
|
parameter:
|
|
|
|
```bash
|
|
$ docker --registry-mirror=https://registry.docker-cn.com -d
|
|
```
|
|
|
|
Or you can add "https://registry.docker-cn.com" to the `registry-mirrors`
|
|
array in `/etc/docker/daemon.json` to pull from the China registry mirror
|
|
by default.
|
|
|
|
```json
|
|
{
|
|
"registry-mirrors": ["https://registry.docker-cn.com"]
|
|
}
|
|
```
|
|
|
|
Save the file and restart Docker for the change to take effect.
|