Configuration Syntax

Permissions

The helm values snippet below shows an example of the generic sync configuration and related RBAC roles. There you can notice some key fields nested under .sync.generic value:

the RBAC namespaced role and cluster scoped clusterRole required for the plugin - these would be adjusted to fit the needs of your use case and the configuration that you define. Note that when the "Multi-namespace mode" is used, the namespaced role will become ClusterRole.
the config field, which will populate the CONFIG environment variable of the vCluster syncer container - this must be a string with valid YAML formatting. It uses a custom syntax to define the behavior of the plugin.

sync:
  generic:
    clusterRole:
      extraRules:
        - apiGroups: ["apiextensions.k8s.io"]
          resources: ["customresourcedefinitions"]
          verbs: ["get", "list", "watch"]
    role:
      extraRules:
        # Example for Cert Manager
        - apiGroups: ["cert-manager.io"]
          resources: ["issuers", "certificates", "certificaterequests"]
          verbs: ["create", "delete", "patch", "update", "get", "list", "watch"]
    config: |-
      version: v1beta1
      export:
      # ...

Virtual to Host sync

We use the top-level export field in the configuration to declare which virtual resources we want to sync to the host cluster. Each item in the export array defines the resource via apiVersion and kind strings. Each apiVersion and kind pair can have only one entry in the export array. The patches field allows you to define how are certain fields of the synced resource modified before its creation(or update) in the host cluster.
The reversePatches field allows you to declare how changes to certain fields(implicitly this is done for the status) of the synced resource(the one created in the host cluster) are propagated back to the original resource in the virtual cluster. Besides the status, only the fields referenced in the copyFromObject reverse patch operations are propagated. Both these fields follow the same syntax, as documented in the "Patch syntax" chapter of this doc.

Example:

sync:
  generic:
    config: |-
      version: v1beta1
      export:
        - apiVersion: cert-manager.io/v1
          kind: Certificate
          patches:
            - op: rewriteName
              path: spec.issuerRef.name
            - op: rewriteName
              path: spec.secretName
          reversePatches:
            # Implicit reverse patch for status would be declared like so:
            # - op: copyFromObject
            #   fromPath: status
            #   path: status

info

Only the namespaced resources are supported at this time.

Selector for a generic Virtual to Host sync
You can limit which resources will be synced from the virtual cluster by configuring the selector array. The virtual resource is synced when it matches one or more selectors, or when the selector field is empty. Supported selector types are:
labelSelector - the key: value map of the resource labels. All of the defined label key and values should match on the resource in the virtual cluster to be synced. Example:

sync:
  generic:
    config: |-
      version: v1beta1
      export:
        - apiVersion: cert-manager.io/v1
          kind: Certificate
          selector: 
            labelSelector: 
              "label-key": "label-value"

Host to Virtual sync

We use the top-level import field in the configuration to declare which host resources we want to sync to the virtual cluster. Each item in the import array defines the resource via apiVersion and kind strings. Each apiVersion and kind pair can have only one entry in the import array. The patches field allows you to define how are certain fields of the synced resource modified before its creation(or update) in the virtual cluster.
The reversePatches field allows you to declare how changes to certain fields of the synced resource(in this case, the one created in the virtual cluster) are propagated back to the original resource in the host cluster. Only the fields referenced in the copyFromObject reverse patch operations are propagated. Both these fields follow the same syntax, as documented in the "Patch syntax" chapter of this doc.

Example:

sync:
  generic:
    config: |-
      version: v1beta1
      import:
        - kind: Secret
          apiVersion: v1
        - kind: IngressClass
          apiVersion: networking.k8s.io/v1

info

The sync from Host to Virtual cluster is supported only in "Multi-namespace mode"

Patch syntax

The patch defines how will the vCluster behave when syncing each resource to and from the host cluster. Generally, a patch is defined by the field path and op(operation) that should be performed on said field.
An array of conditions may also be set, and in such case, the field value will be modified by a patch only if the field value matches all the conditions.
Some operation types may utilize additional fields, and these will be explained in the next chapter.

