Ingresses

Supported Configurations

Running the control plane as a container with:

• Shared Nodes

By default, this is disabled.

When enabled, sync all Ingress resources from the tenant cluster to the control plane cluster. Use this option to make a tenant cluster service available using a hostname/domain without having to configure DNS for each tenant cluster. This requires a compatible Ingress controller running on the control plane cluster, and a single shared controller can reconcile Ingress resources synced from multiple tenant clusters.

vCluster preserves a tenant's spec.ingressClassName unchanged, so a dedicated per-tenant IngressClass alone doesn't isolate tenants. A tenant can still name another tenant's class. Isolate tenants one of two ways:

• Namespace-scoped controller. Run a controller instance per tenant that only watches that tenant's own host namespace. This works regardless of which class a tenant names.
• Enforced class selection. Use sync.fromHost.ingressClasses with a selector, paired with control plane cluster admission. The selector alone only helps partially, since it skips the check when spec.ingressClassName is empty or when a tenant uses the legacy kubernetes.io/ingress.class annotation. Admission needs to cover both paths, plus any classless Ingress that would fall through to a default class.

Hostname claims aren't scoped to a tenant

vCluster syncs a tenant's spec.rules[].host unchanged. It doesn't rewrite or scope the hostname to that tenant. If tenant clusters share a control plane cluster ingress controller, a tenant can claim a hostname belonging to another tenant or to platform infrastructure. The controller's own conflict-resolution behavior decides which rule wins, not vCluster. See Ingress and Gateway API hostname claims in the shared-node hardening guide.

Prefer Gateway API for new workloads

For tenant traffic served by a Gateway controller on the control plane cluster, Gateway API sync is the modern alternative. It syncs Gateway, HTTPRoute, TLSRoute, ReferenceGrant, and BackendTLSPolicy, and lets tenants import host GatewayClass resources via sync.fromHost.gatewayClasses. Ingress sync remains supported for workloads that still depend on networking.k8s.io/v1 Ingress resources.

When enabled, vCluster automatically tries to detect the supported ingress version (networking.k8s.io/v1 or networking.k8s.io/v1beta1).

Sync Ingresses from the tenant to control plane cluster

sync:
  toHost:
    ingresses:
      enabled: true

Patches

Use sync.toHost.ingresses.patches to transform Ingress fields, such as spec.rules[*].host, while syncing to the control plane cluster. See Patching synced resources for syntax, directionality, and examples.

Config reference

ingresses object

Ingresses defines if ingresses created within the virtual cluster should get synced to the host cluster.

enabled boolean false

Enabled defines if this option should be enabled.

patches object[]

Patches patch the resource according to the provided specification.

path required string

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression string

Expression transforms the value according to the given JavaScript expression.

reverseExpression string

ReverseExpression transforms the value according to the given JavaScript expression.

reference object

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.

apiVersion required string

APIVersion is the apiVersion of the referenced object.

apiVersionPath string

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string

Kind is the kind of the referenced object.

kindPath string

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath string

NamePath is the optional relative path to the reference name within the object.

namespacePath string

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.

labels object

Labels treats the path value as a labels selector.