使用容器映像檔的登錄檔鏡像

設定本機存放區鏡像後，您就能從本機端點 (而非 gcr.io 等上游存放區) 提取容器映像檔，建立及升級叢集。這種做法有助於加快 Pod 建立速度、避免外部提取頻率限制，並保護部署工作流程不受公開註冊資料庫中斷影響。在叢集生命週期內，您隨時可以啟用或停用登錄檔鏡像功能。

登錄檔鏡像的運作方式

登錄檔鏡像是公開登錄檔的本機副本，會複製或鏡像公開登錄檔的檔案結構。舉例來說，假設本機登錄檔鏡像的存放路徑是 172.18.0.20:5000。當 containerd 遇到提取映像檔 (例如 gcr.io/kubernetes-e2e-test-images/nautilus:1.0) 的要求時，containerd 會嘗試提取該映像檔，但不是從 gcr.io 提取，而是從下列路徑的本機登錄檔提取：172.18.0.20:5000/kubernetes-e2e-test-images/nautilus:1.0。如果映像檔不在這個本機登錄檔路徑中，系統會自動從 gcr.io 公開登錄檔提取映像檔。

使用登錄檔鏡像可享有下列好處：

  • 避免公開註冊資料庫服務中斷。
  • 加快 Pod 建立速度。
  • 可讓您自行執行安全漏洞掃描。
  • 避免公開註冊資料庫對指令發布頻率的限制。

事前準備

  • 您必須在網路中設定 Artifact Registry 伺服器。
  • 如果登錄伺服器執行私人 TLS 憑證，您必須取得憑證授權單位 (CA) 檔案。
  • 如果登錄伺服器需要驗證，您必須具備適當的登入憑證或 Docker 設定檔。
  • 如果您使用的是 Red Hat Quay 登錄檔，可能需要手動建立本機登錄檔的目錄結構。
  • 如要使用存放區鏡像，必須將容器執行階段設為 containerd。

  • 請確認管理員工作站有足夠的磁碟空間，可上傳映像檔。圖片上傳指令 bmctl push images 會解壓縮下載的圖片套件檔案，然後在本機擷取所有圖片檔案，再上傳這些檔案。磁碟空間必須至少是下載映像檔套件檔案大小的三倍，才能上傳映像檔。

    舉例來說，壓縮的 bmpackages_1.33.0-gke.799.tar.xz 檔案會占用約 12 GB 的磁碟空間，因此下載檔案前，磁碟空間應至少有 36 GB 的可用空間。

    如果您要執行略過升級 (在單一作業中升級兩個子版本)，則必須從目標 (N+2) 版本和中繼 (N+1) 版本的映像檔套件檔案上傳映像檔。根據這個範例，您需要約 72 GB 的可用磁碟空間，才能上傳映像檔。如要進一步瞭解中繼版本，請參閱「登錄檔鏡像的其他規定」。

下載 Google Distributed Cloud 的所有必要映像檔

從「Downloads」頁面下載最新版本的 bmctl 工具和映像檔套件。

將容器映像檔上傳至登錄伺服器

使用 bmctl push images 將容器映像檔上傳至存放區伺服器時，bmctl 會依序執行下列步驟：

  1. 將下載的圖片套件壓縮 tar 檔案解壓縮，例如將 bmpackages_1.36.200-gke.118.tar.xz 解壓縮為 bmpackages_1.36.200-gke.118.tar。

  2. 將解壓縮 tar 檔案中的所有映像檔，擷取至名為 bmpackages_1.36.200-gke.118 的目錄。

  3. 將每個映像檔推送至指定的私人登錄檔。

    bmctl 會使用 --username 和 --password 值進行基本驗證，將映像檔推送至私人登錄檔。

以下各節說明 bmctl push images 指令的一些常見變化版本，可用於將映像檔上傳至存放區伺服器。

向註冊資料庫驗證身分並提供 TLS 憑證

下列指令包含 --username 和 --password 旗標，用於向註冊資料庫伺服器驗證使用者。指令也包含 --cacert 旗標，用於傳遞 CA 傳輸層安全標準 (TLS) 憑證，該憑證用於安全的登錄伺服器通訊，包括映像檔推送和提取。這些旗標可為登錄伺服器提供基本安全性。

