Skip to main content
Version: v0.35

Resolve DNS

Supported Configurations
Running the control plane as a container with:

This feature enables adding custom DNS rules to the 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 to allow communication with services deployed in the control planeControl PlaneThe container orchestration layer that exposes the API and interfaces to define, deploy, and manage the lifecycle of containers. In vCluster, each tenant cluster has its own control plane components.Related: API Server, vCluster cluster and across services in separate 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 instances.

Examples​

note

Enable embedded CoreDNS to ensure DNS resolution works inside the vCluster. Without this setting, DNS queries inside the vCluster, such as resolving services or external domains, fail. Ensure the following is added to vcluster.yaml or Helm values file:

controlPlane:
  coredns:
    enabled: true
    embedded: true

Map a hostname​

This is a URL-based mapping of one tenant cluster hostname to another hostname. A wikipedia.com DNS lookup would return a DNS response with answer as en.wikipedia.org.

controlPlane:
  coredns:
    enabled: true
    embedded: true 
networking:
  resolveDNS:
    - hostname: wikipedia.com
      target:
        hostname: en.wikipedia.org

Map a hostname wildcard​

This is a URL-based mapping of one tenant cluster hostname to another hostname. A test.svc.kubernetes DNS lookup would return a DNS response with answer as test.svc.cluster.local.

controlPlane:
  coredns:
    enabled: true
    embedded: true 
networking:
  resolveDNS:
    - hostname: *.svc.kubernetes
      target:
        hostname: *.svc.cluster.local

Map a tenant cluster service to a control plane cluster service​

This example maps the tenant cluster's my-namespace/my-svc resource to the control plane clusterControl plane clusterThe Kubernetes cluster that hosts the virtualized control planes for tenant clusters. The control plane cluster is operated by the platform provider and is completely invisible to tenants. There are no shared control plane nodes, no in-cluster agent pods, and no lateral path between tenant environments. With shared nodes, this cluster also runs tenant workloads alongside the control plane pods — the same node pool is used for both.Related: Tenant cluster, Control plane cluster, Tenant cluster's dns-test/nginx-svc resource. The DNS response is the nginx-svc IP in the host's dns-test namespace.

controlPlane:
  coredns:
    enabled: true
    embedded: true 
networking:
  resolveDNS:
    - service: my-namespace/my-svc
      target:
        hostService: dns-test/nginx-svc
Kubelet image pulls aren't covered by this mapping

This mapping is a tenant cluster CoreDNS record, so it works for a process inside a pod that resolves the hostname itself, such as an application calling a private registry directly. It doesn't help the kubelet pull container images referenced in a pod's image: field. On shared nodes, the container runtime uses the underlying node's DNS, not the tenant cluster's CoreDNS. See Use a control plane cluster registry from a tenant cluster.

Map services across vCluster instances​

This example maps a tenant cluster Service to another Service in a separate tenant cluster. my-ns-in-vcluster/my-svc-vcluster maps to dns-test-in-vcluster-ns/test-in-vcluster-service in a vCluster instance named test-cluster deployed in the host namespace test-vcluster-ns.

controlPlane:
  coredns:
    enabled: true
    embedded: true 
networking:
  resolveDNS:
    - service: my-ns-in-vcluster/my-svc-vcluster
      target:
        vClusterService: test-vcluster-ns/test-vcluster/dns-test-in-vcluster-ns/test-in-vcluster-service

Map namespaces​

Map all services under a tenant cluster namespace to a host namespace. This host namespace could also contain another vCluster instance, thereby mapping all vCluster services to another vCluster instance.

controlPlane:
  coredns:
    enabled: true
    embedded: true 
networking:
  resolveDNS:
    - namespace: test-in-vcluster-ns
      target:
        hostNamespace: external-vc-ns

All services in the test-vcluster tenant cluster's target namespace test-in-vcluster-ns map to namespace external-vc-ns.

    ┌──────────────────────┐┌──────────────────────────────┐
    │nginx.external-vc-ns  ││nginx.test-in-vcluster-ns     │
    │svcA.external-vc-ns   ││svcA.test-in-vcluster-ns      │
    │svcB.external-vc-ns   ││svcB.test-in-vcluster-ns      │
    │...                   ││...                           │
    └──────────────────────┘└──────────────────────────────┘

Config reference​

resolveDNS object[] ​

ResolveDNS allows to define extra DNS rules. This only works if embedded coredns is configured.

hostname string ​

Hostname is the hostname within the vCluster that should be resolved from.

service string ​

Service is the virtual cluster service that should be resolved from.

namespace string ​

Namespace is the virtual cluster namespace that should be resolved from.

target object ​

Target is the DNS target that should get mapped to

hostname string ​

Hostname to use as a DNS target

ip string ​

IP to use as a DNS target

hostService string ​

HostService to target, format is hostNamespace/hostService

hostNamespace string ​

HostNamespace to target

vClusterService string ​

VClusterService format is hostNamespace/vClusterName/vClusterNamespace/vClusterService