misleading comments in container.Ports

[j4m3s-s]

What happened?

The comments in

kubernetes/staging/src/k8s.io/api/core/v1/types.go

Line 2328 in dc96c3d

// List of ports to expose from the container. Exposing a port here gives

says that :

Exposing a port here gives
the system additional information about the network connections a
container uses, but is primarily informational.

However there are several cases where this is false :

• When using a Service with a targetPort that references a name in the ports arrays of the pod.
• Some software (ab)uses this API to get which ports are used (See Patching ports in PodSpec leads to empty diff #108131 Although unfixable, my goal is to fix the documentation so other people don't have the same problem). The Azure Load Balancer implementation does this for instance.
• Some other network/security software might use this information.

Also, is it possible to document/reference the above issue in the comment ?

What did you expect to happen?

Since it is described as informational I expected for the network to work without this information. But it's definitely not the case.

How can we reproduce it (as minimally and precisely as possible)?

Not needed since it's mostly a doc issue.

Anything else we need to know?

I'm interested in contributing this patch but would like some feedbacks before doing it. :)

Kubernetes version

$ kubectl version
# paste output here

Cloud provider

OS version

# On Linux:
$ cat /etc/os-release
# paste output here
$ uname -a
# paste output here

# On Windows:
C:\> wmic os get Caption, Version, BuildNumber, OSArchitecture
# paste output here

Install tools

Container runtime (CRI) and and version (if applicable)

Related plugins (CNI, CSI, ...) and versions (if applicable)

[j4m3s-s]

/sig network

[khenidak]

/triage accepted

@thockin -- thoughts? I believe the doc are due for a refresh.

[cyclinder]

I'd take this one.
/assign

[cyclinder]

I didn't see that you wanted to do this patch, I am very sorry and now I unassign it.
/unassign

[j4m3s-s]

No worries @cyclinder. But I'm still not sure where / what to add. Should I only fix the part saying it is only informational ? Is there anything else ? (cc @khenidak @thockin)

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[j4m3s-s]

/remove-lifecycle stale