Skip to main content

Network & DNS

vcluster Networking
vcluster - Networking

By default, resources such as Service and Ingress are synced from the virtual cluster to the host cluster in order to enable correct network functionality for the vcluster.

Pod-To-Pod Traffic

Since pods are synchronized by the syncer component of the vcluster, they actually run inside the host namespace of the underlying cluster. That means that these pods have regular cluster-internal IP addresses and can communicate with each other via IP-based networking.

Pod-To-Service Traffic

By default, the vcluster also synchronizes Services (while stripping away unnecessary information from the resource) to allow pods to communicate with services. However, instead of using the DNS names of the services inside the host cluster, the vcluster has its own DNS service which allows the vcluster pods to use much more intuitive DNS mappings just as in a regular cluster.

Mapping Services between vcluster and Host Cluster

Each vcluster has its own DNS service (CoreDNS by default) which allows pods in the vcluster to get the IP addresses of services that are also running in this vcluster. The vcluster syncer ensures that the intuitive naming logic of Kubernetes DNS names for services applies and users can connect to these DNS names which in fact map to the IP address of the synchronized services that are present in the underlying host cluster.

However, this also means that you cannot directly access host services inside the virtual cluster via DNS as well as host pods can only access virtual cluster services by their synced name. vcluster offers a feature to map services from the virtual cluster to the host cluster and vice versa.

Map Host Cluster Service to vcluster Service

For example, to map a service my-host-service in the namespace my-host-namespace to the virtual cluster service my-virtual-service in the virtual cluster namespace my-virtual-namespace, you can use the following config in your values.yaml:

- from: my-host-namespace/my-host-service
to: my-virtual-namespace/my-virtual-service

With this configuration, vcluster will manage a service called my-virtual-service inside the virtual cluster that points to the host service my-host-service in namespace my-host-namespace. So pods inside the vcluster will be able to access the host service via e.g. curl

Map vcluster Service to Host Cluster Service

It is also possible to map a virtual cluster service to an host cluster service. This is especially useful if you want to expose an application that runs inside the virtual cluster to other workloads running in the host cluster. This makes it also easier to share services across vcluster's. For example, to map a virtual service my-virtual-service in the namespace my-virtual-namespace to the vcluster host namespace service my-host-service, you can use the following config in your values.yaml:

- from: my-virtual-namespace/my-virtual-service
to: my-host-service

With this configuration, vcluster will manage a service called my-host-service inside the namespace where the vcluster workloads are synced to, which points to the virtual service my-virtual-service in namespace my-virtual-namespace inside the vcluster. So pods in the host cluster will be able to access the virtual service via e.g. curl http://my-host-service.

Fallback to host DNS

If enabled, will fallback to host dns for resolving domains. This is useful if using istio or dapr in the host cluster and sidecar containers cannot connect to the central instance. Its also useful if you want to access host cluster services from within the vcluster. We can enable this feature with

fallbackHostDns: true

Ingress Controller Traffic

The vcluster has the option to enable Ingress resources synchronization. That means that you can create an ingress in a vcluster to make a service in this vcluster available via a hostname/domain. However, instead of having to run a separate ingress controller in each vcluster, the ingress resource will be synchronized to the underlying cluster (when enabled) which means that the vcluster can use a shared ingress controller that is running in the host cluster. This helps to share resources across different vclusters and is easier for users of vclusters because otherwise, they would need to install an ingress controller and manually configure DNS for each vcluster.


Before the v0.12.0 release of vcluster, the Ingress synchronization was enabled by default.

Enable Ingress Sync

If you want to use an ingress controller from the underlying cluster by synchronizing the Ingress resources, set the following in your values.yaml:

enabled: true

then create or upgrade the vcluster with:

vcluster create my-vcluster --upgrade -f values.yaml

By default, when Ingress sync is enabled, the IngressClasses will be synced from the underlying cluster to the vcluster. This can be disabled by setting the following in your values.yaml:

enabled: false

SSL Certificates

Because the syncer keeps typical SSL provisioning related annotations for ingresses, you may also set the cert-manager ingress annotations on an ingress in your vclusters to use the cert-manager of the underlying host cluster to automatically provision SSL certificates from Let's Encrypt.

Network Policies

Kubernetes has a Network Policy resource type that allows creation of the rules that govern how pods communicate with each other.

By default, vcluster ignores these resources. However, once you enable synchronization of the Network Policies, vcluster will ensure correct policies are created in the host cluster to achieve the desired traffic behaviour.


Network Policies in vcluster rely on the support for this feature in the host cluster. Make sure that your host cluster satisfies the Network Policy prerequisites.

Enable Network Policy Sync

To enable the synchronization of the Network Policy resources add the following to your values.yaml:

enabled: true

then create or upgrade the vcluster with:

vcluster create my-vcluster --upgrade -f values.yaml