RootSync 和 RepoSync 欄位

本頁面提供 RootSync、RepoSync 和 ResourceGroup 物件中欄位的參考資料。如要進一步瞭解這些物件的運作方式，請參閱「Config Sync 架構」。

RootSync 和 RepoSync 欄位

RootSync 和 RepoSync 資源物件的欄位相同，但下列 RootSync 專屬欄位除外：

  • spec.helm.namespace
  • spec.helm.deployNamespace
  • spec.override.roleRefs

來源格式的設定

鍵 說明
spec.sourceFormat 指定可靠資料來源的格式。選填。
這個欄位的驗證作業會區分大小寫。
  • 如果是 RootSync 物件，值必須是 hierarchy 或 unstructured。如未指定，預設值為 hierarchy，但建議使用 unstructured。
  • 對於 RepoSync 物件，預設值為 unstructured，且無法變更。
詳情請參閱非結構化和階層式格式指南。

來源類型的設定

鍵 說明
spec.sourceType sourceType 會指定單一事實來源的類型。必須是 git、oci 或 helm。選填。
如果未指定，則設為 git。這個欄位的驗證會區分大小寫。

Git 存放區的設定

鍵 說明
spec.git.auth 針對 Git 存放區存取權設定的 Secret 類型，必須是 ssh、cookiefile、gcenode、gcpserviceaccount、githubapp、token 或 none。這個欄位的驗證會區分大小寫。必填。
spec.git.gcpServiceAccountEmail 用於註解 RootSync 或 RepoSync 控制器的 Kubernetes 服務帳戶。 Google Cloud 只有在 spec.git.auth 為 gcpserviceaccount 時，才會使用這個欄位。
spec.git.branch 要用來當做同步處理來源的存放區 Git 分支版本。這是選填欄位，預設值為 master。建議使用 spec.git.revision 欄位指定分支名稱。如果同時使用這兩個欄位，spec.git.revision 欄位的優先順序會高於 spec.git.branch。
spec.git.dir Git 存放區中根目錄的絕對路徑，該目錄包含要同步處理的設定。預設值：存放區的根目錄 (/)。
spec.git.period 連續同步處理作業之間的時間間隔。預設值：15s。
spec.git.repo 要同步處理的 Git 存放區網址。必填。
spec.git.revision 要同步處理的 Git 修訂版本 (分支版本、標記或提交)。這個欄位為選填，預設值為 HEAD。使用雜湊時，必須是完整雜湊，不得使用縮寫形式。
spec.git.secretRef.name 用於連線至 Git 資料來源的密鑰名稱。
spec.git.noSSLVerify1 noSSLVerify 可指定是否要啟用或停用 SSL 憑證驗證。預設值：false。
如果 noSSLVerify 設為 true，系統會指示 Git 略過 SSL 憑證驗證。
spec.git.caCertSecretRef.name1 包含憑證授權單位 (CA) 憑證的 Secret 名稱。 如果提供這個欄位，Git 伺服器就必須使用這個 CA 核發的憑證。 CA 憑證必須儲存在 Secret 中，且金鑰名稱為「cert」。

Git 存放區的 Proxy 設定

如果貴機構的安全政策規定必須透過 HTTP(S) Proxy 傳送流量，您可以使用 Proxy 的 URI 設定 Config Sync，與 Git 主機通訊。

鍵 說明
spec.git.proxy Proxy 網址 (含配置)，用於透過 Proxy 設定 Git 存放區的存取權。例如 https://proxy.internal.business.co:443。
Git Proxy 接受 https、http 和未經修飾的網址，但基於安全考量，http不建議使用。
如果使用 http 或未修飾的網址，請確保 Proxy 伺服器與 Git 主機之間的通訊安全無虞。
只有在 spec.git.auth 為 cookiefile、none 或 token 時，這個欄位才會生效。

OCI 映像檔的設定

Config Sync 規定 OCI 層必須以 tar 或 tar+gzip 格式壓縮。

Config Sync 無法辨識其他格式 (例如 tar+bz2)。從有效的 REPO 切換至格式不受支援的 OCI 映像檔時，系統會修剪受管理資源，但不會發生錯誤。

