在 GKE 節點中自訂 containerd 設定

本頁面說明如何自訂 Google Kubernetes Engine (GKE) 節點上 containerd 容器執行階段的設定。閱讀本文前，請務必先瞭解容器執行階段的用途，以及自訂容器執行階段的原因。

GKE 中的 containerd 設定簡介

您可以在執行 Container-Optimized OS 等作業系統的 GKE 節點上，手動設定 containerd 執行階段的一組選項。自訂執行階段可讓您設定特殊需求，例如存取私人映像檔登錄檔。如要設定這些選項，請建立名為執行階段設定檔的 YAML 檔案，並在建立或更新叢集或節點集區時，將該檔案傳遞至 GKE。

這種自訂 containerd 的方法可避免部署具備權限的 DaemonSet，這類 DaemonSet 具有安全風險。當您提供執行階段設定檔給 GKE 時，GKE 會重新建立節點，並使用您的設定更新每個節點上的 containerd config.toml 檔案。即使節點終止、升級及重新建立，設定也會保留。

您可以在叢集層級或節點集區層級設定 containerd。 節點集區層級的設定會覆寫這些選項的叢集層級設定。更新叢集層級的 containerd 設定選項 (例如 registryHosts 或 writableCgroups) 時，GKE 只會更新及重新建立節點集區中的節點，這些節點集區沒有這些選項的專屬節點集區層級設定。如果節點集區已為該選項設定專屬的節點集區層級設定，系統就不會更新或重新建立節點集區，而是繼續使用專屬設定。

您只能透過執行階段設定檔設定 containerd 中的選項。GKE 也支援使用名為節點系統設定檔的獨立檔案，設定特定 kubelet 選項和低階 Linux 核心選項。詳情請參閱「自訂節點系統設定」。

限制

您無法使用執行階段設定檔，在 Windows 節點映像檔中變更 containerd 設定。

可用的 containerd 設定選項

以下各節說明可使用執行階段設定檔設定的選項。

privateRegistryAccessConfig

使用儲存在 Secret Manager 中的私人憑證，存取私人映像檔登錄檔。

如為 Container-Optimized OS 節點映像檔，這個選項適用於 GKE 1.27.3-gke.1700 以上版本；如為 Ubuntu 節點映像檔，則適用於 1.33 以上版本。

如需操作說明，請參閱「使用私人 CA 憑證存取私人登錄檔」。

privateRegistryAccessConfig:
  enabled: true
  certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
    secretURI: "SECRET_LOCATION"
  fqdns:
  - "FQDN1"
  - "FQDN2"

這項設定包含下列欄位：

  • enabled：啟用私人登錄檔設定的布林值。如果您設定 enabled: false，請刪除 privateRegistryAccessConfig 項目中的其他欄位。
  • certificateAuthorityDomainConfig：最多可包含五個憑證和 FQDN 定義。
  • gcpSecretManagerCertificateConfig：包含儲存在 Secret Manager 中的憑證，以及 FQDN 陣列。
  • secretURI：Secret Manager 中的憑證位置。privateRegistryAccessConfig 僅支援 secretURI 中的全域密鑰。
  • fqdns：私人登錄檔的完整網域名稱清單。您也可以使用 IPv4 位址，但我們建議使用 FQDN。

registryHosts

設定 containerd 登錄的進階設定，例如功能、自訂標頭和憑證。這對應於 containerd 的 hosts.toml。

這個選項適用於 GKE 1.34.1-gke.2980000 以上版本。

registryHosts:
- server: "REGISTRY_SERVER_FQDN"
  hosts:
  - host: "MIRROR_FQDN"
    capabilities:
    - "HOST_CAPABILITY_PULL"
    - "HOST_CAPABILITY_RESOLVE"
    - "HOST_CAPABILITY_PUSH"
    overridePath: false
    dialTimeout: "30s"
    header:
    - key: "HEADER_KEY"
      value:
      - "HEADER_VALUE_1"
      - "HEADER_VALUE_2"
    ca:
    - gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CA_SECRET/versions/VERSION"
    client:
    - cert:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_CERT_SECRET/versions/VERSION"
      key:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_KEY_SECRET/versions/VERSION"

