---
title: Configuration Syntax
sidebar_label: 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"](./multi_namespace_mode.mdx) 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. 

```yaml 
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](#patch-syntax).


Example:
```yaml
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:
```yaml 
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](#patch-syntax).


Example:
```yaml
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"](./multi_namespace_mode.mdx)
:::

## 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.

<!-- //TODO: explain how ignore:true works  -->

### 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"](./multi_namespace_mode.mdx).<br/> 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. <br/>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. <br/>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`. <br/>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.
:::