Table of Contents
So you are selected

Troubleshooting Remote Elastic Agent Enrollment in Docker Compose: Common Pitfalls and Solutions

Resolve remote Elastic Agent enrollment issues in Docker. From DNS fixes to port mapping and TLS tips—get your Fleet Server running in no time.

Introduction

If you’ve followed the Elastic Docker Compose tutorial series to set up the Elastic Stack, enrolling remote Elastic Agents might have led to unexpected challenges. Let’s explore a common enrollment failure—DNS resolution errors—and actionable solutions to resolve them. Elastic is known for its flexibility and scalability, but certain configurations, especially around networking and security, can introduce roadblocks if not addressed early.

The Core Issue: DNS and Configuration Conflicts

A user encountered the following error during remote agent enrollment:

lookup fleet-server on 127.0.0.53:53: server misbehaving

This indicates the host couldn’t resolve the fleet-server hostname. Below, we’ll dissect this issue using configuration examples and propose fixes. Misconfigured DNS settings can cause unnecessary delays in Elastic Agent enrollment and system observability, especially across multiple environments.

Key Configuration Insights

  1. Fleet Server Host Configuration
     The Fleet Server host is configured with the URL https://fleet-server:8220. While valid within the Docker network, external hosts cannot resolve fleet-server without explicit DNS mapping.

  2. Elasticsearch Output Configuration
     The Elasticsearch output points to https://es01:9200. Similar to fleet-server, es01 is a Docker service name and won’t resolve externally.

  3. APM Integration Settings
     The APM configuration includes serverUrl: "https://fleet-server:8200". Note the port 8200 instead of 8220—a common typo. Consistency across configurations is critical. Even small misalignments like this can break observability pipelines across environments.

Step-by-Step Fixes

  1. Resolve DNS for Remote Hosts
     Update /etc/hosts on the remote host:

# Replace [DOCKER_HOST_IP] with your Docker host's IP

[DOCKER_HOST_IP]  fleet-server  es01

‍

Verify connectivity:

ping fleet-server  # Should resolve to Docker host IP  

nc -zv fleet-server 8220  # Check port accessibility  

‍

  1. Validate Port Exposure in Docker Compose
     Ensure ports for fleet-server and es01 are exposed:

services:

  fleet-server:

    ports:

      - "8220:8220"  # Expose Fleet Server port

  es01:

    ports:

      - "9200:9200"  # Expose Elasticsearch port

‍

  1. Correct APM Configuration
     Update the APM serverUrl to use port 8220:

serverUrl: "https://fleet-server:8220"

‍

  1. Handle Self-Signed Certificates
     For testing, bypass certificate validation with --insecure:

sudo ./elastic-agent install --url=https://fleet-server:8220 --enrollment-token=TOKEN --insecure

Why This Isn’t Production-Ready

The Docker Compose tutorial focuses on local development. For production:

  • Avoid hardcoded Docker DNS names: Use domain names or internal DNS.

  • Replace self-signed certificates: Deploy trusted certificates (e.g., Let’s Encrypt).

  • Secure ports: Restrict access to ports 8220/9200 via firewalls or VPNs.
    Proper production hardening is crucial when managing observability and security at scale.

Production Checklist

  • DNS: Use a dedicated DNS server or map entries on remote hosts.

  • Networking: Ensure ports 8220 (Fleet Server) and 9200 (Elasticsearch) are securely accessible.

  • Certificates: Use trusted SSL certificates for fleet-server and es01.

  • Policies: Start with minimal integrations (e.g., System metrics) to reduce complexity.
    Having a checklist before rolling out to production reduces troubleshooting overhead and ensures deployment quality.

Community Feedback

Discussions highlight requests for advanced tutorials covering:

  • TLS security for Fleet Server and Elasticsearch.

  • Scaling Fleet Server with load balancers.

  • Kubernetes integration for dynamic environments.
    Community voices continuously shape the Elastic ecosystem, pushing for enhancements, better defaults, and broader support across cloud-native stacks.

Elastic: A Platform for Everything, Everyone, and Everywhere

Elastic isn’t just about search—it’s a complete observability and security platform built for modern infrastructure. Whether you're managing logs, metrics, traces, or securing your environment against threats, Elastic provides the building blocks for scalable, resilient, and intelligent operations.

For developers, it’s a lightning-fast search engine. For DevOps, it’s a full-stack monitoring solution. For security teams, it’s an advanced SIEM and threat detection platform. And with Elastic Cloud, deployment is simplified across AWS, Azure, and Google Cloud.

Whether you're running on Kubernetes, Docker, or traditional servers, Elastic integrates seamlessly across environments, offering a unified UI (Kibana) and powerful APIs.

Every team—from startups to global enterprises—can benefit from Elastic’s modular design, extensive documentation, and vibrant community.

Elastic's commitment to open code, extensibility, and integrations makes it a future-proof choice for teams of all sizes.

It's more than infrastructure monitoring—it's about actionable insights, proactive responses, and scalable solutions across business-critical environments.

Final Recommendations

Enrollment failures often stem from:

  • DNS misconfigurations: Fix with /etc/hosts or DNS servers.
  • Port accessibility: Verify Docker port exposure and firewall rules.
  • Certificate trust: Use --insecure for testing, trusted certs for production.

Pro Tip: Test connectivity with nc or curl before enrolling agents!
Bonus Tip: Use docker network inspect to debug service name resolution within containers.

Elastic continues to evolve as a comprehensive solution for enterprise search, application monitoring, and threat protection. Getting the setup right—starting from agent enrollment—lays the foundation for long-term success and scalability.

‍