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.
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 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​
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​
controlPlane:
coredns:
enabled: true
deployment:
replicas: 1
resources:
requests:
cpu: 20m
memory: 32Mi
limits:
cpu: 100m
memory: 128Mi
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​
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​
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.
coredns
required object ​enabled
required boolean true ​
Enabled defines if coredns is enabled
enabled
required boolean true ​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.
embedded
required boolean false ​security
required object ​
Security defines pod or container security context.
security
required object ​service
required object ​
Service holds extra options for the coredns service deployed within the virtual cluster
service
required object ​deployment
required object ​
Deployment holds extra options for the coredns deployment deployed within the virtual cluster
deployment
required object ​image
required string ​
Image is the coredns image to use
image
required string ​replicas
required integer 1 ​
Replicas is the amount of coredns pods to run.
replicas
required integer 1 ​nodeSelector
required object {} ​
NodeSelector is the node selector to use for coredns.
nodeSelector
required object {} ​affinity
required object {} ​
Affinity is the affinity to apply to the pod.
affinity
required object {} ​tolerations
required object[] [] ​
Tolerations are the tolerations to apply to the pod.
tolerations
required object[] [] ​resources
required object ​
Resources are the desired resources for coredns.
resources
required object ​pods
required object ​
Pods is additional metadata for the coredns pods.
pods
required object ​annotations
required object {} ​
Annotations are extra annotations for this resource.
annotations
required object {} ​labels
required object {} ​
Labels are extra labels for this resource.
labels
required object {} ​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.
topologySpreadConstraints
required object[] [map[labelSelector:map[matchLabels:map[k8s-app:vcluster-kube-dns]] maxSkew:1 topologyKey:kubernetes.io/hostname whenUnsatisfiable:DoNotSchedule]] ​overwriteConfig
required string ​
OverwriteConfig can be used to overwrite the coredns config
overwriteConfig
required string ​overwriteManifests
required string ​
OverwriteManifests can be used to overwrite the coredns manifests used to deploy coredns
overwriteManifests
required string ​priorityClassName
required string ​
PriorityClassName specifies the priority class name for the CoreDNS pods.
priorityClassName
required string ​