Configure /etc/hosts Entries in CoreDNS for Cloud Connector

Configure custom /etc/hosts entries to be propagated into the CoreDNS NodeHosts ConfigMap in the Cloud Connector (K3s-based and K3d-based). This ensures that hostnames defined on the host machine /etc/hosts files are resolvable from within pods running in the K3s cluster.

Note: For new installations, this configuration is applied automatically during the installation process.

Before configuring the existing cloud connectors after upgrade, ensure you have:

  • SSH access to the host machine running Cloud Connector
  • Necessary access permissions
  • kubectl access configured to the K3s cluster
  • Understanding of /etc/hosts file format and structure
  • Custom hostname entries already configured in the host machine's /etc/hosts file
  • Network connectivity between host machine and K3s cluster.
Important: Custom host entries added to /etc/hosts must be non-localhost entries (not 127.0.0.1). Localhost-related entries are automatically filtered out during the propagation process.
  1. Verify current /etc/hosts entries on the host machine.
    1. SSH to the host machine running Cloud Connector.
    2. View the current /etc/hosts file to identify custom host entries: 
      cat /etc/hosts
      Note: All non-localhost entries that should be propagated to CoreDNS:
      192.168.1.10   internal-server.example.com   internal-server
192.168.1.20   app-database.example.com     app-database
10.0.0.5       monitoring.example.com      monitoring
    3. Localhost entries (127.0.0.1, ::1) will be automatically filtered and not propagated to CoreDNS.
  2. Execute the host entries propagation script.
    1. Run the AppViewX utility command to update CoreDNS with /etc/hosts entries: 
      ./avxctl update-hosts
    2. The script performs the following actions:
      • Reads all entries from the host machine's /etc/hosts file
      • Filters out localhost-related entries (127.0.0.1, ::1)
      • Retrieves the current CoreDNS ConfigMap from kube-system namespace
      • Updates the ConfigMap's NodeHosts data field with filtered entries
      • Applies the updated ConfigMap via kubectl
      • Triggers a CoreDNS rollout restart to apply changes
    3. Wait for the command to complete. Total execution time is typically 30-60 seconds.
  3. Verify the CoreDNS ConfigMap update.
    1. Check the CoreDNS ConfigMap to verify host entries were added: 
      ./k3s kubectl coredns -n kube-system -o yaml | grep -A 20 NodeHosts
    2. Verify output contains your custom host entries: 
      NodeHosts: |
  192.168.1.100 internal-api.appviewx.local api
  10.50.0.25 backup-server.appviewx.local backup
  172.16.5.8 metrics-db.appviewx.local metrics
  4. Monitor CoreDNS pod rollout restart.
    1. Watch the CoreDNS pods restart with the new configuration: 
      kubectl rollout status deployment/coredns -n kube-system --timeout=2m
    2. Verify all CoreDNS pods return to Running status.
    3. The rollout typically completes within 30-60 seconds.
  5. Test hostname resolution from within a pod.
    1. Create a test pod to verify DNS resolution: 
      kubectl run -it --rm debug --image=busybox:1.28 --restart=Never -- sh
    2. From within the test pod, test resolution of one of your custom hostnames: 
      nslookup internal-api.appviewx.local
    3. Expected output shows the configured IP address resolving correctly: 
      Name:      internal-api.appviewx.local
Address:   192.168.1.100
    4. Exit the test pod shell.
  6. Configure automatic host entry propagation on system boot.
    1. The Cloud Connector automatically configures a cron job to update host entries on system reboot.
    2. Verify the cron job is configured: 
      crontab -l
    3. The cron job runs the update-hosts command at system boot time (@reboot) to automatically propagate host entries.
    4. This ensures host entries are restored and available in CoreDNS even after host system reboots.
  7. Handle issues and troubleshooting.
    1. If host entries are not resolving, verify the following:
      • Check CoreDNS pod logs for errors: 
        kubectl logs -n kube-system -l k8s-app=kube-dns --tail=50
      • Verify entries were correctly added to ConfigMap: 
        kubectl get configmap coredns -n kube-system -o yaml
      • Confirm hostname format matches /etc/hosts on host: 
        cat /etc/hosts | grep -v "^#" | grep -v "^$"
      • Verify DNS resolution is using CoreDNS: 
        kubectl get svc -n kube-system kube-dns
    2. If CoreDNS pods fail to restart, check pod events: 
      kubectl describe pod -n kube-system -l k8s-app=kube-dns
    3. If script execution fails, verify kubectl access and permissions: 
      kubectl auth can-i patch configmaps -n kube-system

Configuring hostAliases Entries for the Platform Pod

  1. Log in to the Helm Cloud Connector bastion host.
  2. Edit the Platform deployment by executing the following command: 
    kubectl edit deploy avx-mid-server-platform -n <namespace>
  3. Add the hostAliases section under the pod specification. Ensure that hostAliases is aligned at the same indentation level as containers, as shown below: 
    spec:
  hostAliases:
  - hostnames:
    - external.service.local
    ip: 192.168.5.6
  containers:
  4. Save and exit the deployment file.
  5. Verify that the entry was added successfully. List the Platform pods: 
    kubectl get pods -n <namespace>
  6. Log in to any Platform pod whose name starts with avx-mid-server-platform: 
    kubectl exec -it <platform-pod-name> -n <namespace> -- bash

    Replace <platform-pod-name> with the actual Platform pod name.

  7. Inside the pod, verify the /etc/hosts entries: 
    cat /etc/hosts
  8. Confirm that the /etc/hosts file contains the entry added through hostAliases.