如果登錄伺服器需要驗證，且您未使用 --username 和 --password 旗標，則執行 bmctl push images 時，系統應會提示您輸入憑證。您可以輸入密碼，或選擇含有憑證的 Docker 設定檔。

如要上傳含有驗證和私人 CA 憑證的映像檔，請使用類似下列的指令：

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --username USERNAME \
    --password PASSWORD \
    --cacert CERT_PATH

更改下列內容：

  • IMAGES_TAR_FILE_PATH：下載的映像檔套件 tar 檔案路徑，例如 bmpackages_1.36.200-gke.118.tar.xz。

  • REGISTRY_IP:PORT：私人登錄伺服器的 IP 位址和通訊埠。

  • USERNAME：有權將映像檔上傳至登錄檔伺服器的使用者名稱。

  • PASSWORD：使用者用於向登錄檔伺服器驗證身分的密碼。

  • CERT_PATH：如果您的登錄檔伺服器使用私人 TLS 憑證，則為 CA 憑證檔案的路徑。

例如：

bmctl push images \
    --source bmpackages_1.36.200-gke.118.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --username alex --password pa55w0rd \
    --cacert /etc/pki/tls/certs/ca-bundle.crt

上傳映像檔，不需使用者驗證或憑證

如果登錄伺服器不需要憑證 (例如使用者名稱和密碼)，請在 bmctl 指令中指定 --need-credential=false。如果登錄伺服器使用公開 TLS 憑證，則不必使用 --cacert 旗標。這類上傳指令最適合用於測試環境，因為這類環境的安全性考量比正式環境少。

如要上傳圖片，但不進行驗證或使用私人 CA 憑證，請使用類似下列的指令：

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --need-credential=false

例如：

bmctl push images \
    --source bmpackages_1.36.200-gke.118.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --need-credential=false.

調整執行緒數量

映像檔套件 tar 檔案中的容器映像檔大小和數量，可能會導致映像檔上傳程序耗費較多時間。增加平行執行緒數量可加快常式執行速度。您可以使用 --threads 旗標，變更 bmctl push images 使用的平行執行緒數量。

根據預設，圖片上傳常式會使用 4 個執行緒。如果圖片上傳時間過長，請提高這個值。在 Google 測試環境中，從具有 4 個 CPU 的工作站上傳映像檔，使用 8 個平行執行緒大約需要 10 分鐘。

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --cacert CERT_PATH \
    --threads NUM_THREADS

將 NUM_THREADS 替換為用於處理圖片上傳作業的平行執行緒數量。根據預設，bmctl push images 會使用四個平行執行緒。

下列指令會將上傳作業的執行緒數量從 4 增加到 8，縮短上傳時間：

bmctl push images \
    --source bmpackages_1.36.200-gke.118.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --cacert ~/cert.pem \
    --threads 8

透過 Proxy 上傳

如需 Proxy 才能將映像檔從工作站上傳至登錄伺服器，可以在 bmctl 指令前加入 Proxy 詳細資料：

HTTPS_PROXY=http://PROXY_IP:PORT bmctl push images \
    --source=IMAGES_TAR_FILE_PATH \
    --private-registry=REGISTRY_IP:PORT \
    --cacert=CERT_PATH

更改下列內容：

  • PROXY_IP:PORT：Proxy 的 IP 位址和通訊埠。

  • IMAGES_TAR_FILE_PATH：下載的映像檔套件 tar 檔案路徑，例如 bmpackages_1.36.200-gke.118.tar.xz。

  • REGISTRY_IP:PORT：私人登錄伺服器的 IP 位址和通訊埠。

  • CERT_PATH：如果您的登錄檔伺服器使用私人 TLS 憑證，則為 CA 憑證檔案的路徑。

系統提示時，請輸入使用者名稱和密碼，或選取 Docker 設定檔。

下列指令會透過 Proxy 上傳映像檔：

