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

本頁說明如何使用從登錄檔鏡像提取的映像檔 (而非從 gcr.io 等公開登錄檔)，建立及升級叢集。您隨時可以在叢集生命週期中啟用或停用這項功能。

本頁適用於負責設定及管理儲存空間效能、用量和費用的作業人員和儲存空間專家。如要進一步瞭解我們在 Google Cloud 內容中提及的常見角色和範例工作，請參閱「常見的 GKE Enterprise 使用者角色和工作」。

登錄檔鏡像會複製或鏡像公開登錄檔的檔案結構，是公開登錄檔的本機副本。舉例來說，假設本機登錄檔鏡像的路徑是 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.31.200-gke.59.tar.xz 檔案約佔 8.5 GB 的磁碟空間，因此下載檔案前，您應至少有 25.5 GB 的可用磁碟空間。

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

前往「Downloads」頁面，下載最新版的 bmctl 工具和圖片套件。

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

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

1. 將下載的圖片套件壓縮 tar 檔案 (例如 bmpackages_1.32.100-gke.106.tar.xz) 解壓縮至 bmpackages_1.32.100-gke.106.tar。

2. 將解壓縮的 tar 檔案中的所有圖片，解壓縮到名為 bmpackages_1.32.100-gke.106 的目錄。

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.32.100-gke.106.tar.xz。

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

• USERNAME：具有將圖片上傳至登錄伺服器權限的使用者名稱。

• PASSWORD：使用者向登錄伺服器進行驗證時使用的密碼。

• CERT_PATH：CA 憑證檔案的路徑 (如果登錄伺服器使用私密 TLS 憑證)。

例如：

bmctl push images \
    --source bmpackages_1.32.100-gke.106.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.32.100-gke.106.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --need-credential=false.

調整執行緒數量

由於圖片套件 tar 檔案中的容器映像檔大小和數量，圖片上傳程序可能相當耗時。增加平行執行緒數量可加快常式執行速度。您可以使用 --threads 標記，變更 bmctl push images 使用的平行執行緒數量。

根據預設，圖片上傳常式會使用 4 個執行緒。如果圖片上傳時間過長，請增加這個值。以基準來說，在 Google 測試環境中，從工作站上傳圖片 (4 個 CPU) 大約需要 10 分鐘，且有 8 個平行執行緒。

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.32.100-gke.106.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.32.100-gke.106.tar.xz。

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

• CERT_PATH：CA 憑證檔案的路徑 (如果登錄伺服器使用私密 TLS 憑證)。

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

下列指令會透過 Proxy 上傳圖片：

HTTPS_PROXY=http://10.128.0.136:3128 bmctl push images \
    --source bmpackages_1.32.100-gke.106.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:5000/test-namespace/，可以使用下列指令上傳 test-namespace 命名空間下的所有圖片：

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

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

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

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

設定叢集以使用登錄檔鏡像

您可以在建立叢集時，或更新現有叢集時，為叢集設定登錄檔鏡像。您使用的設定方法取決於叢集類型，如果是使用者叢集，則取決於您是要建立叢集還是更新叢集。以下兩節說明設定登錄檔鏡像的兩種方法。

使用叢集設定檔中的標頭區段

在叢集設定檔的標頭部分，您可以在 Cluster 規格以外指定登錄檔鏡像：

• 如果是管理員、混合式和獨立叢集，設定登錄檔鏡像的唯一方法，就是使用叢集設定檔中的標頭部分。這個方法適用於叢集建立或叢集更新。

• 如果是使用者叢集，您只能在建立叢集時，使用這個方法設定登錄檔鏡像。或者，如要為現有使用者叢集設定登錄檔鏡像，請使用叢集規格中的 nodeConfig.registryMirrors 區段。

下列範例叢集設定檔指定要從端點為 https://198.51.20: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: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.registryMirror 區段，包括管理叢集資源的 nodeConfig.registryMirrors 中的密鑰參照：

   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