Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

在 GKE 節點中自訂 containerd 設定

Autopilot Standard

本頁面說明如何自訂 Google Kubernetes Engine (GKE) 節點上 containerd 容器執行階段的設定。閱讀本文件前，請確認您熟悉容器執行階段的概念，以及自訂容器執行階段的原因。

GKE 中的 containerd 設定簡介

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

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

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

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

限制

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

可用的 containerd 設定選項

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

注意：設定 containerd 登錄檔時，建議使用 registryHosts 設定 (涵蓋更多登錄檔欄位)，而非 privateRegistryAccessConfig。registryHosts 則會覆寫 privateRegistryAccessConfig 中任何相符的 FQDN。

`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：用戶端憑證設定。
- key：用戶端私密金鑰設定。

`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"

注意：如果設定檔未使用 Secret Manager 中的密鑰 (例如 privateRegistryAccessConfig 功能，或使用儲存在 Secret Manager 中的憑證搭配 registryHosts)，可以移除 --scopes="cloud-platform" 旗標。

更改下列內容：

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

如要在新的 Standard 叢集啟用 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"

注意：如果設定檔未使用 Secret Manager 中的密鑰 (例如 privateRegistryAccessConfig 功能或使用 registryHosts 時，憑證儲存在 Secret Manager 中)，您可以移除 --scopes="cloud-platform" 旗標。

更改下列內容：

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 的 Secret，叢集或節點集區必須具備 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`

更新設定檔，在 privateRegistryAccessConfig 中指定 enabled: false，並刪除項目中的任何其他欄位，如下列範例所示：
```
privateRegistryAccessConfig:
  enabled: false
```
將更新後的設定檔套用至叢集。如需操作說明，請參閱「將 containerd 設定套用至現有叢集」。

停用 `registryHosts`

更新設定檔，在 registryHosts 項目中指定空白陣列，如以下範例所示：
```
registryHosts: []
```
將更新後的設定檔套用至叢集。如需操作說明，請參閱「將 containerd 設定套用至現有叢集」。

在 GKE 節點中自訂 containerd 設定 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

GKE 中的 containerd 設定簡介

限制

可用的 containerd 設定選項

privateRegistryAccessConfig

registryHosts

writableCgroups

將 containerd 設定套用至新叢集

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

將 containerd 設定套用至現有叢集

檢查存取權範圍

檢查 Autopilot 存取範圍

檢查標準存取權範圍

更新叢集以使用設定檔

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

在 Standard 叢集中重新建立節點

停用 containerd 設定選項

停用 privateRegistryAccessConfig

停用 registryHosts

在 GKE 節點中自訂 containerd 設定

`privateRegistryAccessConfig`

`registryHosts`

`writableCgroups`

停用 `privateRegistryAccessConfig`

停用 `registryHosts`