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 可靠来源的 Secret 的名称。
spec.git.noSSLVerify1 noSSLVerify 指定是启用还是停用 SSL 证书验证。默认值：false。
如果 noSSLVerify 设置为 true，则指示 Git 跳过 SSL 证书验证。
spec.git.caCertSecretRef.name1 包含证书授权机构 (CA) 证书的 Secret 的名称。如果提供此字段，则 Git 服务器必须使用由此 CA 颁发的证书。CA 证书必须存储在 Secret 中名为“cert”的密钥下。

Git 代码库的代理配置

如果您的组织的安全政策要求您通过 HTTP(S) 代理路由流量，则可以使用该代理的 URI 将 Config Sync 配置为与 Git 主机进行通信。

键 说明
spec.git.proxy 代理网址，包含使用代理配置对 Git 代码库的访问权限的方案。例如，https://proxy.internal.business.co:443。
Git 代理接受 https、http 和未修饰的网址，但出于安全考虑，不建议使用 http。
如果使用 http 或未修饰的网址，请确保代理服务器和 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、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 指定在渲染过程中是要启用还是停用 shell 访问。Kustomize 远程库需要 shell 访问。将此字段设置为 true 可在渲染过程中启用 shell 访问，并支持从公共代码库中拉取远程库。
默认值为 false。

命名空间策略的配置（仅限 RootSync）

键 说明
spec.override.namespaceStrategy1 namespaceStrategy 用于控制协调器如何处理来源中声明的命名空间级对象缺少命名空间配置的情况。仅在使用 unstructured sourceFormat 时适用。
  • implicit：如果命名空间不存在，即使未在来源中声明，协调器也会隐式创建命名空间。隐式命名空间是使用 prevent deletion 注解创建的，并由 Config Sync 管理。
  • explicit：协调器将仅创建在来源中明确声明的命名空间。

默认值为 implicit。

RBAC 绑定的配置（仅限 RootSync）

键 说明
spec.override.roleRefs1 roleRefs 是要创建绑定的 Role 或 ClusterRole 的列表。 列表中的每一项都包含以下字段：
  • kind（必需）：指 RBAC 资源的 Kind。可接受的值为 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 对象创建和管理协调器时的状态。
  • 条件的 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 代码库应用于集群的资源的标识符（组、种类、命名空间、名称）列表。可选。
列表中的每个项均包含四个字段：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 中包含的资源的状态列表。每个列表项均包含资源的标识符（组、种类、命名空间或名称）和状态。状态可为 InProgress、Current、Failed、Terminating、NotFound 或 Unknown 之一。

非代管根同步字段

名为 root-sync 的 RootSync 的以下字段不由舰队 (Hub) 服务代管，因此可以使用任何 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 对象中的受管理字段和不受管理字段，请参阅舰队服务如何管理 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

后续步骤