4.1.2.4 Exposed Port Docs

Exposed port docs refer to the practice of clearly communicating, through the EXPOSE instruction and accompanying comments, exactly which ports a containerized application listens on and what purpose each one serves, since EXPOSE alone often does not convey enough context on its own.

What EXPOSE Communicates and What It Doesn't

EXPOSE documents that a container listens on a given port, but it says nothing about what that port is for, which can be ambiguous when an application uses multiple ports for different purposes.

EXPOSE 8080
EXPOSE 9090

Without further explanation, it is not obvious from this alone which port serves the main application and which, if any, serves a secondary purpose like metrics or health checks.

Adding Context Through Comments

A short comment alongside each EXPOSE instruction clarifies the purpose of each port, which is especially helpful for anyone configuring network policies, load balancers, or monitoring around the container.

EXPOSE 8080
# Prometheus metrics endpoint
EXPOSE 9090

Why This Matters for Operations

Operations teams configuring ingress rules, firewalls, or service meshes rely on knowing exactly what each exposed port does, since a port intended only for internal metrics scraping should typically be handled very differently from a port intended for public-facing traffic.

docker run -p 8080:8080 -p 127.0.0.1:9090:9090 myapp:1.0

Binding the metrics port only to localhost, while exposing the main application port more broadly, is a sensible configuration decision that depends on understanding each port's actual purpose.

Keeping Port Documentation in Sync With the Application

Because EXPOSE instructions are easy to forget to update when an application's port usage changes, periodically verifying that documented ports match what the application actually listens on prevents misleading or outdated documentation from persisting in the Dockerfile.

docker run --rm myapp:1.0 netstat -tlnp

Why Exposed Port Documentation Matters

Clear documentation of exposed ports and their purposes reduces misconfiguration risk during deployment, particularly the common mistake of exposing an internal-only port (like a metrics or debug endpoint) more broadly than intended simply because its purpose was not clearly communicated.