HTTPS_PROXY=http://10.128.0.136:3128 bmctl push images \
    --source bmpackages_1.36.200-gke.118.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --cacert ~/cert.pem

搭配使用 bmctl push images 和自己的命名空間

如要在登錄伺服器中使用自己的命名空間，而非根命名空間，只要在叢集設定檔的 registryMirrors.endpoint 欄位中，提供私人登錄檔的 API 端點，containerd 就能從這個命名空間提取。端點通常採用 <REGISTRY_IP:PORT>/v2/<NAMESPACE> 格式。詳情請參閱私人登錄檔使用手冊。詳情請參閱「關於在登錄檔端點中使用 v2」。

bmctl push images \
    --source=IMAGES_TAR_FILE_PATH \
    --private-registry=REGISTRY_IP:PORT/NAMESPACE \
    --cacert=CERT_PATH

將 NAMESPACE 替換為要上傳映像檔的登錄檔伺服器命名空間名稱。

舉例來說，如果您只能存取 198.51.20.1:5000/test-namespace/，可以使用類似下列的指令，上傳 test-namespace 命名空間下的所有映像檔：

bmctl push images \
    --source=./bmpackages_1.36.200-gke.118.tar.xz \
    --private-registry=198.51.20.1:5000/test-namespace \
    --username=alex \
    --password=pa55w0rd \
    --cacert /etc/pki/tls/certs/ca-bundle.crt

接著，在叢集設定檔中，您可以新增下列內容，讓 containerd 從 test-namespace 命名空間提取：

registryMirrors:
  - endpoint: https://198.51.20.1:5000/v2/test-namespace

如要進一步瞭解 bmctl push images 指令，請參閱 bmctl 指令參考資料。

設定叢集以使用存放區鏡像

您可以在建立叢集時，或更新現有叢集時，為叢集設定登錄檔鏡像。以下兩節說明設定登錄檔鏡像的兩種方法。

使用叢集設定檔中的標頭部分

從 1.35 版開始，您可以在叢集設定檔的頂層標頭區段中定義管理員和使用者叢集的登錄檔鏡像和私人登錄檔，藉此設定或更新這些項目。更新後，設定仍會保留。

執行 bmctl update 時，標頭區段中的任何登錄檔設定都會自動覆寫叢集設定檔的 spec.nodeConfig 區段。

如果是 1.34 以下版本，您必須使用 nodeConfig.registryMirrors 區段指定使用者叢集中的登錄檔鏡像和私人登錄檔，而非標頭區段，因為標頭區段不會在更新後保留。

下列叢集設定檔範例指定從端點為 https://198.51.20.1:5000 的本機登錄檔鏡像提取映像檔。以下各節將說明設定檔開頭顯示的部分欄位。

# Sample cluster config with registry mirror:
---
gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
sshPrivateKeyPath: /root/ssh-key/id_rsa
registryMirrors:
  - endpoint: https://198.51.20.1:5000
    caCertPath: /root/ca.crt
    pullCredentialConfigPath: /root/.docker/config.json
    hosts:
      - somehost.io
      - otherhost.io
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-admin1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: admin1
  namespace: cluster-admin1
spec:
  nodeConfig:
    containerRuntime: containerd
...

使用叢集規格中的 nodeConfig.registryMirrors 區段

由於您可以與使用者叢集共用為管理叢集建立的密鑰，因此可以使用管理員或混合叢集的 nodeConfig.registryMirrors，在使用者叢集的叢集規格中指定登錄檔鏡像。

如要將使用者叢集設為使用與管理員叢集相同的登錄檔鏡像，請按照下列步驟操作：

  1. 從管理員叢集資源的 nodeConfig.registryMirrors 取得 nodeConfig.registryMirror 區段，包括 Secret 參照：

    kubectl get cluster CLUSTER_NAME -n CLUSTER_NAMESPACE \
    --kubeconfig ADMIN_KUBECONFIG \
    -o yaml

    更改下列內容：

    • CLUSTER_NAME：管理使用者叢集的管理員或混合式叢集名稱。

    • CLUSTER_NAMESPACE：管理叢集的命名空間名稱。

    • ADMIN_KUBECONFIG：管理叢集的 kubeconfig 檔案路徑。

  2. 將管理員叢集的 nodeConfig.registryMirrors 設定新增至使用者叢集的叢集設定檔。

    使用者叢集設定檔中的 registryMirrors 區段應與以下範例類似：

    ---
gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
sshPrivateKeyPath: /root/ssh-key/id_rsa
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-user1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: user1
  namespace: cluster-user1
spec:
  nodeConfig:
    containerRuntime: containerd
    registryMirrors:
    -   caCertSecretRef:
        name: the-secret-created-for-the-admin-cluster
        namespace: anthos-creds
      endpoint: https://172.18.0.20:5000
      hosts:
        -   somehost.io
        -   otherhost.io
      pullCredentialSecretRef:
        name: the-image-pull-creds-created-for-the-admin-cluster
        namespace: anthos-creds
...

如要後續變更使用者叢集的登錄檔鏡像設定，請編輯使用者叢集設定檔中的 nodeConfig.registryMirrors，並使用 bmctl update 套用變更。

hosts 欄位

containerd 會檢查叢集設定檔的 hosts 區段，找出哪些主機在本機鏡像。這些主機會對應至叢集設定檔 (registryMirror.endpoint) 中指定的登錄檔鏡像端點。在上一節的範例設定檔中，hosts 區段列出的公開登錄檔為 somehost.io 和 otherhost.io。由於這些公開登錄檔會顯示在 hosts 區段中，因此當 containerd 遇到來自 somehost.io 或 otherhost.io 的映像檔提取要求時，會先檢查私人登錄檔鏡像。

舉例來說，假設 containerd 收到 somehost.io/kubernetes-e2e-test-images/nautilus:1.0 的提取指令。由於 somehost.io 列為叢集設定檔 hosts 區段中的其中一個主機，因此 containerd 會在本機登錄檔鏡像中尋找 kubernetes-e2e-test-images/nautilus:1.0 映像檔。如果 hosts 區段中未列出 somehost.io，containerd 就不知道 somehost.io 有本機鏡像。在這種情況下，containerd 不會檢查映像檔的鏡像，而是從 somehost.io 公開登錄檔提取映像檔。

請注意，Google Distributed Cloud 預設會自動從 gcr.io 鏡像映像檔，因此您不必在 hosts 區段中將 gcr.io 列為主機。

hosts 值和 endpoint 值不應重疊。舉例來說，下列設定範例顯示與端點值網域部分相符的主機 europe-docker.pkg.dev。在這種情況下，您不需要指定 hosts 值：

...
registryMirrors:
  ...
  endpoint: https://europe-docker.pkg.dev:5000/v2/cloud-data-fusion-images
  hosts:
    - europe-docker.pkg.dev
    ...

gcrKeyPath 欄位

如要讓 Google Distributed Cloud 自動使用 Artifact Registry (gcr.io) 提取本機登錄檔中未顯示的映像檔，您必須指定 Artifact Registry 服務帳戶金鑰的路徑。Google Distributed Cloud 沒有為其他公開登錄檔提供金鑰的機制。

如果您不打算使用從 gcr.io 提取圖片的功能 (當圖片未顯示在本機登錄檔中時)，則不需要在叢集設定檔中新增 gcrKeyPath。

caCertPath 欄位

如果您的登錄檔需要私人傳輸層安全標準 (TLS) 憑證，這個欄位會採用伺服器根 CA 憑證檔案的路徑。這個憑證檔案應位於管理員工作站，也就是執行 bmctl 指令的機器。如果登錄檔不需要私人 TLS 憑證，則可將 caCertPath 欄位留空。

pullCredentialConfigPath 欄位

如果登錄伺服器不需要驗證 Docker 設定檔，則可將 pullCredentialConfigPath 欄位留空。請注意，這是執行 bmctl 指令的機器上設定檔的路徑。

搭配使用者叢集使用登錄檔鏡像

