CoreDNS

		Enterprise
Available in these plans	Free	Dev	Prod	Scale
Built-In CoreDNS

Each tenant cluster runs its own DNS service using CoreDNS. This allows pods and services inside the tenant cluster to discover each other using standard Kubernetes DNS names such as my-service.default.svc.cluster.local. The syncer syncs the services necessary for DNS to function as expected.

This setup means that applications inside the tenant cluster cannot resolve names for services that only exist in the control plane cluster. Similarly, pods in the control plane cluster cannot discover services that only exist inside a tenant cluster. DNS resolution works entirely within the boundaries of the tenant cluster unless you configure external mappings explicitly.

note

CoreDNS in the tenant cluster listens on port 1053, not the DNS port 53. This avoids privilege issues, especially when multiple tenant clusters run on the same control plane cluster. Port 53 is a privileged port and typically requires elevated permissions to bind. Blocked access to port 1053 prevents DNS resolution within the tenant cluster.

Deployment types

CoreDNS can deploy in two methods, either as a separate pod (default) or CoreDNS components can be embedded as part of the vCluster control plane pod. Each deployment type affects how the DNS service operates, how many pods the tenant cluster requires, and whether users can access and customize the CoreDNS configuration from inside the tenant cluster.

Deployment Type	Pod count per replica	Editable from tenant cluster	Corefile customization	Notes
Separate (Default)	2	Yes	Yes	CoreDNS runs as a Deployment
Embedded	1	No	No	CoreDNS runs inside the syncer container in the vCluster control plane pod

Deploy separate CoreDNS

By default, vCluster creates a dedicated CoreDNS pod. The tenant cluster deployment includes two pods: one pod for the API server and syncer, and another for CoreDNS.

CoreDNS is deployed as a standard Kubernetes deployment inside the tenant cluster. Users can view and modify the CoreDNS deployment using standard Kubernetes tools. DNS configuration is accessible, and you can apply changes or troubleshoot without restarting the tenant cluster's control plane.

Configuration Persistence

Configuration changes applied directly to CoreDNS are not persistent. They get overwritten when the vCluster control plane pod restarts and the original vcluster.yaml configuration is re-applied.

Deploy embedded CoreDNS

Supported Configurations

Running the control plane as a container with:

• Shared Nodes

The embedded CoreDNS feature allows you to run CoreDNS as part of the syncer, which saves the resources of an external CoreDNS pod. This consolidates all tenant cluster components into a single pod and optimizes resource allocation. It also enables advanced DNS features like custom hostname mapping, cross-vCluster service resolution, and communication with control plane cluster services.

The embedded approach requires consideration of operational trade-offs. Troubleshooting becomes more complex since DNS and sync functions share the same container and process space. Updates and restarts affect both DNS and sync capabilities simultaneously, though all CoreDNS features remain supported.

Example

The configuration you choose depends on your deployment model. The following examples show how to configure CoreDNS for each supported mode.

Separate (Default)

Based on the config reference you provided, here are the correct configurations:

Basic CoreDNS configuration

Basic CoreDNS configuration

controlPlane:
  coredns:
    enabled: true
    deployment:
      replicas: 1
      resources:
        requests:
          cpu: 20m
          memory: 32Mi
        limits:
          cpu: 100m
          memory: 128Mi

Private registry CoreDNS configuration

Private registry CoreDNS configuration

controlPlane:
  coredns:
    deployment:
      image: "registry.company.com/coredns"

# imagePullSecrets must be configured at the root level
# since it's not available in the coreDNS configuration
imagePullSecrets:
  - name: company-registry-credentials

Custom CoreDNS configuration

Custom CoreDNS configuration

controlPlane:
  coredns:
    overwriteConfig: |
      .:1053 {
          errors
          health
          ready
          kubernetes cluster.local in-addr.arpa ip6.arpa {
              pods insecure
              fallthrough in-addr.arpa ip6.arpa
              ttl 30
          }
          prometheus :9153
          forward . /etc/resolv.conf
          cache 30
          loop
          reload
      }

Embedded

Embedded CoreDNS configuration

Supported Configurations

Running the control plane as a container with:

• Shared Nodes

Embedded CoreDNS configuration

controlPlane:
  coredns:
    enabled: true
    embedded: true

Config reference

Deprecated Field	New Field
coredns.config	coredns.overwriteConfig
coredns.manifests	coredns.overwriteManifests

coredns object

CoreDNS defines everything related to the coredns that is deployed and used within the vCluster.

enabled boolean true

Enabled defines if coredns is enabled

embedded boolean false

Embedded defines if vCluster will start the embedded coredns service within the control-plane and not as a separate deployment. This is a PRO feature.

security object

Security defines pod or container security context.

podSecurityContext object {}

PodSecurityContext specifies security context options on the pod level.

containerSecurityContext object {}

ContainerSecurityContext specifies security context options on the container level.

service object

Service holds extra options for the coredns service deployed within the virtual cluster

spec object map[type:ClusterIP]

Spec holds extra options for the coredns service

annotations object {}

Annotations are extra annotations for this resource.

labels object {}

Labels are extra labels for this resource.

deployment object

Deployment holds extra options for the coredns deployment deployed within the virtual cluster

image string

Image is the coredns image to use

replicas integer 1

Replicas is the amount of coredns pods to run.

nodeSelector object {}

NodeSelector is the node selector to use for coredns.

affinity object {}

Affinity is the affinity to apply to the pod.

tolerations object[] []

Tolerations are the tolerations to apply to the pod.

resources object

Resources are the desired resources for coredns.

limits object map[cpu:1000m memory:170Mi]

Limits are resource limits for the container

requests object map[cpu:20m memory:64Mi]

Requests are minimal resources that will be consumed by the container

pods object

Pods is additional metadata for the coredns pods.

annotations object {}

Annotations are extra annotations for this resource.

labels object {}

Labels are extra labels for this resource.

annotations object {}

Annotations are extra annotations for this resource.

labels object {}

Labels are extra labels for this resource.

topologySpreadConstraints object[] [map[labelSelector:map[matchLabels:map[k8s-app:vcluster-kube-dns]] maxSkew:1 topologyKey:kubernetes.io/hostname whenUnsatisfiable:DoNotSchedule]]

TopologySpreadConstraints are the topology spread constraints for the CoreDNS pod.

overwriteConfig string

OverwriteConfig can be used to overwrite the coredns config

overwriteManifests string

OverwriteManifests can be used to overwrite the coredns manifests used to deploy coredns

priorityClassName string

PriorityClassName specifies the priority class name for the CoreDNS pods.