DNS

    In this mode, all name lookups are handled locally by the data plane proxy. This approach allows for more robust handling of name resolution.

    On Kubernetes, this is the default. You must enable it manually on universal deployments.

    In Universal mode, the and kuma-dp processes enable DNS resolution to .mesh addresses.

    Prerequisites:

    • kuma-dp, envoy, and coredns must run on the worker node — that is, the node that runs your service mesh workload.
    • core-dns must be in the PATH so that kuma-dp can access it.
      • You can also set the location with the --dns-coredns-path flag.
    • User created to run the kuma-dp process. You must run the kuma-dp process with a different user than the user you test with. Otherwise, name resolution might not work.

    1. Specify the flags --skip-resolv-conf and --redirect-dns in the transparent proxy iptables rules:

    2. Start 

      1. kuma-dp run \
      2.   --cp-address=https://127.0.0.1:5678 \
      3.   --dataplane-file=dp.yaml \
      4.   --dataplane-token-file=/tmp/kuma-dp-redis-1-token

      The kuma-dp process also starts CoreDNS and allows resolution of .mesh addresses.

    This mode implements advanced networking techniques, so take special care for the following cases:

    • The mode can safely be used with the .
    • In mixed IPv4 and IPv6 environments, it’s recommended that you specify an IPv6 virtual IP CIDR.

    When you install the control plane, set the following environment variable to disable the data plane proxy DNS:

    KUMA_RUNTIME_KUBERNETES_INJECTOR_BUILTIN_DNS_ENABLED=false

    Pass the environment variable to the --env-var argument when you install:

    1. kumactl install control-plane \
    2.   --env-var KUMA_RUNTIME_KUBERNETES_INJECTOR_BUILTIN_DNS_ENABLED=false

    Set the environment variable:

    1. Configure the transparent proxy iptables rules:

      1. kumactl install transparent-proxy \
      2.           --kuma-dp-user kuma-dp \

    2. Start with flag --dns-enabled set to false:

      1. kuma-dp run \
      2.   --cp-address=https://127.0.0.1:5678 \
      3.   --dataplane-file=dp.yaml \
      4.   --dataplane-token-file=/tmp/<KUMA_DP_REDIS_1_TOKEN> \
      5.   --dns-enabled=false

    You can configure Kuma DNS with the config file, or with environment variables:

    The domain field specifies the default .mesh DNS zone that Kuma DNS provides resolution for. If you change this value, make sure to change the zone value for kumactl install dns to match. These values must be the same for kube-dns or CoreDNS server to redirect relevant DNS requests.

    The CIDR field sets the IP range of virtual IPs. The default 240.0.0.0/4 is reserved for future IPv4 use IPv4 and is guaranteed to be non-routable. We strongly recommend to not change this value unless you have a specific need for a different IP range.

    Kuma DNS includes these components:

    • The DNS server
    • The VIPs allocator
    • Cross-replica persistence

    The DNS server listens on port 5653, responds to type A and AAAA DNS requests, and answers with A or AAAAA records, for example <service>.mesh. 60 IN A 240.0.0.100 or <service>.mesh. 60 IN AAAAA fd00:fd00::100. The default TTL is 60 seconds, to ensure the client synchronizes with Kuma DNS and to account for any intervening changes.

    The virtual IPs are allocated from the configured CIDR, by constantly scanning the services available in all Kuma meshes. When a service is removed, its VIP is also freed, and Kuma DNS does not respond for it with A DNS record.

    Kuma DNS is not a service discovery mechanism. Instead, it returns a single VIP that is assigned to the relevant service in the mesh. This makes for a unified view of all services within a single zone or across multiple zones.

    Consuming a service handled by Kuma DNS from inside a Kubernetes container is based on the automatically generated kuma.io/service tag. The resulting domain name has the format {service tag}.mesh. For example:

    1. <kuma-enabled-pod>curl http://echo-server_echo-example_svc_1010.mesh:80
    2. <kuma-enabled-pod>curl http://echo-server_echo-example_svc_1010.mesh

    A DNS standards compliant name is also available, where the underscores in the service name are replaced with dots. For example:

    1. <kuma-enabled-pod>curl http://echo-server.echo-example.svc.1010.mesh:80
    2. <kuma-enabled-pod>curl http://echo-server.echo-example.svc.1010.mesh

    The default listeners created on the VIP default to port , so the port can be omitted with a standard HTTP client.