Version: main 🚧

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

You can deploy CoreDNS in two modes: as a separate pod (the default) or embedded within the syncer (enterprise feature). Each mode 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 mode	Pod count per replica	Editable from virtual cluster	Corefile customization	Notes
Separate (Default)	2	Yes	Yes	CoreDNS runs as a Deployment
Embedded (Enterprise)	1	No	No	CoreDNS runs inside the syncer container in the vCluster control plane pod

Deploy separate CoreDNS

In the default configuration, 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.

In this mode, CoreDNS runs 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

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 might become 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)
Embedded

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 CoreDNS configuration

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.

Deployment types​

Deploy separate CoreDNS​

Deploy embedded CoreDNS​

Example​

Basic CoreDNS configuration​

Private registry CoreDNS configuration​

Custom CoreDNS configuration​

Embedded CoreDNS configuration​

Config reference​

coredns required object ​

enabled required boolean true ​

embedded required boolean false ​

security required object ​

podSecurityContext required object {} ​

containerSecurityContext required object {} ​

service required object ​

spec required object map[type:ClusterIP] ​

annotations required object {} ​

labels required object {} ​

deployment required object ​

image required string ​

replicas required integer 1 ​

nodeSelector required object {} ​

affinity required object {} ​

tolerations required object[] [] ​

resources required object ​

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

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

pods required object ​

annotations required object {} ​

labels required object {} ​

annotations required object {} ​

labels required object {} ​

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

overwriteConfig required string ​

overwriteManifests required string ​

priorityClassName required string ​

Deployment types

Deploy separate CoreDNS

Deploy embedded CoreDNS

Example

Basic CoreDNS configuration

Private registry CoreDNS configuration

Custom CoreDNS configuration

Embedded CoreDNS configuration

Config reference

`coredns` required object

`enabled` required boolean true

`embedded` required boolean false

`security` required object

`podSecurityContext` required object {}

`containerSecurityContext` required object {}

`service` required object

`spec` required object map[type:ClusterIP]

`annotations` required object {}

`labels` required object {}

`deployment` required object

`image` required string

`replicas` required integer 1

`nodeSelector` required object {}

`affinity` required object {}

`tolerations` required object[] []

`resources` required object

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

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

`pods` required object

`annotations` required object {}

`labels` required object {}

`annotations` required object {}

`labels` required object {}

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

`overwriteConfig` required string

`overwriteManifests` required string

`priorityClassName` required string