Docker 開源專案之 registry

阿新 • • 發佈：2019-01-18

在部署 registry 之前需要現在主機上安裝 Docker。registry 實際上就是執行在 Docker 中的 registry 映象的例項。

本主題提供關於部署和配置 registry 的基本資訊。要檢視配置選項列表，請參考配置手冊。

1. 執行本地 registry

使用下面命令來啟動 registry 容器：

$ docker run -d -p 5000:5000 --restart=always --name registry registry:2

registry 現在可以使用了。

警告：前幾個示例顯示的 registry 配置僅適用於測試環境。生產環境的 registry 必須受 TLS 保護，並且應該使用訪問控制機制。繼續閱讀下一篇 registry 配置指南以在生產環境中部署 registry。

2. 從 Docker Hub 複製映象到 registry

可以從 Docker Hub 中提取映象並將其推送到你的 registry。以下示例從 Docker Hub 中取出 ubuntu:16.04 映象，並將其重新標記為 my-ubuntu，然後將其放入本地 registry。最後，刪除本地的 ubuntu:16.04 和 my-ubuntu 映象，並從本地 registry 中取出 my-ubuntu 映象。

1. 從 Docker Hub 中取出 `ubuntu:16.04` 映象

$ docker pull ubuntu:16.04

2. 為映象新增標籤 `localhost:5000/my-ubuntu`

。這會會已經存在的映象建立附加標籤。標籤第一部分是主機名和埠號，執行 push 操作時 Docker 將其解析為 registry 的位置。

$ docker tag ubuntu:16.04 localhost:5000/my-ubuntu

3. 上傳映象到執行在 `localhost:5000` 的本地 registry：

$ docker push localhost:5000/my-ubuntu

4. 刪除本地快取中的 `ubuntu:16.04` 和 `my-ubuntu` 映象

刪除後，可以測試從你的本地 registry 中獲取映象。這不會刪除你的 registry 中的 localhost:5000/my-ubuntu

映象。

$ docker image remove ubuntu:16.04
$ docker image remove localhost:5000/my-ubuntu

5. 從你的本地 registry 中獲取 `localhost:5000/my-ubuntu` 映象

$ docker pull localhost:5000/my-ubuntu

3. 停止本地 registry

類似停止其他容器，通過 docker container stop 命令可以停止本地 registry：

$ docker container stop registry

通過 docker container rm 命令可以刪除容器：

$ docker container stop registry && docker container rm -v registry

4. 基本配置

要配置容器，可以將附加選項或修改選項傳遞給 docker run 命令。

下面提供了配置 registry 的基本指導原則。更多詳細資訊，請參閱 registry 配置參考。

4.1 自動啟動 registry

如果你希望將 registry 用作永久性基礎架構的一部分，則應將其設定為在 Docker 重新啟動或退出時自動重新啟動。本示例使用 --restart always 標誌為 registry 設定重新啟動策略。

$ docker run -d \
  -p 5000:5000 \
  --restart=always \
  --name registry \
  registry:2

4.2 自定義釋出的埠

如果埠 5000 已經被佔用，或者你想執行多個本地 registry 來分隔關注的區域，則可以自定義 registry 的埠。下面的示例在埠 5001 上執行 registry，並將其命名為 registry-test。請記住，-p 值的第一部分是主機埠，第二部分是容器內的埠。在容器中，registry 預設在埠 5000 上監聽。

$ docker run -d \
  -p 5001:5000 \
  --name registry-test \
  registry:2

如果要在容器中更改 registry 監聽的埠（If you want to change the port the registry listens on within the container），可以使用環境變數 REGISTRY_HTTP_ADDR 來更改它。此命令使 registry 監聽容器內的埠 5001：

$ docker run -d \
  -e REGISTRY_HTTP_ADDR=0.0.0.0:5001 \
  -p 5001:5001 \
  --name registry-test \
  registry:2

5. 儲存自定義

5.1 自定義儲存位置

預設情況下，registry 資料在主機檔案系統上作為 docker卷持久儲存。如果要將 registry 內容儲存在主機檔案系統上的特定位置，例如掛載到特定目錄的 SSD 或 SAN ，則可以使用繫結掛載。繫結掛載更依賴於 Docker 主機的檔案系統佈局，但在許多情況下效能更高。下面的示例將主機的 /mnt/registry 目錄繫結到 registry 容器的 /var/lib/registry/ 目錄中。

