Skip to content

docs(doc-1576): add patching reference page for sync resources #2335

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
djwfyi wants to merge 4 commits into
base: main
Choose a base branch
from
+399 −163
Open

docs(doc-1576): add patching reference page for sync resources #2335

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
81ee7f7
docs(doc-1576): add sync patching reference page and fix resource links
djwfyi Jun 25, 2026
5cfc246
docs(doc-1576): expand fromHost patch table and add svg diagram
djwfyi Jun 25, 2026
8630633
docs(doc-1576): remove redundant yaml block from patching intro
djwfyi Jun 25, 2026
fc594da
docs(doc-1576): clarify fromHost expression keyword directionality
djwfyi Jun 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions static/media/diagrams/sync-patching-flow.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions vcluster/configure/vcluster-yaml/sync/README.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@ import TenancySupport from '../../../_fragments/tenancy-support.mdx';
## Resources available to sync from control plane cluster to tenant cluster
<SyncFromHostResources/>

## Patching synced resources

@github-actions github-actions Bot Jun 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Loft.imperative-headings] Headings should start with an imperative verb. 'Patching' appears to be a present participle (ends with 'ing').


Use [patching](./patching/README.mdx) to transform fields, references, and custom resource labels while resources sync between the tenant cluster and the control plane cluster.

## Config reference

<Sync/>
12 changes: 1 addition & 11 deletions vcluster/configure/vcluster-yaml/sync/from-host/configmaps.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,13 +131,7 @@ sync:

## Patches

You can specify `reverseExpression` in the `sync.fromHost.configMaps.patches` .

They are applied on the host object and appear in the virtual object.

`expressions` have no effect.

So, for the following `vcluster.yaml` :
Use `sync.fromHost.configMaps.patches` to transform ConfigMap fields while syncing from the control plane cluster to the tenant cluster. For from-host sync, use `reverseExpression` for values that should appear in the tenant cluster. See [Patching synced resources](../patching/README.mdx) for syntax and directionality.

```yaml title="configure ConfigMap sync from host with patches"
sync:
Expand All @@ -153,10 +147,6 @@ sync:
reverseExpression: "value.startsWith('www.') ? value.slice(4) : value"
```

1. Your ConfigMap in the host namespace `default` named `my-cm` is synced to the namespace `barfoo2` in virtual and named `cm-my`.
2. If `default/my-cm` host object has annotation which value starts with `www.` , e.g.: `my-address: www.loft.sh` then synced object in the tenant cluster `barfoo2/cm-my` has annotation `my-address: loft.sh` .


<FromHostConfigMapExample />

## Config reference
Expand Down
16 changes: 1 addition & 15 deletions vcluster/configure/vcluster-yaml/sync/from-host/custom-resources.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,15 +190,7 @@ sync:

### Patches

You can use patches to transform data as it syncs from the control plane cluster to the tenant cluster.

When syncing custom resources from the control plane cluster to the tenant cluster, you can use `reverseExpression` to modify the data during the sync process. The control plane cluster remains unchanged, but the tenant cluster gets the modified data.

:::note
`expressions` (used for virtual-to-host syncing) have no effect when syncing from host to virtual.
:::

The following `vcluster.yaml` shows how patches are used:
Use `sync.fromHost.customResources.<resource>.patches` to transform custom resource fields while syncing from the control plane cluster to the tenant cluster. For from-host sync, use `reverseExpression` for values that should appear in the tenant cluster. See [Patching synced resources](../patching/README.mdx) for syntax, directionality, and custom resource labels patches.

```yaml title="configure custom resource sync from host with patches"
sync:
Expand All @@ -216,12 +208,6 @@ sync:
reverseExpression: "value.startsWith('www.') ? value.slice(4) : value"
```

In the example:

- The custom resource in the host namespace `default` named `my-object` is synced to the namespace `barfoo2` in the tenant cluster and named `object-my`.

- If the `default/my-object` host object has an annotation with a value that starts with `www.` (for example: `my-address: www.loft.sh`), then the synced object in the tenant cluster `barfoo2/object-my` has the annotation `my-address: loft.sh`.

<NamespacedCustomResourcesExample/>

## Config reference
Expand Down
5 changes: 2 additions & 3 deletions vcluster/configure/vcluster-yaml/sync/from-host/nodes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@ sidebar_class_name: host-nodes
---

import SyncNodes from '../../../../_partials/config/sync/fromHost/nodes.mdx'
import Patches from '../../../../_fragments/patches.mdx'
import TenancySupport from '../../../../_fragments/tenancy-support.mdx';

<TenancySupport hostNodes="true" />
Expand Down Expand Up @@ -129,8 +128,8 @@ sync:

### Patches

<Patches resource="nodes" path="status.nodeInfo.operatingSystem" direction="fromHost" />
Use `sync.fromHost.nodes.patches` to transform node fields while syncing nodes from the control plane cluster to the tenant cluster. See [Patching synced resources](../patching/README.mdx) for syntax, directionality, and examples.

## Config reference

<SyncNodes/>
<SyncNodes/>
12 changes: 1 addition & 11 deletions vcluster/configure/vcluster-yaml/sync/from-host/secrets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,13 +130,7 @@ sync:

## Patches

You can specify `reverseExpression` in the `sync.fromHost.secrets.patches` .

They are applied on the host object and appear in the virtual object.

`expressions` have no effect.

So, for the following `vcluster.yaml` :
Use `sync.fromHost.secrets.patches` to transform Secret fields while syncing from the control plane cluster to the tenant cluster. For from-host sync, use `reverseExpression` for values that should appear in the tenant cluster. See [Patching synced resources](../patching/README.mdx) for syntax and directionality.

```yaml title="configure Secret sync from host with patches"
sync:
Expand All @@ -152,10 +146,6 @@ sync:
reverseExpression: "value.startsWith('www.') ? value.slice(4) : value"
```

1. Your Secret in the host namespace `default` named `my-cm` is synced to the namespace `barfoo2` in virtual and named `cm-my`.
2. If `default/my-cm` host object has annotation which value starts with `www.` , e.g.: `my-address: www.loft.sh` then synced object in the tenant cluster `barfoo2/cm-my` has annotation `my-address: loft.sh` .


<FromHostSecretExample />

## Config reference
Expand Down
Loading
Loading