鍵 說明
spec.oci.auth 針對 OCI 映像檔存取權設定的驗證類型，必須是 gcenode、k8sserviceaccount、gcpserviceaccount 或 none。這個欄位的驗證會區分大小寫。必填。
spec.oci.gcpServiceAccountEmail 用於註解 RootSync 或 RepoSync 控制器的 Kubernetes 服務帳戶。 Google Cloud 只有在 spec.oci.auth 為 gcpserviceaccount 時，才會使用這個欄位。
spec.oci.dir OCI 映像檔中的絕對路徑，指向包含要同步處理設定的根目錄。預設值：圖片的根目錄 (/)。
spec.oci.period 連續同步處理作業之間的時間間隔。預設值：15s。
spec.oci.image 要從中同步處理的 OCI 映像檔網址。必填。
spec.oci.caCertSecretRef.name1

包含憑證授權單位 (CA) 憑證的 Secret 名稱。 如果提供這個欄位，OCI 伺服器就必須使用這個 CA 發行的憑證。 CA 憑證必須儲存在 Secret 中，且金鑰名稱為「cert」。

Helm 存放區的設定

鍵 說明
spec.helm.auth 為存取 Helm 存放區設定的驗證類型。 必須是 token、gcenode、k8sserviceaccount、gcpserviceaccount 或 none。這個欄位的驗證會區分大小寫。 必填。
spec.helm.gcpServiceAccountEmail 用於註解 RootSync 或 RepoSync 控制器的 Kubernetes 服務帳戶。 Google Cloud 只有在 spec.helm.auth 為 gcpserviceaccount 時，才會使用這個欄位。
spec.helm.secretRef.name 用於存取 Helm 存放區的 Secret 名稱。只有在 spec.helm.auth 為 token 時，才會使用此欄位。
spec.helm.repo 要用來當做同步處理來源的 Helm 存放區網址。必填。
spec.helm.chart Helm 資訊套件名稱。必填。
spec.helm.version

Helm 資訊套件版本號碼。預設值：最新版本。

版本欄位可以指定為靜態值、Config Sync 從中提取最新版本的版本範圍，或留空表示 Config Sync 應提取最新圖表。 Config Sync 會根據語意版本管理判斷「最新」版本。如果指定為範圍或留空，Config Sync 預設每 1 小時會重新提取一次資訊套件。您可以使用 spec.helm.period 欄位設定重新提取週期。如果版本指定為字串「latest」，圖表會根據 spec.helm.period 重新提取，就像版本範圍或空白版本一樣。

版本範圍語法與 Helm CLI 支援的版本範圍語法相同。

如果將版本指定為範圍或將值留空，可能會導致 CPU 使用率偏高，因為大型圖表會包含許多版本。您可以透過 spec.override 增加 helm-sync 容器的 CPU 要求，如下列範例所示：

    spec:
      override:
        resources:
        - containerName: helm-sync
          cpuRequest: "200m"
spec.helm.period

Config Sync 重新提取圖表前等待的時間長度。

預設值為 1 小時。這個欄位接受字串值，例如「30s」或「5m」。詳情請參閱 Go 說明文件，瞭解有效輸入內容 。

如果圖表版本是範圍、使用「latest」這個字面值標記，或是留空表示 Config Sync 應提取最新版本，系統會根據 spec.helm.period 重新提取圖表。如果圖表版本指定為單一靜態版本，系統就不會重新提取圖表。
spec.helm.releaseName Helm 版本的名稱。
spec.helm.namespace 這與 spec.helm.deployNamespace 互斥。
namespace 會設定版本的目標命名空間。這個欄位僅適用於 RootSync 物件。只有範本中含有 namespace: {{ .Release.Namespace }} 的資源，才會設定命名空間。 spec.helm.namespace 中指定的值只會做為 Helm 範本中宣告的 Release.Namespace 值。 如果範本中的資源沒有 namespace: {{ .Release.Namespace }}，系統會使用命名空間 default。預設值：default
spec.helm.deployNamespace 這與 spec.helm.namespace 互斥。
deployNamespace 指定要部署圖表的命名空間。設定這個欄位會運用 kpt set-namespace 函式，導致 Config Sync 替換圖表中的資源 namespace 欄位，包括命名空間範圍內資源的 metadata.namespace、命名空間物件的 metadata.name，以及某些特殊資源類型中的命名空間參照。
如果未設定 deployNamespace，則未設定 metadata.namespace 的資源會部署至預設命名空間。
spec.helm.values