$ docker run -d \
  -p 5000:5000 \
  --restart=always \
  --name registry \
  -v /mnt/registry:/var/lib/registry \
  registry:2

5.2 自定義儲存後端

預設情況下，registry 將其資料儲存在本地檔案系統中，無論你是使用繫結掛載還是使用卷。可以使用儲存驅動程式將 registry 資料儲存在 Amazon S3 bucket，Google Cloud Platform 或其他儲存後端中。更多資訊，請參閱儲存配置選項。

6. 執行可從外部訪問的 registry

執行僅在本地主機上可訪問的 registry 具有有限的用處。為了使你的 registry 能夠被外部主機訪問，必須先開啟 TLS。

下面的示例在下一小節執行 registry 作為服務中進行了擴充套件。

6.1 獲取證書

這些例子假設如下：

你的註冊網址是 https://myregistry.domain.com/。
你的 DNS，路由和防火牆設定允許通過埠 443 訪問 registry 所在主機。
你已經從認證中心（certificate authority，CA）獲得證書。

如果你已獲得中間證書，請參閱本小節最後一部分使用中間證書。

1. 建立證書目錄

$ mkdir -p certs

將 .crt 和 .key 檔案從 CA 複製到 certs 目錄中。以下步驟假定這些檔案被命名為 domain.crt 和 domain.key。

2. 如果 registry 正在執行，則停止 registry

$ docker container stop registry

3. 重新啟動 registry

指示 registry 使用 TLS 證書。該命令將 certs/ 目錄繫結到容器中的 /cert/ 目錄，並設定環境變數來告訴容器在哪裡找到 domain.crt 和 domain.key 檔案。registry 在埠 443 上執行，即預設的 HTTPS 埠。

$ docker run -d \
  --restart=always \
  --name registry \
  -v `pwd`/certs:/certs \
  -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  -p 443:443 \
  registry:2

4. Docker 客戶端現在可以使用外部地址從 registry 中下載上傳映象：

$ docker pull ubuntu:16.04
$ docker tag ubuntu:16.04 myregistry.domain.com/my-ubuntu
$ docker push myregistry.domain.com/my-ubuntu
$ docker pull myregistry.domain.com/my-ubuntu

使用中間證書

證書頒發者可能會提供中間證書。在這種情況下，必須將你的證書與中間證書連線起來形成一個證書包（certificate bundle）。可以使用 cat 命令執行此操作：

cat domain.crt intermediate-certificates.pem > certs/domain.crt

就像在前面的示例中使用 domain.crt 檔案一樣，可以使用 certificate bundle。

6.2 對 Let’s Encrypt 的支援

6.3 使用不安全的 registry（僅適合測試環境）

可以使用自簽名證書，或者不安全地使用 registry。除非你已為自簽名證書設定驗證，否則這僅用於測試。請參閱執行不安全的登錄檔。

7. Run the registry as a service

Swarm 服務相對於獨立容器有幾個優勢。他們使用宣告式模型（declarative model），這意味著你定義了所需的狀態，並且 Docker 可以使你的服務保持在該狀態。服務提供自動負載均衡擴充套件，以及控制服務分佈的能力等優勢。服務還允許你在 secrets 中儲存敏感資料，例如 TLS 證書。

你使用的儲存後端決定你是使用完全伸縮的服務還是僅使用單個節點或節點約束的服務。

如果使用分散式儲存驅動程式（如 Amazon S3），則可以使用完全複製的服務（a fully replicated service）。每個工作人員都可以寫入儲存後端，而不會導致寫入衝突。
如果使用本地繫結掛載或卷，則每個工作節點都會寫入其自己的儲存位置，這意味著每個 registry 都包含一個不同的資料集。可以通過使用單副本服務（single-replica service）和節點約束來解決此問題，以確保只有一個工作節點正在寫入繫結掛載。

以下示例將 registry 作為單副本服務啟動，該服務可通過任何 swarm 節點的 80 埠訪問。假定你使用的是與前面示例中相同的 TLS 證書。

首先，將 TLS 證書和金鑰儲存為 secrets：

$ docker secret create domain.crt certs/domain.crt

$ docker secret create domain.key certs/domain.key