Patch operations

op	Support	Description
copyFromObject	all	Copy value of the field referenced in the `fromPath` from the originating object to the `path` field of the destination object. The `fromPath` can be omitted, in such case, it will default to the same field path as referenced in the `path`.
add	all	Add contents of the `value` into the `path` field. The `value` can be either scalar or a complex object.
replace	all	Replace the contents of the `path` field with the contents of the `value`. The `value` can be either scalar or a complex object.
remove	all	Remove the contents of the `path` field
rewriteName	V->H	Replaces the contents of the `path` field with transformed content based on the namespace of the synced resource. This is typically done on the fields that refer to a resource name, and on the `.metadata.name` as well(implicit). This is done to avoid naming collisions when syncing resources to the host cluster, but it is not necessary when using the "Multi-namespace mode". As an example, the "logstash" value of a resource in the "logging" namespace of the vCluster named "vc" is rewritten to "logstash-x-logging-x-vc". If the resulting length of the value would be over 63 characters, the last 10 characters will be replaced with a hash of the full value.
rewriteName + namePath + namespacePath	V->H	Similar to `rewriteName`, but with an addition of the `namePath` and/or `namespacePath`. This is used when a field of the synced resource is referencing a different resource via namespace and name via two separate fields. When using this option you would set the `path` to reference a field that is a common parent of both `namePath` and `namespacePath`, and these two fields would then contain just the relative path. For example, `path: spec.includes` + `namePath: name` + `namespacePath: namespace` for a resource that contains name in `spec.includes.name` and namespace in `spec.includes.namespace`.
rewriteName + regex	V->H	Similar to `rewriteName`, but with an addition of the `regex` option for the patch. This is used when a string contains not just the resource name, but optionally a namespace, and other characters. For example, a string containing "namespace/name" can be correctly rewritten with the addition of this configuration option - `regex: "$NAMESPACE/$NAME"`. The vCluster uses Go regular expressions to recognize the name part with the "NAME" capture group (can be written as `$NAME`), and the namespace with the "NAMESPACE" capture group (can be written as `$NAMESPACE`).
rewriteLabelKey	V->H	The keys of the `.metadata.labels` of the synced resources are rewritten by vCluster and plugins. This patch type allows you to rewrite the key references in the same way, so the fields that are referencing labels will still reference correct labels in their rewritten form. For example, the label key-value pair "app: curl" is rewritten to "vcluster.loft.sh/label-vcluster-x-a172cedcae: curl", so with this patch operation you can rewrite a field that contains "app" to "vcluster.loft.sh/label-vcluster-x-a172cedcae, and the controllers operating on the synced resources will work with this label just as expected. This is not necessary when using the ["Multi-namespace mode"].(./multi_namespace_mode.mdx).
rewriteLabelSelector	V->H	This operation exists for the same reasons as described for the rewriteLabelKey operation. It is intended to be used for the key-value map fields that represent a label selector. This patch operation will rewrite all keys in the field referenced by `path` to the expected format for the label keys, and it will also add additional key-value pairs(with virtual namespace and vCluster name) to avoid naming conflicts. This is not necessary when using the ["Multi-namespace mode"].
rewriteLabelExpressionsSelector	V->H	Similar to the `rewriteLabelSelector`, but expects `path` reference a field with the `matchLabels` and `matchExpressions` sub-fields, which will have the label keys rewritten just as described for `rewriteLabelKey`. This is not necessary when using the ["Multi-namespace mode"].

info

V->H patch operation is supported only for patches, or reverse patches, that are executed in the virtual to host direction.

Permissions​

Virtual to Host sync​

Host to Virtual sync​

Patch syntax​

Patch operations​

Permissions

Virtual to Host sync

Host to Virtual sync

Patch syntax

Patch operations