RootSync and RepoSync fields
This page provides a reference for RootSync, RepoSync, and ResourceGroup resources.
You can use RootSync and RepoSync resources to configure Config Sync.
RootSync objects configure Config Sync to watch the specified source and apply objects from that source to the cluster. RootSyncs can be used to manage any resources on the cluster with cluster-admin permissions.
RepoSync objects configure Config Sync to watch the specified source and apply objects from that source to a specific namespace in the cluster. RepoSync objects are used to manage any namespace-scoped resources in that namespace with custom user-specified permissions.
The ResourceGroup resource is used by Config Sync to persist the inventory of objects that it previously applied and currently manages. Config Sync creates a ResourceGroup object for each RootSync and RepoSync on the cluster. This enables Config Sync to prune objects removed from the source and aggregate object sync and reconciliation status. You do not need to create your own ResourceGroup objects, nor should you modify ones managed by Config Sync.
Use of RootSync and RepoSync objects
If you
installed Config Sync using the Google Cloud console or Google Cloud CLI,
the Hub service will automatically create a RootSync object named
root-sync
. See
control root repositories in a root repository
for how to create additional RootSync objects.
If you
installed Config Sync using kubectl
,
see
control root repositories in a root repository
for how to create RootSync objects.
To create RepoSync objects, see control namespace repositories in a root repository or control namespace repositories in a namespace repository.
In addition to syncing fully-rendered Kubernetes objects, you can also configure Config Sync to use a repo with Kustomize configurations or Helm charts.
Lifecycle of RootSync, RepoSync, and ResourceGroup objects
The RootSync, RepoSync, and ResourceGroup custom resource definitions are installed when you install Config Sync.
The following diagram shows you an overview of how Config Sync creates the RootSync, RepoSync, and ResourceGroup resources:
Once it's created, the Reconciler Manager handles controlling the lifecycle of the Root Reconciler and each Namespace Reconciler process:
RootSync and RepoSync fields
RootSync and RepoSync CRDs use the same fields with the exceptions of following RootSync-only fields:
spec.sourceFormat
spec.helm.namespace
spec.helm.deployNamespace
Configuration for the source format
Key | Description |
---|---|
spec.sourceFormat |
sourceFormat specifies how the repository is formatted. Optional. The validation of this field is case-sensitive.
|
Configuration for the source type
Key | Description |
---|---|
spec.sourceType |
sourceType specifies the type of the source of truth. Must be one of
git , oci , or helm . Optional.Set to git if not specified. The validation of this field is
case-sensitive.Only one of spec.git and spec.oci can be
specified depending on the source type.
|
Configuration for the Git repository
Key | Description |
---|---|
spec.git.auth |
The type of Secret configured for access to the Git repo. Must be
ssh , cookiefile , gcenode ,
gcpserviceaccount , token , or none .
The validation of this field is case-sensitive. Required. |
spec.git.gcpServiceAccountEmail |
The Google Cloud service account used to annotate the RootSync or
RepoSync controller's Kubernetes Service Account. This field is only used
when spec.git.auth is gcpserviceaccount . |
spec.git.branch |
The Git branch of the repository to sync from. Default: master . |
spec.git.dir |
The absolute path in the Git repository to the root directory that
contains the configuration that you want to sync. Default: the root
directory (/ ) of the repository. |
spec.git.period |
The time duration between consecutive syncs. Default:
15s . |
spec.git.repo |
The Git repository URL to sync from. Required. |
spec.git.revision |
The Git revision (tag, commit, or hash) to check out. Default: HEAD . |
spec.git.secretRef.name |
The name of the Secret used to connect to the Git source of truth. |
spec.git.noSSLVerify 1 |
noSSLVerify specifies whether to enable or disable the SSL certificate
verification. Default: false. If noSSLVerify is set to true, it tells Git to skip the SSL certificate verification. This field is supported in Anthos Config Management version 1.8.2 and later. |
spec.git.caCertSecretRef.name 1 |
The name of the Secret containing the certificate authority (CA) certificate. If this field is provided, the git server must be using a certificate issued by this CA. The CA certificate must be stored in the Secret under a key named "cert". |
Proxy configuration for the Git repository
If your organization's security policies require you to route traffic through an HTTP(S) proxy, you can use the proxy's URI to configure Config Sync to communicate with your Git host.
Key | Description |
---|---|
spec.git.proxy |
The proxy URL with scheme for configuring access to the Git repo using
a proxy. For example,
https://proxy.internal.business.co:443 .The Git proxy accepts https , http , and
unadorned URLs, but http is not recommended for
security concerns.If using an http or an unadorned URL, make sure the
communication between your proxy server and Git host is secure.This field only has an effect when spec.git.auth is
cookiefile , none , or token . |
Configuration for the OCI image
Config Sync requires that the OCI layer is compressed in the tar
or
tar+gzip
format.
Other formats (for example, tar+bz2
) will not be recognized by Config Sync.
Switching from a valid REPO to an OCI image with an unsupported format will cause
managed resources to be pruned without an error.
Key | Description |
---|---|
spec.oci.auth |
The type of authentication configured for access to the OCI image. Must
be gcenode , gcpserviceaccount , or
none .
The validation of this field is case-sensitive. Required. |
spec.oci.gcpServiceAccountEmail |
The Google Cloud service account used to annotate the RootSync or
RepoSync controller's Kubernetes Service Account. This field is only used
when spec.oci.auth is gcpserviceaccount . |
spec.oci.dir |
The absolute path in the OCI image to the root directory that
contains the configuration that you want to sync. Default: the root
directory (/ ) of the image. |
spec.oci.period |
The time duration between consecutive syncs. Default:
15s . |
spec.oci.image |
The OCI image URL to sync from. Required. |
Configuration for the Helm repository
Key | Description |
---|---|
spec.helm.auth |
The type of authentication configured for access to the Helm repository.
Must be token , gcenode ,
gcpserviceaccount , or none . The validation of this
field is case-sensitive. Required. |
spec.helm.gcpServiceAccountEmail |
The Google Cloud service account used to annotate the RootSync or
RepoSync controller's Kubernetes Service Account. This field is only used
when spec.helm.auth is gcpserviceaccount . |
spec.helm.secretRef.name |
The name of the Secret
used to access the Helm repository. This field is used only when
spec.helm.auth is token . |
spec.helm.repo |
The Helm repository URL to sync from. Required. |
spec.helm.chart |
The Helm chart name. Required. |
spec.helm.version |
The Helm chart version number. Default: the latest version. In Config Sync versions before 1.16.0, the version field is available,
but only static versions are supported and charts aren't re-pulled. In
Config Sync version 1.16.0 and later, the version field can be specified
as a static value, as a range of versions from which Config Sync pulls the latest,
or left blank to indicate that Config Sync should the latest chart according to semver.
If specified as a range or left blank to indicate latest, Config Sync re-pulls
the chart every 1 hour by default. In Config Sync version 1.16.1 and later,
the re-pull period is configurable with the The version range syntax is identical to the version range syntax supported by the Helm CLI. Specifying the version as a range or leaving the value empty can cause high
CPU use for large charts with many versions. You can use
spec: override: resources: - containerName: helm-sync cpuRequest: "200m" |
spec.helm.period |
In Config Sync version 1.16.1 and later, The default value is 1 hour. The field accepts string values, for example "30s" or "5m". See the Go documentation on valid inputs for more information. If the chart version is a range, uses the literal tag "latest", or is left
empty to indicate that Config Sync should pull the latest version, the
chart is re-pulled according to |
spec.helm.releaseName |
The name of the Helm release. |
spec.helm.namespace |
This is mutually exclusive with spec.helm.deployNamespace . namespace sets the target namespace for a release. This field is used with RootSync objects only.
It only sets namespace for resources that contain namespace: {{ .Release.Namespace }} in their templates.
The value specified in spec.helm.namespace is only used as the value of Release.Namespace declared in your Helm templates.
For the resources that do not have namespace: {{ .Release.Namespace }} in their templates,
namespace default will be used. Default: default |
spec.helm.deployNamespace |
This is mutually exclusive with spec.helm.namespace . deployNamespace specifies which namespace to deploy the chart. Setting this field leverages the kpt set-namespace function, which causes Config Sync to replace the namespace fields of resources in the chart, including metadata.namespace of namespace-scoped resources, metadata.name of Namespace objects, and namespace references in some special resource types. If deployNamespace is not set, resources where metadata.namespace is not set are deployed to the default namespace. |
spec.helm.values |
Values to use instead of default values that accompany the chart. Format the values in the same way with the default values.yaml. For example: values: foo: bar: val1 quz: - val2 - val3 If For more information, see the Helm example manifest. |
spec.helm.includeCRDs |
Specifies if the Helm template should generate CustomResourceDefinitions.
Default: false . |
spec.helm.valuesFileRefs |
A list of references to objects in the cluster that represent values to use instead of the default values that accompany the chart. Only ConfigMaps are supported. The ConfigMap must be immutable and in the same namespace as the RootSync or RepoSync. ConfigMaps are immutable. To change the valuesFile after syncing, you must create a ConfigMap
with a different name and update the RootSync or RepoSync
When multiple values files are specified, duplicated keys in later files
override the value from earlier files. This is equivalent to passing in
multiple values files to the Helm CLI. If Each item in the list must contain the following:
This field is supported in Anthos Config Management 1.16.0 and later. For an example of how to change values, see /anthos-config-management/docs/how-to/sync-helm-charts-from-artifact-registry#valuesfilerefs. |
Configuration for overriding the resource requests and limits of a root or namespace reconciler
For Autopilot clusters, Config Sync ignores resource limit overrides. Resource request overrides are applied only when there exists one or more resource requests higher than the corresponding adjusted output declared in the annotation, or there exists one or more resource requests lower than the corresponding input declared in the annotation. For more information, see Cluster requirements for Config Sync.
Key | Description |
---|---|
spec.override.resources 1 |
The list of container resource request and limit overrides. Optional. Each item in the list contains three fields:
When an override value for a resource request or limit isn't provided, the default resource value for the request or limit is used. |
Configuration for overriding the log level of a container in root or namespace reconciler
When log level override value is not set, log level is configured to be the default value. The default log level for all containers in a RootSync or RepoSync reconciler is 0, with the exception of the git-sync container where the default is 5. Accepted log level override value is between 0 to 10 inclusive.
Key | Description |
---|---|
spec.override.logLevels |
The list of container log level override values. Optional. Each item in the list contains two fields:
When an override value for a container's log level isn't provided, the default log level value is used. |
Configuration for the number of Git commits to fetch
Key | Description |
---|---|
spec.override.gitSyncDepth 1 |
gitSyncDepth lets you override the number of Git commits to fetch. Must be no less than 0. Config Sync does a full clone if this field is 0, and a shallow clone if this field is greater than 0. If this field is not provided, Config Sync configures it automatically. |
Configuration for capturing the resource level status
Key | Description |
---|---|
spec.override.statusMode 1 |
statusMode lets you enable or disable capturing the resource level status.The default is enabled .To disable capturing the resource level status, set this field to disabled . |
Configuration for overriding the reconcile timeout
Key | Description |
---|---|
spec.override.reconcileTimeout 1 |
reconcileTimeout lets you override the threshold for how long to wait for
resources in an apply group to reconcile before giving up. All the resources in a commit
can be in multiple apply groups based on the dependencies.The default timeout is 5m .Use string to specify this field value, like 30s , 5m . |
Configuration for overriding the timeout for requests to the API server
Key | Description |
---|---|
spec.override.apiServerTimeout 1 | apiServerTimeout lets you
override the timeout for requests to the API server. The default timeout is
5s in Anthos Config Management versions earlier than 1.16.0,
and 15s in Anthos Config Management versions 1.16.0 and
later.Use string to specify this field value, like 30s , 5m . |
Configuration for shell access in rendering process
Key | Description |
---|---|
spec.override.enableShellInRendering 1 |
enableShellInRendering specifies whether to enable or disable the shell access in the rendering process.
Kustomize remote bases require shell access. Setting this field to true enables shell access in the rendering process and
supports pulling remote bases from public repositories.The default is false . |
Status of the objects
Key | Description |
---|---|
status.observedGeneration |
The generation (metadata.generation) of the spec of a RootSync or RepoSync resource that was last observed and acted on by Config Sync. This value can be compared with metadata.generation, which is an integer and is updated on spec mutation by the API server. |
status.reconciler |
The name of the reconciler process which corresponds to the sync resource. |
status.source.gitStatus.repo |
The Git repository URL being fetched. |
status.source.gitStatus.revision |
The Git revision (tag, commit, or hash) being fetched. |
status.source.gitStatus.branch |
The Git branch of the repository being fetched. |
status.source.gitStatus.dir |
The absolute path in the Git repository to the root directory that contains the configuration that you are syncing to. |
status.source.ociStatus.image |
The OCI image URL being fetched. |
status.source.ociStatus.dir |
The absolute path in the OCI image to the root directory that contains the configuration that you are syncing to. |
status.source.helmStatus.repo |
The helm repository URL being fetched. |
status.source.helmStatus.version |
The helm chart version being fetched. |
status.source.helmStatus.chart |
The name of the helm chart being fetched. |
status.source.commit |
The hash of the most recent commit or digest fetched from the source URL. |
status.source.errors |
A list of any errors that occurred while reading from the repository. |
status.rendering.gitStatus.repo |
The Git repository URL being rendered. |
status.rendering.gitStatus.revision |
The Git revision (tag, commit, or hash) being rendered. |
status.rendering.gitStatus.branch |
The Git branch of the repository being rendered. |
status.rendering.gitStatus.dir |
The absolute path in the Git repository to the root directory that contains the configuration that you are rendering. |
status.rendering.ociStatus.image |
The OCI image URL being rendered. |
status.rendering.ociStatus.dir |
The absolute path in the OCI image to the root directory that contains the configuration that you are rendering. |
status.rendering.helmStatus.repo |
The helm repository URL being rendered. |
status.rendering.helmStatus.version |
The helm chart version being rendered. |
status.rendering.helmStatus.chart |
The name of the helm chart being rendered. |
status.rendering.commit |
The hash of the most recent commit or digest that was rendered. This value is updated even when a commit or digest is only partially synced due to an error. |
status.rendering.errors |
A list of any errors that occurred while rendering the resources from
the change indicated by status.rendering.commit . |
status.sync.gitStatus.repo |
The Git repository URL being synced. |
status.sync.gitStatus.revision |
The Git revision (tag, commit, or hash) being synced. |
status.sync.gitStatus.branch |
The Git branch of the repository being synced. |
status.sync.gitStatus.dir |
The absolute path in the Git repository to the root directory that contains the configuration that you are syncing to. |
status.sync.ociStatus.image |
The OCI image URL being synced. |
status.sync.ociStatus.dir |
The absolute path in the OCI image to the root directory that contains the configuration that you are syncing to. |
status.sync.helmStatus.repo |
The helm repository URL being synced. |
status.sync.helmStatus.version |
The helm chart version being synced. |
status.sync.helmStatus.chart |
The name of the helm chart being synced. |
status.sync.commit |
The hash of the most recent commit or digest that was synced to the cluster. This value is updated even when a commit or digest is only partially synced due to an error. |
status.sync.errors |
A list of any errors that occurred while applying the resources from
the change indicated by status.sync.commit . |
status.conditions |
The latest available observations of the RootSync's current state. |
1 If you created a RootSync configuration file after installing with the Google Cloud console or Google Cloud CLI , you can overwrite this field. For a complete list, see Editable fields.
ResourceGroup fields
Spec and status fields
Key | Description |
---|---|
spec.resources |
The list of identifiers (Group, Kind, Namespace, Name) for resources
that are applied to the cluster from the Git repository that is specified
in a RepoSync CR or a RootSync CR. Optional. Each item in the list contains four fields: group ,
kind , namespace , and name . |
Status fields
Key | Description |
---|---|
status.observedGeneration |
The generation (metadata.generation) of the spec of a RootSync or RepoSync resource that was last observed and acted on by ResourceGroup controller. This value can be compared with metadata.generation, which is an integer and is updated on spec mutation by the API server. |
status.conditions |
The latest observed conditions for the current ResourceGroup. The
conditions have two different types: Reconciling and
Stalled . When the Reconciling type condition is
true, it means the current ResourceGroup is in reconciliation. When the
Stalled type condition is true, it means that the
reconciliation is stalled. When both are false, it means the current
ResourceGroup is reconciled and the status is up to date. |
status.resourceStatuses |
The list of statuses for resources that are included in
`.spec.resources`. Each item contains the identifier (Group, Kind,
Namespace, or Name) and status of a resource. The status is one of:
InProgress , Current , Failed ,
Terminating , NotFound , or
Unknown . |
Managed and unmanaged root-sync fields
There are two ways to install Config Sync:
For most installations, Config Sync is managed by the Hub service,
based on your inputs to the Google Cloud API, specifically the
spec.configSync
section of the config-management apply API.
For Anthos on VMware, Config Sync is managed by the user, with kubectl or any other Kubernetes client.
If your Config Sync installation is managed by the Hub service,
then your initial RootSync may also optionally be managed by the Hub
service. This allows you to bootstrap GitOps on your cluster using the
config-management apply API, and the Google Cloud client you prefer, such as
Google Cloud console, Google Cloud CLI, Config Connector, Terraform, and so on. This initial
managed RootSync will be named root-sync
.
This root-sync
will be created based on your inputs to the Google Cloud
API, specifically the
apply spec configuration for Config Sync.
Since this API only exposes a subset of the
RootSync fields, those fields are considered
managed in the root-sync
, while the other fields are considered unmanaged. The
managed fields can only be edited using the Google Cloud API. The
unmanaged fields can be edited using kubectl, or any other Kubernetes client.
For example, see
create and edit a RootSync configuration file
for how to export the root-sync
YAML, edit it locally, and re-apply it.
To create additional RootSyncs or RepoSyncs, you can use kubectl or another
Kubernetes client. You can also use the initial root-sync
to manage additional
RootSyncs and RepoSyncs with GitOps, by adding their YAML manifests to the
source of truth that the root-sync
is configured to sync from. This method
cannot be used to manage the config of initial root-sync
, because some of its
fields are managed by the Hub service. To manage the root-sync
with
GitOps, use Config Connector or Terraform.
The following fields of the RootSync named root-sync
are not managed by
the Hub service and can be edited with any Kubernetes client:
Key | Description |
---|---|
spec.git.noSSLVerify |
noSSLVerify specifies whether to enable or disable the SSL certificate
verification. Default: false .If noSSLVerify is set to true , it tells Git to skip the SSL certificate
verification. |
spec.git.caCertSecretRef.name |
The name of the Secret containing the certificate authority (CA) certificate. If this field is provided, the Git server must be using a certificate issued by this CA. The CA certificate must be stored in the Secret under a key named `cert`. |
spec.override.resources |
The list of container resource requests and limit overrides. Optional. Each item in the list contains three fields:
When an override value for a resource request or limit isn't provided, the default resource value for the request or limit is used. |
spec.override.gitSyncDepth |
gitSyncDepth lets you override the number of Git commits to fetch.Must be no less than 0. Config Sync does a full clone if this field is 0, and a shallow clone if this field is greater than 0. If this field is not provided, Config Sync configures it automatically. |
spec.override.statusMode |
statusMode lets you enable or disable capturing the resource
level status.The default is enabled .To disable capturing the resource level status, set this field to disabled .
|
spec.override.reconcileTimeout |
reconcileTimeout lets you override the threshold for how long
to wait for resources in an
apply group
to reconcile before giving up. All the resources in a commit can be in
multiple apply groups based on the
dependencies.The default timeout is 5m .Use string to specify this field value, for example 30s ,
5m .
|
spec.override.enableShellInRendering |
enableShellInRendering specifies whether to enable or disable
the shell access in the rendering process. Kustomize remote bases require
shell access. Setting this field to true enables shell access
in the rendering process and supports pulling remote bases from public
repositories.The default is false . |
Example CRs
The following sections show you examples of RootSync and Reposync CRs.
RootSync CR
The following example shows a RootSync object.
# 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: init
dir: config-sync-quickstart/multirepo/root
auth: none
period: 30s
RepoSync CR
The following example shows a RepoSync object.
# 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: init
dir: config-sync-quickstart/multirepo/root
auth: none
period: 30s
What's next
- Learn how to monitor your RootSync and RepoSync objects.