如果管理員叢集已設為從登錄檔鏡像提取映像檔，使用者叢集不會自動執行這項操作。如要讓使用者叢集從登錄檔鏡像提取映像檔，您必須按照「將叢集設為使用登錄檔鏡像」一文中的說明，個別設定使用者叢集。

更新登錄檔鏡像端點、憑證和提取憑證

如要更新登錄檔鏡像端點、憑證或提取憑證，請按照下列步驟操作：

  1. 在叢集設定檔中，更新端點、CA 憑證檔案，以及提取憑證設定檔的路徑。

  2. 執行下列指令來套用變更：

    bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG

    更改下列內容：

    • 將 CLUSTER_NAME 替換為要更新的叢集名稱。

    • ADMIN_KUBECONFIG 替換為管理員叢集設定檔的路徑。

確認映像檔是從映像檔存放區鏡像提取

您可以按照下列步驟檢查 config.toml 檔案的內容，判斷 containerd 是否從本機註冊資料庫提取映像檔：

  1. 登入節點並檢查下列檔案的內容：/etc/containerd/config.toml

  2. 請查看 config.toml 檔案的 plugins."io.containerd.grpc.v1.cri".registry.mirrors 區段，確認 endpoint 欄位中是否列出您的登錄伺服器。以下是 config.toml 範例檔案的摘錄，其中 endpoint 欄位以粗體顯示：

    version = 2
root = "/var/lib/containerd"
state = "/run/containerd"
...
[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.configs]
    [plugins."io.containerd.grpc.v1.cri".registry.configs."gcr.io"]
      [plugins."io.containerd.grpc.v1.cri".registry.configs."privateregistry2.io".tls]
        ca_file = '/etc/containerd/certs.d/privateregistry2.io/ca.crt'
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
      endpoint = ["http://privateregistry.io", "https://privateregistry2.io"]
...

    如果 endpoint 欄位中顯示您的登錄檔鏡像，則節點會從您的登錄檔鏡像提取映像檔，而不是從公開登錄檔提取。

疑難排解登錄檔鏡像設定問題

您可以使用 crictl (容器執行階段介面指令列工具)，下載個別映像檔來測試登錄檔設定。每個圖片檔都會獨立標記有意義的版本字串。舉例來說，叢集 API 控制器映像檔會標記 Google Distributed Cloud 發布版本，etcd 映像檔則會標記對應的 etcd 版本。

在 Google Distributed Cloud for bare metal 1.31.200-gke.59 版中，叢集 API 控制器映像檔 cluster-api-controller 和 etcd 映像檔 etcd 具有下列標記：

  • cluster-api-controller:1.31.200-gke.59
  • etcd:v3.4.30-0-gke.1

從登錄檔鏡像提取映像檔

如果您的登錄檔鏡像不使用命名空間，請使用下列指令提取映像檔：

crictl pull REGISTRY_IP:PORT/IMAGE_PATH:IMAGE_TAG

從使用命名空間的登錄檔鏡像提取映像檔

如果您的登錄檔鏡像使用命名空間，請使用下列指令提取映像檔：

crictl pull REGISTRY_IP:PORT/NAMESPACE/IMAGE_PATH:IMAGE_TAG

在登錄檔端點中使用 v2

如果登錄檔使用自訂命名空間，您必須在叢集設定檔的登錄檔端點 (registryMirror.endpoint) 中，於命名空間前面加上 v2/。如果您不使用命名空間，請勿使用 v2。無論是哪種情況，請勿在 --private-registry 旗標值或映像檔提取指令中使用 v2：

沒有命名空間

  • 有效：
    • endpoint: https://172.18.0.20:5000
    • crictl pull 172.18.0.20:5000/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
  • 無效：
    • endpoint: https://172.18.0.20:5000/v2
    • crictl pull 172.18.0.20:5000/v2/anthos-baremetal-release/etcd:v3.4.30-0-gke.1

使用命名空間

  • 有效：
    • endpoint: https://172.18.0.21:5000/v2/namespace
    • crictl 172.18.0.21:5000/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
  • 無效：
    • endpoint: https://172.18.0.21:5000/namespace
    • crictl pull 172.18.0.21:5000/v2/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1