接下來，將標籤新增到要執行 registry 的節點。可以使用 docker node ls 獲取節點的名稱。用下面的 node1 替換節點的名稱。

$ docker node update --label-add registry=true node1

然後建立服務，授予其訪問這兩個 secrets 的許可權，並將其限制為僅在具有標籤 registry=true 的節點上執行。除了約束之外，還指定一次只能執行一個副本。該示例將 swarm 節點上的 /mnt/registry 繫結掛載到容器中的 /var/lib/registry/。繫結掛載依賴於預先存在的源目錄，因此確保 node1 上存在 /mnt/registry。在執行以下 docker service create 命令之前，可能需要建立它。

預設情況下，secrets 在 /run/secrets/<secret-name> 處掛載到服務中。

$ docker service create \
  --name registry \
  --secret domain.crt \
  --secret domain.key \
  --constraint 'node.labels.registry==true' \
  --mount type=bind,src=/mnt/registry,dst=/var/lib/registry \
  -e REGISTRY_HTTP_ADDR=0.0.0.0:80 \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/run/secrets/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/run/secrets/domain.key \
  --publish published=80,target=80 \
  --replicas 1 \
  registry:2

可以訪問任何 swarm 節點的 80 埠上的服務。Docker 將請求傳送到正在執行該服務的節點。

8. 負載均衡的考慮

人們可能想要使用負載均衡器分配負載，終止 TLS 或提供高可用性。雖然完整的負載均衡設定不在本文件的範圍內，但有一些注意事項可以使該過程更加流暢。

最重要的方面是，負載均衡的 registry 叢集必須共享相同的資源。對於當前版本的 registry，這意味著以下內容必須相同：

儲存驅動程式
HTTP Secret
Redis 快取（如果已配置）

上述任何差異都會導致服務請求出現問題。例如，如果使用的是檔案系統驅動程式，則所有 registry 例項都必須能夠訪問同一臺計算機上的相同檔案系統根目錄。對於其他驅動程式（如 S3 或 Azure），它們應該訪問相同的資源並共享相同的配置。HTTP Secret 協調上傳（The HTTP Secret coordinates uploads），跨例項也必須相同。可以配置不同的 redis 例項（編寫本文時），但如果例項不共享，則不是最優的，因為此時會導致更多的請求傳送到後端伺服器而不是使用 redis 快取。

8.1 重要/必需的 HTTP 頭

正確獲取 header 非常重要。對於“/v2/”地址空間下的任何請求的所有響應，即使是 4xx 響應，Docker-Distribution-API-Version 的 header 也應設定為值“registry/2.0”。如果需要，此頭允許 docker 引擎快速解析身份驗證提示資訊並回退到版本 1 的registry。確認此設定是否正確可以幫助避免回退問題。（This header allows the docker engine to quickly resolve authentication realms and fallback to version 1 registries, if necessary. Confirming this is setup correctly can help avoid problems with fallback.）

在同樣的思路中，你必須確保正確地將 X-Forwarded-Proto，X-Forwarded-For 和 Host header 傳送到它們的“客戶端”值。如果不這樣做，通常會使 registry 問題重定向到內部主機名或從 https 降級到 http。（Failure to do so usually makes the registry issue redirects to internal hostnames or downgrading from https to http.）

當“/v2/”端點在沒有憑證的情況下被訪問時，正確安全的 registry 應返回 401。響應應包含 WWW-Authenticate，為如何進行身份驗證提供指導，例如使用基本身份驗證或令牌服務。如果負載平衡器有健康檢查，建議將其配置為將 401 響應視為健康狀況，其他情況視為關閉。通過確保認證的配置問題不會意外暴露未受保護的 registry，可以確保安全。如果你使用的是不太複雜的負載平衡器（例如亞馬遜的 Elastic Load Balancer），它不允許更改健康的響應程式碼，則健康檢查可以定向到“/”，它總是返回 200 OK 響應。

9. 限制訪問

除了在安全的本地網路上執行的 registry 外，應始終對 registry 實施訪問限制。

9.1 原生基本身份驗證 native basic authentication

實現訪問限制的最簡單方法是通過基本認證（類似於其他 Web 伺服器的基本認證機制）。這個例子使用通過 htpasswd 來儲存 secrets 的原生基本身份認證。

