Pod lifecycle: is a non-normative note on the magnitude of the NetworkPolicy handling delay in scope?

Start with the Pod lifecycle section linked in the issue and review its existing NetworkPolicy ordering guidance. Use the reported measurements only to assess whether a non-normative statement about measurable, implementation-specific delay fits the concept page. Done means either an agreed documentation update is made or maintainers explicitly decide the note is out of scope.

This is a Feature Request

What would you like to be added

A short, non-normative sentence in Pod lifecycle noting that the NetworkPolicy handling delay is implementation-specific and measurable out of band — or a maintainer's judgement that this is out of scope for a concept page, which is a perfectly good outcome and the reason this is filed as a question rather than a PR.

Why is this needed

The section currently says:

Every created NetworkPolicy will be handled by a network plugin eventually, but there is no way to tell from the Kubernetes API when exactly that happens.

and suggests an init container that waits for destinations to be reachable.

That is accurate, and #39875 already separated the two orderings clearly, so this is not a request to restate any of it.

The gap is magnitude. A reader cannot tell whether the unhandled interval is microseconds or minutes, and so cannot judge whether the init-container workaround is proportionate to their risk. "No way to tell from the Kubernetes API" is true and is the part that bites — but the delay is measurable out of band, and the page does not say so.

Comments

I measured it, so the question is concrete rather than hypothetical. Single-node kind, 180 trials, 30 per cell, pre-registered protocol.

Enforcement latency from issuing kubectl apply for a default-deny policy to traffic actually being blocked, with the Pod already Ready:

All three pairs differ (Mann-Whitney, Holm-adjusted). Antrea and Calico finished enforcing before kubectl apply returned to the caller, in 30 of 30 trials each; Cilium in 0 of 30.

I also tested the ordering the page warns about. Creating the policy immediately after the victim Deployment's apply returned, all 90 such trials were already blocked at the harness's first look, on all three CNIs — the Pod never became Ready unprotected. Pod startup gave the plugin a 386–570 ms head start against that 51–116 ms latency.

These are single-node numbers and they are a floor, not an estimate. One node, one policy, one endpoint — everything that makes policy distribution hard in a real cluster is absent. I am not proposing the page carry any of these figures, and I would not want it to imply a normative value. The only thing I think the numbers establish is that the interval is bounded and measurable, which is what a reader deciding about init containers needs to know exists.

Method, pre-registration, raw-data checksums and reproduction steps: https://github.com/SomaTomita/k8s-netpol-enforcement-window

/sig network
/language en