CoreDNS

Each virtual cluster runs its own DNS service using CoreDNS. This allows pods and services inside the virtual 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 virtual cluster cannot resolve names for services that only exist in the host cluster. Similarly, pods in the host cluster cannot discover services that only exist inside a virtual cluster. DNS resolution works entirely within the boundaries of the virtual cluster unless you configure external mappings explicitly.

note

CoreDNS in the virtual cluster listens on port 1053, not the DNS port 53. This avoids privilege issues, especially when multiple virtual clusters run on the same host cluster. Port 53 is a privileged port and typically requires elevated permissions to bind. Blocked access to port 1053 prevents DNS resolution within the virtual 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 virtual cluster requires, and whether users can access and customize the CoreDNS configuration from inside the virtual cluster.

Deployment Type	Pod count per replica	Editable from virtual 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 virtual 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 virtual 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 virtual 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

Limited vCluster Tenancy Configuration Support

This feature is only available when using the following worker node types:

Host Nodes

Enterprise-Only Feature

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

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 virtual 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 host 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

Limited vCluster Tenancy Configuration Support

This feature is only available when using the following worker node types:

Host Nodes

Enterprise-Only Feature

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

Embedded CoreDNS enterprise configuration

controlPlane:
  coredns:
    enabled: true
    embedded: true

Config reference

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

coredns required object

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

enabled required boolean true

Enabled defines if coredns is enabled

embedded required 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 required object

Security defines pod or container security context.

podSecurityContext required object {}

PodSecurityContext specifies security context options on the pod level.

containerSecurityContext required object {}

ContainerSecurityContext specifies security context options on the container level.

service required object

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

spec required object map[type:ClusterIP]

Spec holds extra options for the coredns service

annotations required object {}

Annotations are extra annotations for this resource.

labels required object {}

Labels are extra labels for this resource.

deployment required object

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

image required string

Image is the coredns image to use

replicas required integer 1

Replicas is the amount of coredns pods to run.

nodeSelector required object {}

NodeSelector is the node selector to use for coredns.

affinity required object {}

Affinity is the affinity to apply to the pod.

tolerations required object[] []

Tolerations are the tolerations to apply to the pod.

resources required object

Resources are the desired resources for coredns.

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

Limits are resource limits for the container

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

Requests are minimal resources that will be consumed by the container

pods required object

Pods is additional metadata for the coredns pods.

annotations required object {}

Annotations are extra annotations for this resource.

labels required object {}

Labels are extra labels for this resource.

annotations required object {}

Annotations are extra annotations for this resource.

labels required object {}

Labels are extra labels for this resource.

topologySpreadConstraints required 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 required string

OverwriteConfig can be used to overwrite the coredns config

overwriteManifests required string

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

priorityClassName required string

PriorityClassName specifies the priority class name for the CoreDNS pods.