要使用的值，而非圖表隨附的預設值。使用預設的 values.yaml 格式設定值。例如：

values:
  foo:
    bar: val1
  quz:
  - val2
  - val3

如果也指定了 valuesFileRefs，則 values 中的欄位會覆寫 valuesFileRefs 中的欄位。

詳情請參閱 Helm 範例資訊清單。
spec.helm.includeCRDs 指定 Helm 範本是否應產生 CustomResourceDefinitions。 預設：false。
spec.helm.valuesFileRefs

叢集中物件的參照清單，代表要使用的值，而非圖表隨附的預設值。僅支援 ConfigMap。ConfigMap 必須不可變動，且與 RootSync 或 RepoSync 位於相同命名空間。

ConfigMap 無法變更。如要在同步處理後變更 valuesFile，您必須建立名稱不同的 ConfigMap，並更新 RootSync 或 RepoSync spec.valuesFileRefs.name。

如果指定多個值檔案，後續檔案中的重複鍵會覆寫先前檔案中的值。這等同於將多個值檔案傳遞至 Helm CLI。如果也指定了 spec.helm.values，則 values 中的欄位會覆寫 valuesFileRefs 中的欄位。

清單中的每個項目都必須包含下列內容：

  • name (必要)：ConfigMap 物件的名稱
  • dataKey (選用)：物件中的資料鍵，用於讀取值。預設值：values.yaml

如要瞭解如何變更值，請參閱「同步處理 Helm 資訊圖表」。
spec.helm.caCertSecretRef.name1

包含憑證授權單位 (CA) 憑證的 Secret 名稱。 如果提供這個欄位，Helm 伺服器必須使用這個 CA 核發的憑證。 CA 憑證必須儲存在 Secret 中，且金鑰名稱為「cert」。

設定，以覆寫根或命名空間協調器的資源要求和限制

您可以覆寫 git-sync、oci-sync、helm-sync、hydration-controller 和 reconciler 容器。允許部分覆寫：如果未提供資源要求或限制的覆寫值，系統會使用要求或限制的預設資源值。

如果是 Autopilot 叢集，Config Sync 會忽略資源限制覆寫。只有在有一或多個資源要求高於註解中宣告的相應調整後輸出，或有一或多個資源要求低於註解中宣告的相應輸入時，系統才會套用資源要求覆寫。詳情請參閱「Config Sync 的叢集需求」。

鍵 說明
spec.override.resources1 容器資源要求和限制的覆寫清單。選填。
清單中的每個項目都包含三個欄位：
  • containerName：這個欄位可以是 git-sync、oci-sync、helm-sync、hydration-controller 或 reconciler。
  • cpuRequest (選填)
  • cpuLimit (選填)
  • memoryRequest (選填)
  • memoryLimit (選填)

如果未提供資源要求或限制的覆寫值，系統會使用要求或限制的預設資源值。

在根目錄或命名空間調解器中，覆寫容器記錄層級的設定

如果未設定記錄層級覆寫值，記錄層級會設為預設值。 RootSync 或 RepoSync 調解器中所有容器的預設記錄層級為 0，但 git-sync 容器的預設層級為 5。可接受的記錄層級覆寫值介於 0 至 10 (含) 之間。

鍵 說明
spec.override.logLevels 容器記錄層級覆寫值清單。選填。
清單中的每個項目都包含兩個欄位：
  • containerName：這個欄位可以是 git-sync、oci-sync、helm-sync、hydration-controller 或 reconciler。
  • logLevel

如果未提供容器記錄層級的覆寫值，系統會使用預設記錄層級值。

要擷取的 Git 提交次數設定

