iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
“Networking inside Docker” in a Kubernetes lesson can mean two nested systems. Docker networking connects containers to one another and to your host machine. Kubernetes networking gives Pods their own IP addresses and uses Services to reach them. When a local cluster is built with Docker, the Kubernetes nodes are themselves Docker containers, so both layers apply to the same traffic. To fix a connection problem, first decide which kind of destination you are trying to reach, then follow the one path that applies to it.
Two networks with one name
Docker manages a set of virtual networks on each Docker host. A container attaches to one of them, receives an address on it, and can reach other containers on the same network. Docker’s network drivers, including the bridge driver and host networking, decide how that container is connected to the rest of the machine.
Kubernetes sits on top of this in a local setup. A tool such as kind runs each Kubernetes node as a Docker container. Inside each node, Kubernetes assigns every Pod a cluster-private IP address, and Services provide stable names and addresses that route to Pods. Kubernetes does not require you to create Docker links between Pods, and it does not require host-port mappings for ordinary Pod-to-Pod traffic.
The practical consequence is that the same request can cross several boundaries: from your host into a Docker port mapping, into a node container, and then into a Pod through a Service. Each boundary has its own rules, so the first troubleshooting step is to identify the destination.
#1 Best Overall
Identify the destination first
Each destination lives in a different network context. The table below shows which path applies to each.
| Destination | Network context | How a host normally reaches it | What to check |
|---|---|---|---|
| Plain Docker container on a bridge network | Its own IP on a Docker bridge | A published port with -p, or direct use of the container IP on Linux |
The -p mapping and its host IP binding |
| Process running directly on the host | Host network stack | Not applicable; it is already on the host | The service’s own listen address |
| kind node (a Docker container acting as a Kubernetes node) | Docker bridge, with Kubernetes running inside | On Linux, the node IP is often reachable directly; with Docker Desktop or a remote Docker host, use extraPortMappings |
The kind cluster configuration |
| Pod | Cluster-private Pod IP inside the cluster | Not directly from the host as a normal access pattern | Use a Service, or a port-forward for debugging |
| Service | Stable virtual address that routes to Pods | A NodePort, or a port-forward for testing | The Service type, port, targetPort, and nodePort |
Docker bridge networks
A bridge network is a software network that connects containers on one Docker host. Containers attached to the same bridge can communicate with each other. Docker isolates containers on other bridges and on external hosts by default, so a container is not reachable from the outside unless you publish a port or attach it to a network that allows the traffic.
Docker provides two kinds of bridge that behave differently for name lookup:
The default bridge
On the default bridge, containers usually need to use IP addresses to reach each other. Name-based access between containers is not the normal pattern here, so if you rely on container names, a user-defined bridge is the better choice.
Rank #2
A user-defined bridge
A user-defined bridge gives attached containers automatic DNS lookup by container name. You create it and attach containers to it like this:
docker network create app-net
docker run -d --name api --network app-net nginx
docker run --rm --network app-net curlimages/curl http://apiThe second container reaches the first by the name api. Containers on different user-defined bridges cannot reach each other this way unless you connect them to a shared network.
Publishing a port from host to container
Publishing a port creates a path from the host into a container. In -p 8080:80, host port 8080 forwards to container port 80. The container still lives on its bridge network; only the published port is opened on the host.
docker run -d --name web -p 8080:80 nginx
curl http://localhost:8080Choosing the host address
If you omit a host IP, Docker publishes the port on all of the host’s addresses. Docker’s port-publishing documentation warns that a port published this way is reachable from outside the machine by default. To limit access to the local machine, bind the port to loopback:
Rank #3
docker run -d --name web -p 127.0.0.1:8080:80 nginxDocker’s documentation also notes a localhost exposure caveat for releases before 28.0.0 when hosts share the same Layer 2 network segment. If your Docker version is older than 28.0.0, check its release notes before assuming loopback binding fully isolates the port.
Host networking
The host network driver removes the separate network boundary for a container. The container shares the host’s network stack, so it has no separate container IP address. Docker ignores port-publishing flags such as -p in this mode, because the container already listens on the host’s ports. Use this mode when a container should bind directly to host interfaces, and avoid it when you need isolation between the container and host ports.
kind: a Docker layer around Kubernetes
kind, the Kubernetes-in-Docker tool, runs Kubernetes nodes as Docker containers. Because of that, a port your application exposes inside the cluster must pass through two steps before it reaches your host: the Kubernetes Service port inside the node, and the Docker mapping from the node container to the host.
Forwarding a port with extraPortMappings
The kind configuration key extraPortMappings forwards a port from a node container to the host. The following example maps host port 8080 to node port 30080 for a NodePort Service:
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
extraPortMappings:
- containerPort: 30080
hostPort: 8080Create the cluster with this file using kind create cluster --config kind-config.yaml. Then define a Service of type NodePort whose nodePort matches the containerPort from the mapping:
apiVersion: v1
kind: Service
metadata:
name: web
spec:
type: NodePort
selector:
app: web
ports:
- port: 80
targetPort: 80
nodePort: 30080The kind node’s containerPort and the Service’s nodePort must be the same number. If they differ, the request reaches the node container on a port that no Service is listening on.
When the node IP is reachable directly
On native Linux without Docker Desktop, the host can generally reach a kind node’s IP address directly, so a mapping may not be needed for that case. Docker Desktop and remote Docker hosts do not offer that direct route, so use extraPortMappings there.
Docker Desktop changes the host path
On Docker Desktop, containers run inside a Linux virtual machine rather than directly on your operating system. Docker Desktop’s backend receives connections to published ports on the host and forwards them into that VM. This is why a port mapping on Docker Desktop is the normal route into a container or kind node, and why the Linux-only shortcut above does not apply.
Best Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
To reach a service running on the host from inside a container, use the name host.docker.internal. Docker Desktop provides it so containers can call host services without knowing the host’s IP address.
How a Service reaches a Pod
Inside the cluster, a Service is the stable access point for a set of Pods. Traffic sent to the Service’s address is routed to one of the Pods that match its selector. Pod IPs can change when Pods are recreated, which is why applications should use the Service name rather than a Pod address.
When you troubleshoot a Pod-to-Pod or Service-to-Pod path, use Kubernetes networking concepts such as Services, selectors, and ports. Solving that connection with Docker container links or host-port mappings is the wrong layer.
A troubleshooting sequence
- Name the destination: host service, Docker container, kind node, Pod, or Service.
- For two ordinary containers, confirm both are attached to the same user-defined bridge, and use the container name as the hostname.
- For host-to-container access, run
docker psand check thePORTScolumn. Confirm the host port, the container port, and the host IP binding such as127.0.0.1. - If you use Docker Desktop, confirm the mapping is published there, because connections are forwarded into the Linux VM.
- For a kind cluster, check
extraPortMappingsin the cluster configuration. - For NodePort access, confirm the node’s mapped
containerPortequals the Service’snodePort. - For Pod or Service traffic, use
kubectl get svcandkubectl get endpointsto confirm the Service has backing Pods, then test from a Pod inside the cluster.
The steps above follow the order of network boundaries a request crosses. If a connection fails at step 3 for a container, the problem is in the Docker mapping, not in Kubernetes.
Common mistakes
- Publishing a container port without a host IP and then assuming the port is private to the machine.
- Using container names on the default bridge, where automatic name lookup is not available.
- Expecting
-pto work with host networking, where Docker ignores it. - Setting a kind NodePort mapping whose
containerPortdoes not match the Service’snodePort. - Calling a Pod IP directly from the host, instead of going through a Service.
Once the destination and path are identified, the rest of the troubleshooting usually comes down to a single mismatched port or binding address.
Quick Recap
The Bottom Line
“”
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
