8.10 Kubernetes Container Port Model

Kubernetes Container Port Model is the schema and semantics of a container's ports array, specifying containerPort, an optional name, protocol, and an optional hostPort, a structure that is largely documentary for basic Pod-to-Pod reachability but becomes functionally significant when named ports, host port binding, or non-default protocols are involved.

Why containerPort Declaration Is Mostly Informational

Network Reachability Without Declaration

Because all containers within a Pod share a single network namespace, a container listening on a given port is reachable by other containers in the same Pod, and by other Pods able to reach the Pod's IP, regardless of whether that port was declared in the ports array at all; declaring it is not what makes the port reachable.

What Declaration Actually Provides

Declaring a containerPort instead serves as documentation, visible through kubectl describe pod, and as the basis for named port references elsewhere in the Pod's own configuration and in dependent objects like Services, rather than functioning as a firewall rule or a listen-address configuration.

The name Field and Named Port References

Assigning a Symbolic Name to a Port

The optional name field gives a container port a symbolic identifier, such as http or metrics, which must be unique within the Pod, unlocking the ability for other parts of the configuration to reference the port by name rather than by its raw numeric value.

Consuming Named Ports in Probes and Services

A liveness or readiness probe can target a named port instead of a literal number, and a Service's targetPort can likewise reference a container's named port, meaning a single renumbering of the actual port value, changed once in the container spec, automatically propagates correctly to every probe and Service referencing it by name rather than requiring each reference to be updated individually.

Protocol Specification

Supported Protocol Values

The protocol field accepts TCP, the default if omitted, UDP, and SCTP, determining which transport-layer protocol the declared port corresponds to, relevant for named port resolution and for any downstream consumer, such as a Service, that needs to know which protocol to route for that port.

Matching Protocol to Application Behavior

A container running a UDP-based service, such as certain DNS or streaming protocols, must correctly declare protocol: UDP for any named port reference or Service configuration depending on that port to function correctly, since a mismatched protocol declaration would misconfigure downstream routing even if the port number itself is correct.

hostPort and Its Implications

Binding Directly to the Node's Network

Setting hostPort binds the container's port directly to the same port number on the node's own network interface, meaning traffic arriving at the node's IP on that port is forwarded into the Pod, a fundamentally different exposure mechanism than the Pod's own cluster-internal IP address that exists regardless of hostPort configuration.

Scheduling and Conflict Implications

Because a given hostPort value can only be bound by one Pod per node at a time, using hostPort effectively constrains scheduling, since the scheduler must place the Pod on a node where that specific host port is not already claimed by another Pod, and it inherently limits how many replicas of that Pod can run on a single node to at most one.

When hostPort Is Actually Needed

hostPort is primarily useful for workloads that genuinely need to be reachable on a specific, predictable port directly on a node's own IP, such as certain node-level agents or legacy integrations expecting a fixed host-level port, rather than for typical application workloads, which almost always rely on Service-based exposure instead.

Practical Guidance on Port Declaration

Declaring Ports Even When Not Strictly Required

Even though containerPort declaration is not required for basic reachability, consistently declaring it, along with a meaningful name, is good practice for manifest clarity and for enabling named port references in probes and Services, making the declaration a low-cost habit with clear downstream benefits despite not being strictly mandatory for connectivity itself.