Resource Proxy

Enterprise-Only Feature

This feature is an Enterprise feature. See our pricing plans or contact our sales team for more information.

vCluster Platform required

This feature requires vCluster Platform. Both the client and target tenant clusters must be managed as VirtualClusterInstance within the platform.

The Resource Proxy feature enables vClustervClusterAn open-source software product that creates and manages tenant clusters within Kubernetes infrastructure. vCluster provides tenant isolation capabilities while reducing infrastructure costs.Related: Tenant cluster, Control plane cluster to proxy requests for custom resources defined by CustomResourceDefinitions (CRDs) to other tenant clusters. When enabled, the client tenant clusterTenant clusterA fully isolated Kubernetes environment provisioned for a single tenant. Each tenant cluster has its own API server, controller manager, and resource namespace, backed by a virtualized control plane hosted on a control plane cluster. From the tenant's perspective it behaves exactly like a standard Kubernetes cluster.Related: Control plane cluster, Tenant cluster transparently forwards resource operations to a target tenant cluster, where the objects are stored and can be managed by controllers running there.

This page covers the vcluster.yaml fields. For the mechanism, see How the resource proxy works. To set one up, see Set up the resource proxy. For ongoing operation and monitoring, see Operate the resource proxy. If something's broken, see Troubleshoot the resource proxy.

Configuration

To enable resource proxying, configure the experimental.proxy.customResources section in your vcluster.yaml:

vcluster.yaml

# Basic Resource Proxy configuration
# Enables group/version-wide proxying for example.com/v1 to a target tenant cluster.
# The explicit resource name is advertised by synthetic fallback discovery.
experimental:
  proxy:
    customResources:
      myresources.example.com/v1:
        enabled: true
        targetVirtualCluster:
          name: "target"

Configuration options

Field	Type	Default	Description
customResources	map[string]CustomResourceProxy	{}	Map of resource keys to proxy configuration.
customResources.<key>.enabled	boolean	false	Enable the proxy for this resource.
customResources.<key>.targetVirtualCluster	VirtualClusterRef	-	Reference to the target VirtualClusterInstance to proxy requests to.
customResources.<key>.targetVirtualCluster.name	string	-	Name of the target tenant cluster. Required for every entry, including disabled entries.
customResources.<key>.targetVirtualCluster.project	string	Same as client	Project of the target tenant cluster. Defaults to the same project as the client vCluster.
customResources.<key>.accessResources	string	"owned"	Resource visibility mode: owned or all. See Access modes.

Resource key format

The resource key follows the format resource.apiGroup/version:

• myresources.example.com/v1 - enables the proxy for the example.com/v1 group and version and advertises myresources in fallback discovery
• otherresources.test.io/v2 - enables the proxy for the test.io/v2 group and version and advertises otherresources in fallback discovery
• additionalresources.acme.org/v1alpha1 - enables the proxy for the acme.org/v1alpha1 group and version and advertises additionalresources in fallback discovery

Proxy registration is group/version-wide

An enabled entry registers one Kubernetes APIService for the entry's entire API group and version. While the target is reachable, the proxy forwards discovery for that group and version to the target and can route requests for every resource the target advertises. The resource name in an explicit key doesn't restrict live requests to that resource.

Use RBAC in the target tenant cluster to restrict the resource kinds and operations available to a client. All enabled entries for the same group and version must use the same target and access mode.

For entries that share a group and version, write equivalent settings identically. Validation compares the configured values before applying defaults. Either omit accessResources from every entry or set the same explicit value on every entry. Likewise, either omit targetVirtualCluster.project from every entry or set the same explicit project on every entry. Mixing an omitted value with its explicit default is rejected.

Wildcard group and version entry

You can use * in place of an explicit resource name:

• *.example.com/v1 - enables the proxy for the example.com/v1 group and version
• *.test.io/v2 - enables the proxy for the test.io/v2 group and version

Wildcard and explicit entries have the same group/version-wide behavior while the target is reachable. They differ when the target is unavailable. Explicit entries give the proxy resource names for its synthetic fallback discovery document, while a wildcard doesn't.

Prefer explicit resource keys over wildcards where you can, and list each resource that clients depend on during an outage. With explicit keys such as myresources.example.com/v1, fallback discovery continues to advertise the configured resource names when the target is briefly unreachable. The fallback is synthetic. It reports resources as namespaced, derives singular names and kinds mechanically, and advertises only the get verb. Treat only the configured resource names as dependable. With *.example.com/v1, discovery degrades to an empty list, which some controllers and CLIs handle poorly. See Discovery lists resources with only a get verb, or an empty list.