鍵 說明
spec.override.gitSyncDepth1 您可以透過 gitSyncDepth 覆寫要擷取的 Git 提交次數。
不得小於 0。
如果這個欄位為 0，Config Sync 會執行完整複製；如果這個欄位大於 0，則會執行淺層複製。
如果未提供這個欄位，Config Sync 會自動設定。

擷取資源層級狀態的設定

鍵 說明
spec.override.statusMode1 statusMode 可讓您啟用或停用擷取資源層級狀態。
預設值為 enabled。
如要停用擷取資源層級狀態，請將這個欄位設為 disabled。

用於覆寫協調逾時的設定

鍵 說明
spec.override.reconcileTimeout1 reconcileTimeout 可讓您覆寫等候資源的時間長度門檻，套用群組會在放棄前進行協調。根據依附元件，提交中的所有資源可以屬於多個套用群組。
預設逾時時間為 5m。
使用字串指定這個欄位值，例如 30s、5m。

設定，以覆寫 API 伺服器要求的逾時

鍵 說明
spec.override.apiServerTimeout1 apiServerTimeout 可讓您覆寫 API 伺服器要求的逾時時間。預設逾時時間為 15 秒，以 15s
形式指定。請使用字串指定這個欄位值，例如 30s、5m。

在算繪程序中設定 Shell 存取權

鍵 說明
spec.override.enableShellInRendering1 enableShellInRendering 指定是否要在算繪程序中啟用或停用殼層存取權。 Kustomize 遠端基礎需要 Shell 存取權。將這個欄位設為 true，即可在算繪程序中啟用 Shell 存取權，並支援從公開存放區提取遠端基準。
預設值為 false。

命名空間策略的設定 (僅限 RootSync)

鍵 說明
spec.override.namespaceStrategy1 namespaceStrategy 可控制調解器如何處理來源中宣告的命名空間範圍物件，缺少命名空間設定的情況。僅適用於使用 unstructured sourceFormat 時。
  • implicit：如果命名空間不存在，即使未在來源中宣告，協調器也會隱含地建立命名空間。系統會使用防止刪除註解建立隱含命名空間，並由 Config Sync 管理。
  • explicit：調解器只會建立來源中明確宣告的命名空間。

預設值為 implicit。

RBAC 繫結設定 (僅限 RootSync)

鍵 說明
spec.override.roleRefs1 roleRefs 是要建立繫結的 Role 或 ClusterRole 清單。 清單中的每個項目都包含下列欄位：
  • kind (必要)：指 RBAC 資源的種類。可接受的值為 Role 和 ClusterRole.
  • name (必要)：Role 或 ClusterRole 資源的名稱。
  • namespace (選用)：指出應建立 RoleBinding 的命名空間。如果是 ClusterRole 物件，則會決定是否要建立 RoleBinding 或 ClusterRoleBinding。如果是 Role 物件，則必須設為與 Role 相同的命名空間。

如果未設定，系統會建立 cluster-admin 的 ClusterRoleBinding。

物件狀態