警告：無法使用以純文字格式傳送憑證的身份驗證方案進行身份驗證。必須首先配置 TLS 才能使驗證生效。

1. 為使用者 testuser 建立一個包含密碼 testpassword 的密碼檔案：

$ mkdir auth
$ docker run \
  --entrypoint htpasswd \
  registry:2 -Bbn testuser testpassword > auth/htpasswd

2. 停止 registry

$ docker container stop registry

3. 使用基本身份驗證啟動 registry

$ docker run -d \
  -p 5000:5000 \
  --restart=always \
  --name registry \
  -v `pwd`/auth:/auth \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  -v `pwd`/certs:/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  registry:2

4. 嘗試從 registry 獲取映象，或上傳映象到 registry。這會全部失敗。

5. 登入 registry

$ docker login myregistrydomain.com:5000

在第一步提供使用者名稱和密碼。

測試現在可以從 registry 中獲取映象或將映象推送到 registry。

X509 錯誤：X509 錯誤通常表明你正在嘗試使用自簽名證書，但未正確配置 Docker 守護程式。請參閱執行不安全的登錄檔。

9.2 更多高階認證

你可能希望通過在 registry 前使用代理來實現更高階的基本身份驗證。見 recipes 列表。

登錄檔還支援委派認證（delegated authentiation），將使用者重定向到特定的可信令牌伺服器（token server）。這種方法設定起來更加複雜，只有在需要完全配置 ACL 並需要更多控制 registry 與全域性授權和身份驗證系統的整合時才有意義（only makes sense if you need to fully configure ACLs and need more control over the registry’s integration into your global authorization and authentication systems）。請參閱以下背景資訊和配置資訊。

這種方法需要你使用自己的或第三方認證系統。

10. 通過 compose 檔案部署 registry

如果 registry 很複雜，那麼使用 Docker compose 檔案來部署它可能更容易，而不是依賴於特定的 docker run 呼叫。使用以下示例 docker-compose.yml 作為模板。

registry:
  restart: always
  image: registry:2
  ports:
    - 5000:5000
  environment:
    REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
    REGISTRY_HTTP_TLS_KEY: /certs/domain.key
    REGISTRY_AUTH: htpasswd
    REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
    REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
  volumes:
    - /path/data:/var/lib/registry
    - /path/certs:/certs
    - /path/auth:/auth

將 /path 替換為包含 certs/ 和 auth/ 目錄的目錄。

通過在包含 docker-compose.yml 檔案的目錄中發出以下命令來啟你的 registry：

$ docker-compose up -d

11. 對 air-gapped registry 的考慮

可以在沒有網際網路連線的環境中執行 registry。但是，如果你依賴任何非本地映象，則需要考慮以下幾點：

你可能需要在連線的主機上構建本地 registry 的資料卷，可以在其中執行 docker pull 以獲取遠端可用的任何映象，然後將 registry 的資料卷遷移到隔離網路（air-gapped network）。
某些映象，如官方 Microsoft Windows 基本映象，不可分發。這意味著當你將基於這些映象之一的映象上傳到你的私人 registry 時，不會推送不可分發的層，而是始終從其授權位置獲取。這對於連線網際網路的主機來說很好，但不能用於空隙設定（air-gapped set-up）。

在 Docker 17.06 及更高版本中，可以配置 Docker 守護程式，以允許在這種情況下將不可分配的層上傳到私有 registry。這僅適用於存在不可分配映象的空隙設定或頻寬極端有限的情況下。你有責任確保你符合不可分配的層的使用條款。

1. 編輯 Linux 主機上的 `/etc/docker/` 和 Windows Server 上的 `C:\ProgramData\docker\config\daemon.json` 中的 `daemon.json` 檔案。假設檔案先前為空，請新增以下內容：

{
  "allow-nondistributable-artifacts": ["myregistrydomain.com:5000"]
}

值是 registry 地址陣列，用逗號分隔。
儲存並退出。

2. 重啟 Docker

3. 如果 registry 沒有自動重啟，則重啟 registry

4. 當你將映象上傳到 registry 時，它們的不可分發層也會上傳到 registry。

警告：不可分發的構件通常對如何以及在何處分發和共享有限制。只有使用此功能才能將工件推送到私有 registry，並確保你符合包含重新分配不可分配構件的任何條款。