NodePort — exposing a Service on every node

A NodePort Service exposes a port on every node. The external client directs traffic to <node-ip>:<node-port>; the kube-proxy on the node DNATs to the Service ClusterIP, which is DNATed to a Pod. The NodePort is the simplest way to expose a Service externally; the trade-off is no HA and no TLS. This lesson walks the mechanism, the failure modes, and the operational discipline.

The NodePort manifest

apiVersion: v1
kind: Service
metadata:
  name: billing
spec:
  type: NodePort
  selector:
    app: billing
  ports:
    - name: http
      port: 80
      targetPort: 8080
      nodePort: 30080
      protocol: TCP

The nodePort field is the port on every node. The range is 30000-32767 by default. The operator can configure the range with the kube-apiserver’s --service-node-port-range flag.

The traffic flow

The traffic flow:

sequenceDiagram
    autonumber
    participant EC as External client
    participant N as Node IP:30080
    participant KP as kube-proxy
    participant P as Pod
    EC->>N: TCP <node-ip>:30080
    N->>KP: kube-proxy DNAT to ClusterIP:80
    KP->>P: DNAT to Pod IP:8080
    P->>P: handle request
    P->>KP: response
    KP->>N: response
    N->>EC: response

The kube-proxy on the receiving node intercepts traffic to the NodePort and DNATs to the Service ClusterIP. The ClusterIP is then DNATed to a Pod IP via the standard Service path.

The port range

The NodePort range is configurable:

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
networking:
  serviceSubnet: 10.96.0.0/16
  nodePortRange: 30000-32767

The default is 30000-32767 (276 ports). The cluster operator can change the range at init time. Changing the range after the cluster is created requires a control-plane restart.

The kubelet’s role

The kubelet does not directly program the NodePort. The kube-proxy reads the Service and programs the iptables or IPVS rules. The NodePort is just a port on the node’s interface that the kube-proxy listens on.

The cluster operator can verify:

# The NodePort is listening
ss -tlnp | grep 30080

# The iptables rules
iptables-save | grep 30080

The output shows the NodePort is listening on the node’s interface and the kube-proxy has programmed the rules.

The use cases

The NodePort’s use cases:

• Development and testing: the simplest way to expose a Service externally.
• On-premises clusters without a load balancer: a bare-metal cluster can use NodePort with a round-robin DNS or a hardware load balancer.
• Ingress controller backend: many Ingress controllers use NodePort as the backend Service.
• Temporary external access: an operator needs to expose a Service for a one-off task.

The NodePort is not the production choice for external HTTP traffic. The production choice is Ingress (for HTTP) or LoadBalancer (for non-HTTP).

The failure modes

The NodePort’s failure modes:

• Node failure: the traffic is lost when the node fails. The external client must connect to a different node.
• Port conflict: the NodePort is in the range 30000-32767. The cluster operator must ensure the ports do not conflict.
• No TLS: the NodePort is unencrypted. The external traffic is in plaintext.
• No HA: the external client must know the node IPs. A round-robin DNS or a hardware load balancer is required.
• Firewall blocking: the NodePort is on the node’s interface. The firewall must allow the port.

The operational discipline

The NodePort’s operational discipline:

• Use NodePort for development only. The production choice is Ingress or LoadBalancer.
• Audit the NodePort usage. The cluster operator must enumerate every NodePort Service.
• Coordinate with the firewall. The NodePort must be allowed by the firewall.
• Use a hardware load balancer or round-robin DNS for HA. The external client must be able to reach every node.
• Document the NodePort choice. The cluster operator must understand which Services are NodePort.
• Test the NodePort at every release. The NodePort is a security-relevant change.

Quiz

Production discipline

• Use NodePort for development only. The production choice is Ingress or LoadBalancer.
• The NodePort range is 30000-32767 by default. The range is fixed at cluster init; plan for the maximum number of NodePort Services.
• Audit the NodePort usage. The cluster operator must enumerate every NodePort Service.
• Coordinate with the firewall. The NodePort must be allowed by the firewall.
• Use a hardware load balancer or round-robin DNS for HA. The HA is the client’s responsibility.
• Document the NodePort choice. The cluster operator must understand which Services are NodePort.
• Test the NodePort at every release. The NodePort is a security-relevant change.
• Migrate to Ingress or LoadBalancer. The NodePort is the development pattern; the production pattern is Ingress or LoadBalancer.