Skip to main content
Version: 1.2.0

Configure Local DNS

When you set up a Kubernetes cluster locally with services that use multiple subdomains (e.g., *.civitas.test), you need a way for your local machine to resolve those subdomains to your cluster. There are two main options for configuring this:

  1. Modifying the hosts file: This is a quick but less flexible option. You manually add each subdomain (e.g., api.civitas.test, grafana.civitas.test) to your system's hosts file (see the list below), pointing them to your Minikube IP. This is simpler but requires manual updates for each subdomain.

  2. Using a DNS server: This option is scalable and dynamic, useful if you regularly work with multiple subdomains. You can use Acrylic DNS on Windows or Dnsmasq on Linux/macOS to automatically resolve any subdomain of civitas.test to your Minikube cluster.

Option 1: Modify Hosts File (Simple and Manual)​

This method involves manually adding each required domain to your system’s hosts file. It’s a simple solution, but if you frequently add or change subdomains, it can become tedious to maintain.

Steps:​

  1. Open the Hosts File:

    • Windows: Open the file located at C:\Windows\System32\drivers\etc\hosts with administrative privileges.
    • Linux/macOS: Open the file located at /etc/hosts with root privileges in your preferred editor.

  2. Add Entries: Add each required domain, pointing them to your cluster (usually 127.0.0.1 e.g. if using minikube tunnel):

    127.0.0.1 civitas.test
    127.0.0.1 alertmanager.civitas.test
    127.0.0.1 api-dashboard.civitas.test
    127.0.0.1 api.civitas.test
    127.0.0.1 api-admin.civitas.test
    127.0.0.1 apim.civitas.test
    127.0.0.1 geoportal.civitas.test
    127.0.0.1 geoserver.civitas.test
    127.0.0.1 grafana.civitas.test
    127.0.0.1 idm.civitas.test
    127.0.0.1 mimir.civitas.test
    127.0.0.1 minio-tenant-console.civitas.test
    127.0.0.1 minio-tenant.civitas.test
    127.0.0.1 monitoring.civitas.test
    127.0.0.1 mqtt.civitas.test
    127.0.0.1 oauth.civitas.test
    127.0.0.1 oauth.geoportal.civitas.test
    127.0.0.1 pgadmin.civitas.test
    127.0.0.1 superset.civitas.test

  3. Save and Close the File.

For more dynamic setups, setting up a local DNS server like Acrylic DNS on Windows or Dnsmasq on Linux/macOS is a better solution. In this way, any subdomain under civitas.test will be automatically resolved without needing to update your hosts file manually.

Windows: Install Acrylic DNS​

  1. Install Acrylic DNS Proxy: Download and install Acrylic DNS using a package manager like winget:

    winget install AcrylicDNS

  2. Configure Acrylic: Open Acrylic's user interface and edit the AcrylicHosts.txt file through the menu. Add the following entry to enable wildcard domain routing for *.civitas.test:

    127.0.0.1 *.$DOMAIN $DOMAIN
    • Replace $DOMAIN with civitas.test. If using Minikube tunnel, leave the IP as 127.0.0.1.
    • If you're not using Minikube tunnel, replace 127.0.0.1 with your actual cluster IP.

  3. Restart Acrylic: After saving the configuration, restart the Acrylic service to apply the changes.

  4. Update Windows DNS Settings: Ensure that the Windows DNS settings of your network adapters point to the local Acrylic DNS service.

Linux/macOS: Install and Configure Dnsmasq​

  1. Install Dnsmasq:

    Linux (e.g. Ubuntu, Debian):

    sudo apt install dnsmasq

    macOS:

    brew install dnsmasq

  2. Configure Dnsmasq:

    Edit the Dnsmasq configuration file (/etc/dnsmasq.conf on Linux or /opt/homebrew/etc/dnsmasq.conf on macOS). Add the following line to route any subdomain under .civitas.test to 127.0.0.1:

    address=/civitas.test/127.0.0.1
    • Replace civitas.test with your cluster domain.
    • If you're using Minikube tunnel, leave 127.0.0.1 as it is. If you're not using Minikube tunnel, replace 127.0.0.1 with your cluster IP.

  3. Restart Dnsmasq:

    On Linux:

    sudo systemctl restart dnsmasq

    On macOS:

    brew services start dnsmasq

  4. Update DNS Settings:

    On Linux: Edit /etc/resolv.conf to point to your local Dnsmasq server.

    nameserver 127.0.0.1

    On macOS: Create a resolver file at /etc/resolver/civitas.test with the following content:

    nameserver 127.0.0.1