鍵 說明
status.observedGeneration Config Sync 最近一次觀察並處理的 RootSync 或 RepoSync 資源規格產生作業 (metadata.generation)。這個值可以與 metadata.generation 比較，後者是整數，且會在 API 伺服器變更規格時更新。
status.reconciler 與同步資源對應的和解程序名稱。
status.source.gitStatus.repo 要擷取的 Git 存放區網址。
status.source.gitStatus.revision 要擷取的 Git 修訂版本 (標記、修訂版本或雜湊)。
status.source.gitStatus.branch 要擷取的存放區 Git 分支。
status.source.gitStatus.dir Git 存放區中根目錄的絕對路徑，其中包含要同步處理的設定。
status.source.ociStatus.image 要擷取的 OCI 映像檔網址。
status.source.ociStatus.dir OCI 映像檔中的絕對路徑，指向包含要同步處理設定的根目錄。
status.source.helmStatus.repo 要擷取的 Helm 存放區網址。
status.source.helmStatus.version 要擷取的 Helm 資訊套件版本。
status.source.helmStatus.chart 要擷取的 Helm 資訊套件名稱。
status.source.commit 從來源網址擷取的最新修訂版本或摘要的雜湊。
status.source.errors 從單一事實來源讀取及剖析設定時發生錯誤。如果錯誤過多，Config Sync 會截斷錯誤訊息，因此這份報告可能不會列出所有錯誤。
status.source.errorSummary.totalCount 整數，追蹤從可靠資料來源讀取及剖析設定時發生的錯誤總數。
status.source.errorSummary.truncated 布林值，指出 status.source.errors 欄位是否包含從可靠資料來源讀取及剖析設定時遇到的所有錯誤。
status.source.errorSummary.errorCountAfterTruncation 整數，追蹤 status.source.errors 欄位中的錯誤數。
status.rendering.gitStatus.repo 要轉譯的 Git 存放區網址。
status.rendering.gitStatus.revision 要算繪的 Git 修訂版本 (標記、修訂版本或雜湊)。
status.rendering.gitStatus.branch 要算繪的存放區 Git 分支版本。
status.rendering.gitStatus.dir Git 存放區中的絕對路徑，指向包含要算繪設定的根目錄。
status.rendering.ociStatus.image 要轉譯的 OCI 圖片網址。
status.rendering.ociStatus.dir OCI 映像檔中的絕對路徑，指向包含要轉譯設定的根目錄。
status.rendering.helmStatus.repo 要算繪的 Helm 存放區網址。
status.rendering.helmStatus.version 要算繪的 Helm 資訊套件版本。
status.rendering.helmStatus.chart 要算繪的 Helm 資訊套件名稱。
status.rendering.commit 系統算繪的最新提交或摘要的雜湊。即使因發生錯誤而只部分同步處理提交或摘要，這個值也會更新。
status.rendering.errors 在從 status.rendering.commit 指示的變更中算繪資源時，所發生的任何錯誤清單。如果錯誤過多，Config Sync 會截斷錯誤，因此這可能不包含所有遇到的錯誤。
status.rendering.errorSummary.totalCount 整數：追蹤從可靠資料來源算繪設定時發生的錯誤總數。
status.rendering.errorSummary.truncated 這個布林值表示 status.rendering.errors 欄位是否包含從可靠資料來源算繪設定時遇到的所有錯誤。
status.rendering.errorSummary.errorCountAfterTruncation 整數，追蹤 status.rendering.errors 欄位中的錯誤數。
status.sync.gitStatus.repo 正在同步處理的 Git 存放區網址。
status.sync.gitStatus.revision 正在同步處理的 Git 修訂版本 (標記、修訂版本或雜湊)。
status.sync.gitStatus.branch 要同步處理的存放區 Git 分支版本。
status.sync.gitStatus.dir Git 存放區中根目錄的絕對路徑，其中包含要同步處理的設定。
status.sync.ociStatus.image 正在同步的 OCI 映像檔網址。
status.sync.ociStatus.dir OCI 映像檔中的絕對路徑，指向包含要同步處理設定的根目錄。
status.sync.helmStatus.repo 正在同步處理的 Helm 存放區網址。
status.sync.helmStatus.version 正在同步處理的 Helm 資訊套件版本。
status.sync.helmStatus.chart 要同步處理的 Helm 資訊套件名稱。
status.sync.commit 同步至叢集的最新提交或摘要的雜湊。即使因發生錯誤而只部分同步處理提交或摘要，這個值也會更新。
status.sync.errors 列出套用 status.sync.commit 所指出變更中的資源時發生的任何錯誤。如果錯誤過多，Config Sync 會截斷錯誤訊息，因此這份報告可能不會列出所有錯誤。
status.sync.errorSummary.totalCount 整數，追蹤從可靠資料來源套用設定時發生的錯誤總數。
status.sync.errorSummary.truncated 這個布林值表示 status.sync.errors 欄位是否包含從可靠資料來源套用設定時發生的所有錯誤。
status.sync.errorSummary.errorCountAfterTruncation 整數，追蹤 status.sync.errors 欄位中的錯誤數。
status.conditions 追蹤 RootSync 或 RepoSync 物件目前狀態的條件清單。
當條件的「type」欄位為「Reconciling」 或「Stalled」時：
  • 這個條件表示 Reconciler Manager 在建立及管理這個 RootSync 或 RepoSync 物件的 Reconciler 時的狀態。
  • 條件的 errors 欄位會追蹤調解 RootSync 或 RepoSync 物件時發生的錯誤。
  • 條件的 errorSummary 欄位會摘要說明條件 errors 欄位中的錯誤。
  • 條件的「errorsSourceRefs」欄位為空白。
