docs(doc-1389): add gateway api sync examples and cli guidance

hack/vcluster/partials/main.go

@@ -61,6 +61,7 @@ var paths = []string{
 	"sync/toHost/services",
 	"sync/toHost/networkPolicies",
 	"sync/toHost/ingresses",
+	"sync/toHost/gatewayApi",
 	"sync/toHost/endpoints",
 	"sync/toHost/endpointSlices",
 	"sync/toHost/secrets",
@@ -73,6 +74,7 @@ var paths = []string{
 	"sync/fromHost/storageClasses",
 	"sync/fromHost/nodes",
 	"sync/fromHost/ingressClasses",
+	"sync/fromHost/gatewayClasses",
 	"sync/fromHost/events",
 	"sync/fromHost/runtimeClasses",
 	"sync/fromHost/priorityClasses",

vcluster/_fragments/patches.mdx

@@ -41,17 +41,17 @@ You can define a path for <code>{props.path}</code> field in `vcluster.yaml` usi
       - path: ${props.path}
         expression: '"my-prefix-"+value'
         # optional reverseExpression to reverse the change from the Control Plane Cluster
-        # reverseExpression: 'value.slice("my-prefix".length)'`}
+        # reverseExpression: 'value.slice("my-prefix-".length)'`}
 </CodeBlock>
 
 In the example:
 
-  - The path targets the <code>{props.path}</code> field to override when syncing to the Control Plane Cluster. The `*` wildcard applies the patch to each container individually.
-  - `"'my-prefix-' + value"` defines a JavaScript expression that prepends `"my-prefix-"` to the <code>{props.path}</code> field in the Control Plane Cluster.
+- The path targets the <code>{props.path}</code> field to override when syncing to the Control Plane Cluster. The `*` wildcard applies the patch to each matching value individually.
+- `"'my-prefix-' + value"` defines a JavaScript expression that prepends `"my-prefix-"` to the <code>{props.path}</code> field in the Control Plane Cluster.
 
 :::note Reverse sync
 You can use the `reverseExpression` field to define how to revert changes when syncing from the Control Plane Cluster back to the tenant cluster.
-For example, add `reverseExpression: {"value.slice('my-prefix'.length)"}` to `vcluster.yaml` to remove the `"my-prefix-"` prefix when syncing back from the Control Plane Cluster to the tenant cluster in the previous example.
+For example, add `reverseExpression: 'value.slice("my-prefix-".length)'` to `vcluster.yaml` to remove the `"my-prefix-"` prefix when syncing back from the Control Plane Cluster to the tenant cluster in the previous example.
 :::
 
 To replace value with a hardcoded one, put the desired value in the quotation marks:
@@ -115,12 +115,11 @@ To prevent unintended modifications of the synced objects in either direction, d
 ```yaml title="Use expression and reverseExpression together"
 sync:
   toHost:
-    secrets:
+    <resource>:
       enabled: true
       patches:
       - path: metadata.annotations["encoded-value"]
         expression: 'btoa(value)'
-      - path: metadata.annotations["encoded-value"]
         reverseExpression: 'atob(value)'
 ```
 :::
@@ -146,7 +145,7 @@ For example, if the Control Plane Cluster contains a secret named `"my-example-s
 
 Workloads in the tenant cluster can then use the secret without manual syncing.
 
-You can sync between the tenant cluster and the Control Plane Cluster by mapping `spec.secretName` to a secret in the Control Plane Cluster:
+You can sync between the tenant cluster and the Control Plane Cluster by treating a field value as a Secret reference:
 
 <CodeBlock language="yaml">
 {`sync:
@@ -162,8 +161,8 @@ You can sync between the tenant cluster and the Control Plane Cluster by mapping
 
 In the example:
 
-- The code uses a patch to add `metadata.annotations["my-secret-ref"]`
-- It references a Secret in the Control Plane Cluster using the patch and ensures <code>{props.resource}</code> in the Control Plane Cluster links to the correct Secret.
+- The patch treats `metadata.annotations["my-secret-ref"]` as the name of a Secret reference.
+- vCluster rewrites the field to the corresponding Secret name in the target cluster and syncs or imports the referenced Secret when the resource is configured for syncing.
 
 :::note Reference Patches with Namespace Syncing
 If you have enabled syncing namespaces, reference patches are only required if the namespace is part of the patch. You can use the `namespacePath` option to specify the path of the namespace of the reference.

vcluster/_partials/config/sync/fromHost.mdx

@@ -815,6 +815,309 @@ Selector defines the selector to use for the resource. If not set, all resources
 
 
 
+<details className="config-field" data-expandable="true">
+<summary>
+
+### `gatewayClasses` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">object</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses}
+
+GatewayClasses defines if gateway classes should get synced from the host cluster to the virtual cluster, but not back. When enabled, host GatewayClasses are the source of truth and virtual-only GatewayClasses are deleted.
+
+</summary>
+
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+#### `enabled` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">boolean</span> <span className="config-field-default">false</span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-enabled}
+
+Enabled defines if this option should be enabled.
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="true">
+<summary>
+
+#### `patches` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">object[]</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches}
+
+Patches patch the resource according to the provided specification.
+
+</summary>
+
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `path` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches-path}
+
+Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `expression` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches-expression}
+
+Expression transforms the value according to the given JavaScript expression.
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `reverseExpression` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches-reverseExpression}
+
+ReverseExpression transforms the value according to the given JavaScript expression.
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="true">
+<summary>
+
+##### `reference` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">object</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches-reference}
+
+Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode
+automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with
+other names, in multi-namespace mode this will not translate the name.
+
+</summary>
+
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `apiVersion` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches-reference-apiVersion}
+
+APIVersion is the apiVersion of the referenced object.
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `apiVersionPath` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches-reference-apiVersionPath}
+
+APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `kind` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches-reference-kind}
+
+Kind is the kind of the referenced object.
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `kindPath` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches-reference-kindPath}
+
+KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `namePath` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches-reference-namePath}
+
+NamePath is the optional relative path to the reference name within the object.
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `namespacePath` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches-reference-namespacePath}
+
+NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the
+metadata.namespace path of the object.
+
+</summary>
+
+
+
+</details>
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="true">
+<summary>
+
+##### `labels` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">object</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-patches-labels}
+
+Labels treats the path value as a labels selector.
+
+</summary>
+
+
+
+</details>
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="true">
+<summary>
+
+#### `selector` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">object</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-selector}
+
+Selector defines the selector to use for the resource. If not set, all resources of that type will be synced.
+
+</summary>
+
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `matchLabels` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">object</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-selector-matchLabels}
+
+
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="true">
+<summary>
+
+##### `matchExpressions` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">object[]</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-selector-matchExpressions}
+
+
+
+</summary>
+
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `key` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-selector-matchExpressions-key}
+
+
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `operator` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-selector-matchExpressions-operator}
+
+
+
+</summary>
+
+
+
+</details>
+
+
+
+<details className="config-field" data-expandable="false" open>
+<summary>
+
+##### `values` <span className="config-field-required" data-required="false">required</span> <span className="config-field-type">string[]</span> <span className="config-field-default"></span> <span className="config-field-enum"></span> {#fromHost-gatewayClasses-selector-matchExpressions-values}
+
+
+
+</summary>
+
+
+
+</details>
+
+
+</details>
+
+
+</details>
+
+
+</details>
+
+
+
 <details className="config-field" data-expandable="true">
 <summary>