Shrink your Kubernetes init containers: swap curl for netcat

We run a wait-probe init container in our Kubernetes deployments to gate service startup on Postgres and NATS being ready. It was present in two deployments — the API and the operator — each with two init containers (one for Postgres, one for NATS), so four instances in total per cluster.

The image was built on curlimages/curl. After switching to alpine:3.20 + netcat-openbsd and measuring both published versions:

Four instances × 16.7 MB saved = ~67 MB less to pull per node on a cold start. The netcat-openbsd package itself is about 80 KB — curlimages/curl carries TLS libraries, certificate bundles, and everything else curl needs to speak HTTP/S. None of that is useful for a TCP port check.

The original probe

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

initContainers:
  - name: wait-for-postgres
    image: curlimages/curl:latest
    command:
      - sh
      - -c
      - |
        until (curl --silent --connect-timeout 2 --max-time 3 \
          "http://postgres-host:5432" >/dev/null 2>&1; [ $? -ne 7 ]); do
          sleep 2
        done

This works. But every time I read it I have to stop and reconstruct the logic: curl to a raw TCP port, check if the exit code is not 7 (connection refused), loop until it isn’t. It’s exit-code archaeology.

What exit code 7 means (and why you shouldn’t have to know)

curl exit code 7 is CURLE_COULDNT_CONNECT — the host refused the connection. So the idiom above is: “keep looping while the port is refusing connections; stop when anything else happens.” That anything else includes curl successfully connecting, timing out, or hitting a different error. In practice it works for TCP readiness checks, but it’s a roundabout way to say “is this port open.”

netcat does exactly one thing here

nc -z opens a TCP connection to a host and port, exits 0 on success, non-zero on failure. That’s the whole API. The probe becomes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

initContainers:
  - name: wait-for-postgres
    image: ghcr.io/glassflow/wait-probe:latest
    command:
      - sh
      - -c
      - |
        until nc -z postgres-host 5432; do
          sleep 2
        done

The intent is in the flag name. -z = zero I/O mode = just check if the port is open. No exit code lookup required. The same pattern works identically for NATS:

1

until nc -z nats-host 4222; do sleep 2; done

The Dockerfile

1
2
3

FROM alpine:3.20
RUN apk add --no-cache netcat-openbsd
USER 100

The USER 100 matters for Kubernetes: without a numeric UID, runAsNonRoot: true fails because the kubelet can’t verify a string username like curl_user is non-root. A numeric UID it can check directly. This also plays nicely with OpenShift’s restricted-v2 SCC — no runAsUser in the pod spec means OpenShift injects a UID from the namespace range without conflict.

When this matters more than you’d think

Init containers run on every pod restart. A leaner image:

• Pulls faster on a cold node
• Evicts less useful layers from the node’s image cache
• Gives the security scanner less surface area to flag

None of this is a crisis at small scale. But it’s also a five-minute change with no downside, and the probe is easier to read afterwards.

The image is published at ghcr.io/glassflow/wait-probe if you want to use it directly. Source and Dockerfile are on GitHub.