edit patches text

change file location

change file location

change file location

change file location

change file location

change file location

change file location

change file location

change file location

change file location

change file location

remove admonitions

change file location

change file location

change file location

update

update link

update link

update link

update link

update link

update link

update link

update link

update link

update first line

updates for linter

update text for clarity

update text for consistency

slight rewrite

Author: joaniekube

vcluster/_fragments/patches.mdx

@@ -3,38 +3,71 @@ import CodeBlock from '@theme/CodeBlock';
 
 <ProAdmonition/>
 
-You can modify the sync behaviour with patches that target specific paths. Currently there is 2 different kinds of patches supported.
+Patches override the default resource syncing rules in your vCluster YAML configurations.
 
-:::info Wildcard patches
-You can use `*` in paths to select all entries of an array or object, e.g. `spec.containers[*].name` or `spec.containers[*].volumeMounts[*]`. vCluster calls the patch multiple times when using the wildcard reference.
+By default, vCluster [syncs specific resources](https://www.vcluster.com/docs/vcluster/next/configure/vcluster-yaml/sync/) between virtual and host clusters. To modify the sync behavior, you can use patches to specify which fields to edit, exclude, or override during syncing.
+
+Patches can provide greater control over syncing by preventing unintended changes, preserving critical settings, and ensuring only necessary updates are applied.
+
+vCluster supports two patch types:
+
+- [JavaScript expression patch](#javascript-expression-patch): Uses JavaScript ES6 expressions to dynamically modify fields during syncing. You can define how a field changes when syncing from a virtual cluster to a host cluster, or from a host cluster to a virtual cluster.
+- [Reference patch](#reference-patch): Modifies specific fields within a resource to point to different resources. If the specified resource exists in a host cluster, vCluster automatically imports it into the corresponding virtual cluster.
+
+:::info Using wildcards in patches
+You can apply a wildcard, using an asterisk (`*`) in a specified path, to modify all elements of an array or object.
+For instance, `spec.containers[*].name` selects the `name` field of every container in the `spec.containers` array, and `spec.containers[*].volumeMounts[*]` selects all `volumeMounts` for each container. 
+When using the asterisk (`*`) notation, vCluster applies changes individually to every element that matches the path.
 :::
 
-### JavaScript Expression Patches
+### JavaScript expression patch
+
+A JavaScript expression patch allows you to use JavaScript ES6 expressions to change specific fields when syncing between virtual and host clusters. 
+This is useful when modifying resource configurations to align with differing environments or naming conventions between clusters.
+
+For example, if your virtual cluster follows a specific naming convention for container names, but the host cluster requires a different prefix, you can use a JavaScript expression patch to automatically update the relevant field for each container.
+
+You can define a path for `spec.containers[*].name` in `vcluster.yaml` using the following configuration:
 
-These are powerful JavaScript ES6 compatible expression patches that can be used to change a field while syncing. You define how it changes when syncing from the virtual cluster into the host cluster or when syncing from the host cluster into the virtual cluster. To change the path <span>{props.path}</span> you can do:
 <CodeBlock language="yaml">
-{`sync:
+{`
+sync:
   toHost:
-    ${props.resource}:
-      enabled: true
-      patches:
-      - path: ${props.path}
-        expression: '"my-prefix-"+value'
-        # optional reverseExpression to reverse the change from the host cluster
-        # reverseExpression: 'value.slice("my-prefix".length)'`}
+    enabled: true
+    patches:
+    - path: spec.containers[*].name
+      expression: "'my-prefix-' + value"
+`}
 </CodeBlock>
 
-There is also a variable called `context` besides `value` that can be used to access specific data of the virtual cluster:
-* `context.vcluster.name`: Name of the virtual cluster
-* `context.vcluster.namespace`: Namespace of the virtual cluster
-* `context.vcluster.config`: Config of the virtual cluster, basically `vcluster.yaml` merged with the defaults
-* `context.hostObject`: Host object (can be null if not available)
-* `context.virtualObject`: Virtual object (can be null if not available)
-* `context.path`: The matched path on the object, useful when using wildcard path selectors (*)
+In the example:
+
+  - `spec.containers[*].name` targets the `name` field of all containers within a Pod. The `*` wildcard applies the patch to each container individually.
+  - `"'my-prefix-' + value"` defines a JavaScript expression that prepends `"my-prefix-"` to each container name during syncing.
+
+:::note Reverse sync
+You can use the `reverseExpression` field to define how to revert changes when syncing from the host cluster back to the virtual cluster.
+For example, add `reverseExpression: {"value.slice('my-prefix'.length)"}` to `vcluster.yaml` to remove the `"my-prefix-"` prefix when syncing back from the host cluster to the virtual cluster in the previous example.
+:::
+
+#### Context variable
 
-### Reference patches
+The context variable is an object supported in JavaScript expression patches, that provides access to virtual cluster data during syncing. The context object includes the following properties:
+
+* `context.vcluster.name`: Name of the virtual cluster.
+* `context.vcluster.namespace`: Namespace of the virtual cluster.
+* `context.vcluster.config`: Configuration of the virtual cluster, basically `vcluster.yaml` merged with the defaults.
+* `context.hostObject`: Host object (`null` if not available).
+* `context.virtualObject`: Virtual object (`null` if not available).
+* `context.path`: Matched path on the object, useful when using wildcard path selectors (`*`).
+
+### Reference patch
+
+A reference patch allows you to link a field in one resource to another resource. During syncing, vCluster rewrites the reference and imports the linked resource from a host cluster into its corresponding virtual cluster, if the resource exists.
+You can use reference patches to share resources, such as `Secrets` or `ConfigMaps`, between clusters without manually recreating or duplicating them.
+
+For example, if you have a custom resource in your virtual cluster that references a `Secret` named `my-secret-ref`, you can define a reference patch in your `vcluster.yaml` using the following configuration:
 
-A reference patch can be used to have a specific field of one resource point to a different resource that should get rewritten. vCluster automatically imports the referenced resource to the virtual cluster if it can find it in the host cluster. For example:
 <CodeBlock language="yaml">
 {`sync:
   toHost:
@@ -47,8 +80,10 @@ A reference patch can be used to have a specific field of one resource point to
           kind: Secret`}
 </CodeBlock>
 
-With this yaml, vCluster translates the path `metadata.annotations["my-secret-ref"]` as it points to a secret. If the secret is created in the host cluster, vCluster automatically imports it into the virtual cluster.
+In the example:
+
+  - `metadata.annotations["my-secret-ref"]` points to a `Secret`. The `Secret` is created in the host cluster and vCluster automatically imports it into the virtual cluster.
 
-:::info Multi-Namespace-Mode
-With multi-namespace-mode you only need to rewrite references that include a namespace. You can use the `namespacePath` option to specify the path of the namespace of the reference.
+:::info Multi namespace mode
+With multi-namespace mode you only need to rewrite references that include a namespace. You can use the `namespacePath` option to specify the path of the namespace of the reference.
 :::