這項設定包含下列欄位：

  • server：登錄伺服器的主機名稱 (例如 example.com)。這項資訊用於命名節點上的設定檔。這應該是完整網域名稱或 IP 位址，不含架構、通訊埠或路徑。
  • hosts：server 的主機專屬設定清單。
  • host：登錄檔鏡像的主機名稱 (例如 https://mirror.example.com:8000/1234、1.2.3.4:80)。這應該是完整網域名稱或 IP 位址。支援通訊協定、通訊埠和路徑。配置只能是 http 或 https。
  • capabilities：功能清單，指定主機可執行的作業。支援的值如下：
    • HOST_CAPABILITY_PULL：代表依摘要擷取資訊清單和 Blob 的功能。
    • HOST_CAPABILITY_RESOLVE：代表依名稱擷取資訊清單的功能。
    • HOST_CAPABILITY_PUSH：代表推送 Blob 和資訊清單的功能。
    如未指定，系統會啟用所有功能。
  • overridePath：布林值。如果 true，表示主機的 API 根端點是在網址路徑中定義，而非透過 API 規格定義。這項功能可用於缺少 /v2 前置字元的不符規定 OCI 登錄檔。預設為 false。
  • dialTimeout：持續時間字串 (例如 "30s")，指定連線嘗試完成所允許的最長持續時間。允許的最大值為 "180s"。如未設定，containerd 會將預設值設為 "30s"。值應為秒數的十進位數字，並加上 s 後置字串。
  • header：要傳送至登錄主機的自訂 HTTP 標頭清單。
    • key：標頭鍵。
    • value：標頭值清單。
  • ca：登錄主機憑證授權單位 (CA) 的憑證設定清單。如要為憑證建立密鑰及設定必要權限，請參閱「在 Secret Manager 中儲存 CA 公開金鑰」一文中的操作說明。
    • gcpSecretManagerSecretUri：Secret Manager 中包含 CA 憑證的 Secret URI。這項功能支援全域密鑰和區域密鑰。各機密類型的格式如下：
      • 全域密鑰格式：projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION。
      • 區域密鑰格式：projects/PROJECT_ID_OR_NUMBER/locations/REGION/secrets/SECRET_NAME/versions/VERSION。
  • client：用於向登錄主機進行驗證的用戶端憑證和金鑰組清單。如要為憑證建立密鑰及設定必要權限，請參閱「在 Secret Manager 中儲存 CA 公開金鑰」一文中的操作說明。
    • cert：用戶端憑證設定。
      • gcpSecretManagerSecretUri：Secret Manager 中含有用戶端憑證的密鑰 URI。支援全域密鑰和區域密鑰。
    • key：用戶端私密金鑰設定。
      • gcpSecretManagerSecretUri：Secret Manager 中含有用戶端金鑰的密鑰 URI。支援全域密鑰和區域密鑰。

writableCgroups

以讀寫模式掛接 /sys/fs/cgroup 檔案系統，讓工作負載管理子項程序的資源。

這個選項適用於 GKE 1.34.1-gke.2541000 以上版本。

詳情請參閱「為容器設定可寫入的 cgroup」。

writableCgroups:
  enabled: true

將 containerd 設定套用至新叢集

本節說明如何建立新的 GKE 叢集時套用 containerd 設定檔。

執行下列指令來建立 Autopilot 叢集：

gcloud container clusters create-auto CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

更改下列內容：

  • CLUSTER_NAME：新叢集的名稱。
  • LOCATION：新叢集的 Compute Engine 位置。
  • PATH_TO_CONFIG_FILE：您建立的設定檔路徑，例如 ~/containerd-configuration.yaml。

如要在新的標準叢集上啟用 containerd 設定，請使用相同選項執行 gcloud container clusters create 指令。除非您指定不同的 containerd 設定，否則在叢集中建立的新節點集區會沿用叢集層級的預設 containerd 設定。

將 Containerd 設定套用至新的節點集區

您可以使用下列指令，將 containerd 設定套用至新的 GKE 節點集區：

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

更改下列內容：

  • NODE_POOL_NAME：新節點集區的名稱。
  • CLUSTER_NAME：現有叢集的名稱。
  • LOCATION：新節點集區的 Compute Engine 位置。
  • PATH_TO_CONFIG_FILE：您建立的設定檔路徑，例如 ~/containerd-configuration.yaml。

將 containerd 設定套用至現有叢集

本節說明如何將 containerd 設定套用至現有叢集和節點。

更新叢集層級的 containerd 設定時，只會套用至未在節點集區層級定義自身設定的節點集區 (例如 registryHosts 或 writableCgroups)。GKE 會在這些節點集區中重新建立節點，以套用新設定。具有節點集區層級設定的節點集區會繼續使用自己的設定，且節點不會重新建立。 更新叢集或節點集區的 containerd 設定時，系統會重新建立節點以套用設定。這可能會導致執行中的工作負載暫時中斷。 只有在啟用自動升級功能時，GKE 才會重新建立節點。重新建立時，系統會遵守您設定的維護時間範圍。在未啟用自動升級功能的標準叢集中，您必須手動重新建立節點，才能套用設定。

檢查存取權範圍

如果設定檔使用 Secret Manager 中的密鑰，叢集或節點集就必須具備 cloud-platform 存取範圍。本節說明如何檢查存取範圍，以及如何使用新的或修改過的執行階段設定檔更新現有叢集。

如要瞭解新叢集的預設存取權範圍，請參閱「GKE 中的存取權範圍」。

檢查 Autopilot 存取權範圍

執行下列指令：

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

如果您使用 Secret Manager 中的密鑰，但叢集沒有 https://www.googleapis.com/auth/cloud-platform 存取權範圍，請建立具有這個存取權範圍的新叢集。

檢查標準存取權範圍

如要查看 Standard 叢集存取範圍，請檢查節點集區：

gcloud container node-pools describe NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --format='value[delimiter="\\n"](config.oauthScopes)'

將 NODE_POOL_NAME 替換為節點集區名稱。

如果您使用 Secret Manager 中的密鑰，但叢集沒有 https://www.googleapis.com/auth/cloud-platform 存取權範圍，請建立具有 cloud-platform 存取權範圍的新節點集區，並刪除現有節點集區。

更新叢集以使用設定檔

執行下列指令：

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

更新節點集區以使用設定檔

如要更新節點集區的 containerd 設定，請執行下列指令：

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

更改下列內容：

  • NODE_POOL_NAME：要更新的節點集區名稱。
  • CLUSTER_NAME：現有叢集的名稱。
  • LOCATION：叢集的 Compute Engine 位置。
  • PATH_TO_CONFIG_FILE：您建立的設定檔路徑，例如 ~/containerd-configuration.yaml。

在 Standard 叢集中重新建立節點

如果 Standard 叢集未使用自動升級功能，您必須手動重新建立節點集區，才能套用新設定。如要手動重新建立節點，請將叢集升級至目前使用的 GKE 版本。

gcloud container clusters upgrade CLUSTER_NAME \
    --location=LOCATION \
    --cluster-version=VERSION

將 VERSION 替換為叢集已使用的 GKE 修補程式版本。

停用 containerd 設定選項

停用 privateRegistryAccessConfig

  1. 更新設定檔，在 privateRegistryAccessConfig 中指定 enabled: false，並刪除項目中的任何其他欄位，如下列範例所示：

    privateRegistryAccessConfig:
  enabled: false
  2. 將更新後的設定檔套用至叢集。如需操作說明，請參閱「將 containerd 設定套用至現有叢集」。

停用 registryHosts

  1. 更新設定檔，在 registryHosts 項目中指定空白陣列，如下列範例所示：

    registryHosts: []
  2. 將更新後的設定檔套用至叢集。如需操作說明，請參閱「將 containerd 設定套用至現有叢集」。