如果條件類型為 Syncing：
  • 這個條件會指出調解器將資源同步至叢集時的狀態。
  • 條件的 errors 欄位不會使用，應忽略。
  • 條件的 errorsSourceRefs 欄位會追蹤錯誤的來源。錯誤來源可能是 status.rendering.errors、status.source.errors 或 status.sync.errors。
  • 條件的 errorSummary 欄位會摘要說明 errorsSourceRefs 欄位中提及的錯誤。

1 如果您使用 Google Cloud 控制台或 Google Cloud CLI 安裝後建立 RootSync 設定檔，可以覆寫這個欄位。

ResourceGroup 欄位

規格和狀態欄位

鍵 說明
spec.resources 從 RepoSync CR 或 RootSync CR 中指定的 Git 存放區套用至叢集的資源 ID 清單 (群組、種類、命名空間、名稱)。選填。
清單中的每個項目都包含四個欄位：group、kind、namespace 和 name。

狀態欄位

鍵 說明
status.observedGeneration ResourceGroup 控制器上次觀察及處理的 RootSync 或 RepoSync 資源規格產生項目 (metadata.generation)。這個值可以與 metadata.generation 比較，後者是整數，且會在 API 伺服器變更規格時更新。
status.conditions 目前 ResourceGroup 最近一次觀察到的條件。條件有兩種不同類型：Reconciling 和 Stalled。如果 Reconciling 類型條件為 true，表示目前的 ResourceGroup 正在進行協調。如果 Stalled 類型條件為 true，表示對帳作業已停止。如果兩者皆為 false，表示目前的 ResourceGroup 已完成調解，且狀態為最新狀態。
status.resourceStatuses .spec.resources 中所含資源的狀態清單。每個項目都包含資源的 ID (群組、種類、命名空間或名稱) 和狀態。狀態為下列其中一項：InProgress、Current、Failed、Terminating、NotFound 或 Unknown。

不受管理的根同步欄位

Fleet (Hub) 服務不會管理名為 root-sync 的 RootSync 的下列欄位，因此可以使用任何 Kubernetes 用戶端編輯這些欄位：

鍵 說明
spec.helm Helm 存放區設定的所有欄位。
spec.override 所有用於覆寫預設設定的欄位。
spec.git.noSSLVerify 用於指定是否要啟用或停用 Git 的 SSL 憑證驗證。預設值為 false。
spec.git.caCertSecretRef.name 包含 Git 存放區憑證授權單位 (CA) 憑證的 Secret 名稱。
spec.oci.caCertSecretRef.name 包含 OCI 存放區憑證授權單位 (CA) 憑證的 Secret 名稱。

如要進一步瞭解 RootSync 物件中的受管理和非受管理欄位，請參閱「Fleet 服務如何管理 RootSync 物件」。

範例 CR

以下各節將顯示 RootSync 和 RepoSync CR 的範例。

RootSync CR

以下範例顯示 RootSync 物件。

# root-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: root-sync
  namespace: config-management-system
spec:
  sourceType: git
  sourceFormat: unstructured
  git:
    repo: https://github.com/GoogleCloudPlatform/anthos-config-management-samples
    branch: main
    dir: config-sync-quickstart/multirepo/root
    auth: none
    period: 30s

RepoSync CR

以下範例顯示 RepoSync 物件。

# repo-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RepoSync
metadata:
  name: repo-sync
  namespace: gamestore
spec:
  sourceType: git
  sourceFormat: unstructured
  git:
    repo: https://github.com/GoogleCloudPlatform/anthos-config-management-samples
    branch: main
    dir: config-sync-quickstart/multirepo/root
    auth: none
    period: 30s

後續步驟