Cross-vCluster DNS

This vCluster.Pro feature allows you to add custom DNS rules to the vCluster to allow communication across services in separate vClusters as well as services deployed in the host cluster.

Records, Modes and Targets

The spec for this is basically divided into 3 parts – Records, Modes and Targets.

1. Record: A record is a section that is supposed to match a lookup for a DNS query. It can be of three types:
   • fqdn - is basically any 'fully qualified domain name' and will be mapped to a target of your choice
   • service – it is basically a mocked name of type service_name/namespace. Any DNS query of the form <service_name>.<namespace> will be mapped to the one in the target
   • namespace - this allows mapping services in an entire namespace into a namespace inside vcluster.
2. Target: A target is a specification about what should be returned as a response to a matched record and the mode filed. This basically also currently has the following 4 options:
   • mode – specifies where to find the target, is explained in detail in next section.
   • vcluster - specifies that the target service is to be found in this vcluster. Only used when the mode is vcluster
   • service - specifies target service itself. Needs to be in the namespace/name format.
   • namespace - specifies that target namespace itself. Only used in case where target.namespace is set. This is for namespace-to-namespace mapping.
3. Mode: A mode is a specificaition in which a record and target combination should work in. Currently we support the following 4 modes:
   • url – This specifies that the record - target combination are basically just 2 FQDN mapping one to another (more details in the examples below)
   • host - This specifies that the DNS queries matching from the record field should be mapped to the target in the 'host' cluster.
   • vcluster - This specifies that the DNS queries matching from record are to be mapped according to the target spec inside the given vcluster.
   • self - This specifies that the matching DNS queries are to be mapped to another service in that same vcluster itself

Spec

Below is the specification of how the above-explained fields are to be specified and their expected values

coredns:
  integrated: true
  plugin:
    enabled: true
    config:
      - record:
          fqdn: <FQDN>
          service: <service_namespace/service_name>
          namespace: <namespace>
        target:
          mode: url | host | vcluster | self
          vcluster: <vcluster_namespace/vcluster_name>
          url: <url>
          service: <service_namespace/service_name>
          namespace: <namespace>

Examples

Below are a few examples showcaseing some possible combinations of the above explained fields and sections

Mapping an FQDN

Consider the following example config

coredns:
  integrated: true
  plugin:
    enabled: true
    config:
      - record:
          fqdn: wikipedia.org
        target:
          mode: url
          url: en.wikipedia.org

This is purely a url mode based mapping – mapping one fqdn inside the vcluster to another fqdn. Hence dns lookups of wikipedia.com would return a DNS response with answer as en.wikipedia.org.

Mapping service to host cluster service

Mapping a service inside vcluster to service on host cluster

coredns:
  integrated: true
  plugin:
    enabled: true
    config:
      - record:
          service: my-namespace/my-svc
        target:
          mode: host
          service: dns-test/nginx-svc

As specified by mode: host, this config maps my-namespace/my-svc inside vcluster to dns-test/nginx-svc service in the host cluster. In this case the DNS response would be the service IP of the nginx-svc in dns-test namespace of the host cluster.

Mapping services across vcluster

Mapping a service inside vcluster to another service in a separate vcluster

coredns:
  integrated: true
  plugin:
    enabled: true
    config:
      - record:
          service: my-ns-in-vcluster/my-svc-vcluster
        target:
          mode: vcluster
          vcluster: test-vcluster-ns/test-vcluster
          service: dns-test-in-vcluster-ns/test-in-vcluster-service

In this case, as specified with mode: vcluster – the target service is in another vcluster. Here the service my-ns-in-vcluster/my-svc-vcluster is mapped to dns-test-in-vcluster-ns/test-in-vcluster-service in a vcluster named test-vcluster deployed in namespace test-vcluster-ns.

Mapping with service aliasing

Mapping a service in the same vcluster but under a different alias

coredns:
  integrated: true
  plugin:
    enabled: true
    config:
      - record:
          service: my-self-vc-ns/my-self-vc-svc
        target:
          mode: self
          service: dns-test/nginx-svc

In this case the service my-self-vc-ns/my-self-vc-svc is mapped to dns-test/nginx-svc from the same vcluster itself.

Mapping whole namespaces

Mapping all services under a particular namespace under another namespace in vcluster

coredns:
  integrated: true
  plugin:
    enabled: true
    config:
      - record:
          namespace: external-vc-ns
        target:
          mode: vcluster
          vcluster: test-vcluster-ns/test-vcluster
          namespace: test-in-vcluster-ns

Here, all services in the target namespace test-in-vcluster-ns of the vcluster test-vcluster are mapped inside a namespace external-vc-ns. One can visualize it as:

    ┌──────────────────────┐┌──────────────────────────────┐
    │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      │
    │...                   ││...                           │
    └──────────────────────┘└──────────────────────────────┘

The same is possible under the mode: host as well.