Wildcard and explicit entries are mutually exclusive

A wildcard key (for example *.example.com/v1) and an explicit key (for example myresources.example.com/v1) cannot both be enabled for the same group and version. vCluster rejects that combination at startup. A disabled explicit entry (enabled: false) does not conflict with a wildcard for the same group and version.

For worked examples of this configuration, including multi-target and cross-project setups, see Set up the resource proxy.

Access modes

The accessResources field controls which resources a client tenant cluster can see through the proxied API group and version:

Access modes configuration

# Access modes configuration examples

# Example 1: "owned" mode (default)
# The tenant cluster only sees objects with its ownership labels
experimental:
  proxy:
    customResources:
      myresources.example.com/v1:
        enabled: true
        targetVirtualCluster:
          name: "target"
        # accessResources defaults to "owned" - only see resources we created

---
# Example 2: "all" mode
# The proxy doesn't filter by owner; target RBAC still applies
experimental:
  proxy:
    customResources:
      myresources.example.com/v1:
        enabled: true
        targetVirtualCluster:
          name: "target"
        accessResources: all  # Disable ownership filtering

owned mode - default

The proxy presents each client tenant cluster only objects with matching ownership labels. It normally adds those labels to objects the client creates. This enables tenant isolationTenant IsolationThe capability to host multiple separate users, teams, or workloads on the same infrastructure while providing strong isolation between them. vCluster delivers tenant isolation through dedicated control planes, isolated resource namespaces, and optional private nodes per tenant.Related: Tenant cluster where multiple client tenant clusters can share a target without seeing each other's resources.

Stay on accessResources: owned unless you have a reason not to. Each client sees and manages only objects with its ownership labels. The proxy normally adds those labels when the client writes an object. Lists and watches are filtered by an injected label selector, and named GET, PUT, PATCH, and DELETE requests for objects it doesn't own return 404. This is visibility isolation, not name allocation. Two clients creating the same object name in the same target namespace still collide, and the second create normally returns 409 from the target. Give each client its own namespace or its own name prefix.

all mode

The proxy doesn't filter objects by ownership. Target RBAC still determines which resource kinds and operations the client can access. This is useful for read-only observers, centralized dashboards, or admin access.

Use all only when the client must manage objects it didn't create, and treat that client as privileged. The mode removes ownership filtering, so target RBAC can permit the client to read, mutate, and delete objects owned by other tenant clusters.

Combine access modes with RBAC

The accessResources mode controls visibility - what resources a tenant cluster can see. RBAC in the target tenant cluster controls permissions - what operations the tenant cluster can perform.

For example, a tenant cluster with accessResources: all but read-only RBAC can see all resources that its target RBAC permits but can't modify any.

For a worked multi-client example, see Set up the resource proxy.

Limitations

• All CustomResources within the same API GroupVersion must use the same target tenant cluster and access mode. Validation enforces that all entries for a group and version agree on targetVirtualCluster and accessResources. Split API groups if two targets must serve sibling resources.
• An enabled API group can't appear in both experimental.proxy.customResources and either sync.toHost.customResources or sync.fromHost.customResources. Validation checks the entire API group, regardless of resource name or version. Disabled entries don't conflict.
• Proxy routing is group/version-wide. An explicit resource key doesn't prevent access to sibling resources that the target advertises in that group and version. Restrict sibling resources with target RBAC.
• In owned mode, named PUT, PATCH, and DELETE requests require target RBAC permission to get the resource as well as permission for the requested mutation. The proxy performs a GET first to verify ownership. If that GET is forbidden, the mutation is masked as a 404.
• Connection upgrade verbs such as exec, attach, and port-forward aren't supported through the proxy. See Connection upgrades return 501.
• When configuring RBAC for status updates, include permissions for the status subresource.

Find content that moved off this page

This page used to include the full explanation, setup walkthrough, monitoring guide, and troubleshooting steps for the resource proxy. That content moved to dedicated pages, so a bookmarked link to a section below may land here instead of on the section itself. Here's where things went:

• How it works, key capabilities, connection path, and peer-health thresholds → How the resource proxy works

• Platform RBAC and the setup examples → Set up the resource proxy

• DERP relay tuning and the monitoring guide → Operate the resource proxy

• Troubleshooting steps and the log reference → Troubleshoot the resource proxy

• The typed config reference tables → merged into Configuration options above

• Best practices → distributed into the sections above: explicit resource keys under Wildcard group and version entry, staying on owned mode under Access modes, and the rest into Operate the resource proxy and Troubleshoot the resource proxy