Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix description of Ports in PodSpec #110564

Merged
merged 1 commit into from Jul 9, 2022

Conversation

j4m3s-s
Copy link
Contributor

@j4m3s-s j4m3s-s commented Jun 14, 2022

What type of PR is this?

/kind documentation

What this PR does / why we need it:

Which issue(s) this PR fixes:

Fixes #108255

Special notes for your reviewer:

First time contributor here so, if anything's missing / incorrect please enlighten me.

Does this PR introduce a user-facing change?

Make PodSpec.Ports' description clearer on how this information is only informational and how it can be incorrect.

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:


@k8s-ci-robot k8s-ci-robot added release-note Denotes a PR that will be considered when it comes time to generate release notes. kind/documentation Categorizes issue or PR as related to documentation. size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Jun 14, 2022
@linux-foundation-easycla
Copy link

linux-foundation-easycla bot commented Jun 14, 2022

CLA Signed

The committers listed above are authorized under a signed CLA.

  • login: j4m3s-s / name: James Landrein (8991f493a5e803ebad710f9a6eb85038d17d066b)

@k8s-ci-robot k8s-ci-robot added cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. do-not-merge/needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. labels Jun 14, 2022
@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Jun 14, 2022

Welcome @j4m3s-s!

It looks like this is your first PR to kubernetes/kubernetes 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/kubernetes has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

@k8s-ci-robot k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Jun 14, 2022
@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Jun 14, 2022

Hi @j4m3s-s. Thanks for your PR.

I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

@k8s-ci-robot k8s-ci-robot added needs-priority Indicates a PR lacks a `priority/foo` label and requires one. kind/api-change Categorizes issue or PR as related to adding, removing, or otherwise changing an API labels Jun 14, 2022
@k8s-ci-robot k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. labels Jun 14, 2022
@j4m3s-s
Copy link
Contributor Author

j4m3s-s commented Jun 14, 2022

@cyclinder The PR we talked about the other day.

@k8s-triage-robot
Copy link

k8s-triage-robot commented Jun 14, 2022

This PR may require API review.

If so, when the changes are ready, complete the pre-review checklist and request an API review.

Status of requested reviews is tracked in the API Review project.

@cyclinder
Copy link
Contributor

cyclinder commented Jun 14, 2022

/sig api-machinery
/sig network
/ok-to-test

@k8s-ci-robot k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. sig/network Categorizes an issue or PR as relevant to SIG Network. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. do-not-merge/needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. labels Jun 14, 2022
@j4m3s-s
Copy link
Contributor Author

j4m3s-s commented Jun 14, 2022

/retest

@fedebongio
Copy link
Contributor

fedebongio commented Jun 14, 2022

/remove-sig api-machinery
/sig node

@k8s-ci-robot k8s-ci-robot added sig/node Categorizes an issue or PR as relevant to SIG Node. and removed sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. labels Jun 14, 2022
@aojea
Copy link
Member

aojea commented Jun 14, 2022

/assign @thockin @khenidak

they were dancing with this problem in the referred issue
#103544 (comment)

@k8s-ci-robot k8s-ci-robot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Jun 16, 2022
@leilajal
Copy link
Contributor

leilajal commented Jun 16, 2022

/remove-sig api-machinery

@k8s-ci-robot k8s-ci-robot removed the sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. label Jun 16, 2022
// This array might be out-of-date because it merges on containerPort and not (containerPort, protocol).
// This information should not be used to get accurate ports exposed by pod.
// See https://github.com/kubernetes/kubernetes/issues/103544 for more information.
Copy link
Contributor

@danwinship danwinship Jun 16, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That doesn't seem like the right doc fix. I would say "don't use strategic merge patch with this field" and explain why.

Copy link
Contributor Author

@j4m3s-s j4m3s-s Jun 17, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think my current contribution makes it clearer that this information should not be taken as truth. Do you want me to add a part indicating "don't use strategic merge patch with this field" or replace my comment by yours ?
I think mine makes it clearer for those not necessarily familiar with merge strategies in k8s. WDYT ?

Copy link
Contributor

@sftim sftim Jun 17, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Other than a strategic merge patch or purely client-side confusion, is there any other way for this field to become “out of date”?

If the only API means to get it wrong are strategic merge patch, we can say so.
💭 We could also, in the API, send a Warning: response any time someone does a strategic merge patch that updates this field (and client-go etc then presents the warning to its caller).

Copy link
Contributor

@danwinship danwinship Jun 17, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think my current contribution makes it clearer that this information should not be taken as truth.

But it is the truth. If you have a Service that is delivering to port "foo" on a given pod, and someone uses strategic merge patch and accidentally removes that entry from Ports, then the service will stop delivering traffic to that pod. The problem is not that Ports contains incorrect information; it's that the pod has been redefined, and the new definition isn't what you had wanted.

Copy link
Contributor Author

@j4m3s-s j4m3s-s Jun 20, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I should have been clearer in my wording. Indeed you are right, it is the truth.

I don't think there's any other way of the fields Ports to be out-of-date.
I agree we should indicate the problem is using strategic merge patch in this case, but I would prefer if we also make it clear for people that are not familiar with it (as was I when I encountered this bug). Is it okay to link k8s docs in those comments ?
I would say something along the lines of

Use of strategic merge patch with this field can lead to errors due to information seemingly being the same but actually being different. This happens when applying diffing with arrays with same port number since the diffing takes only port into account and not the tuple (port, protocol).
See <link to the issue>
See <link to strategic merge patch like https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/#notes-on-the-strategic-merge-patch>.

Sending a warning sounds like a great idea ! Do you mind giving me some pointers on how to do this ? Should I add this to this PR or should I make another one ?

I'm also open to suggestions on wording since I'm not a native english speaker.

Copy link
Contributor

@danwinship danwinship Jun 22, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The other case I know of is:

https://github.com/kubernetes/api/blob/v0.24.2/core/v1/types.go#L4986

But that's a field that end users don't really modify anyway (since kubelet would overwrite their modifications) so the docs don't need to worry as much about being understandable to end users...

Use of strategic merge patch with this field can lead to errors due to information seemingly being the same but actually being different. This happens when applying diffing with arrays with same port number since the diffing takes only port into account and not the tuple (port, protocol).

I'm not sure it's worth explaining in that much detail since it doesn't especially help the user to solve their problem. I'd just note that trying to modify it with strategic merge patch may corrupt the data, but that you can still use other kinds of patch if you need to. And link to this PR or to #108255 and then people who want to know more can follow the link.

Copy link
Contributor

@danwinship danwinship Jun 22, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sending a warning sounds like a great idea ! Do you mind giving me some pointers on how to do this ? Should I add this to this PR or should I make another one ?

I opened #110627 about that, but it's likely to be complicated. I don't know exactly how the apiserver warning mechanism works...

Copy link
Contributor Author

@j4m3s-s j4m3s-s Jun 23, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I followed the issue as well. I'm not an expert in client-go / API server but I'm a bit worried on how the client will get an error properly.

Otherwise, thanks for the feedback, will update the PR.

@k8s-ci-robot k8s-ci-robot added the sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. label Jun 23, 2022
@leilajal
Copy link
Contributor

leilajal commented Jun 23, 2022

/triage accepted

@k8s-ci-robot k8s-ci-robot added triage/accepted Indicates an issue or PR is ready to be actively worked on. and removed needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. labels Jun 23, 2022
Copy link
Member

@thockin thockin left a comment

Thanks!

/lgtm
/approve

@k8s-ci-robot k8s-ci-robot added lgtm Indicates that a PR is ready to be merged. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Jul 6, 2022
@k8s-triage-robot
Copy link

k8s-triage-robot commented Jul 6, 2022

The Kubernetes project has merge-blocking tests that are currently too flaky to consistently pass.

This bot retests PRs for certain kubernetes repos according to the following rules:

  • The PR does have any do-not-merge/* labels
  • The PR does not have the needs-ok-to-test label
  • The PR is mergeable (does not have a needs-rebase label)
  • The PR is approved (has cncf-cla: yes, lgtm, approved labels)
  • The PR is failing tests required for merge

You can:

/retest

3 similar comments
@k8s-triage-robot
Copy link

k8s-triage-robot commented Jul 7, 2022

The Kubernetes project has merge-blocking tests that are currently too flaky to consistently pass.

This bot retests PRs for certain kubernetes repos according to the following rules:

  • The PR does have any do-not-merge/* labels
  • The PR does not have the needs-ok-to-test label
  • The PR is mergeable (does not have a needs-rebase label)
  • The PR is approved (has cncf-cla: yes, lgtm, approved labels)
  • The PR is failing tests required for merge

You can:

/retest

@k8s-triage-robot
Copy link

k8s-triage-robot commented Jul 7, 2022

The Kubernetes project has merge-blocking tests that are currently too flaky to consistently pass.

This bot retests PRs for certain kubernetes repos according to the following rules:

  • The PR does have any do-not-merge/* labels
  • The PR does not have the needs-ok-to-test label
  • The PR is mergeable (does not have a needs-rebase label)
  • The PR is approved (has cncf-cla: yes, lgtm, approved labels)
  • The PR is failing tests required for merge

You can:

/retest

@k8s-triage-robot
Copy link

k8s-triage-robot commented Jul 7, 2022

The Kubernetes project has merge-blocking tests that are currently too flaky to consistently pass.

This bot retests PRs for certain kubernetes repos according to the following rules:

  • The PR does have any do-not-merge/* labels
  • The PR does not have the needs-ok-to-test label
  • The PR is mergeable (does not have a needs-rebase label)
  • The PR is approved (has cncf-cla: yes, lgtm, approved labels)
  • The PR is failing tests required for merge

You can:

/retest

@k8s-ci-robot k8s-ci-robot removed the lgtm Indicates that a PR is ready to be merged. label Jul 7, 2022
@j4m3s-s
Copy link
Contributor Author

j4m3s-s commented Jul 7, 2022

Sorry, I took a bit of time to fix the last issue on my PR, this should be mergeable now. I think all the tests that aren't passing aren't my fault (please correct me if my analysis is wrong ofc :). ).

@j4m3s-s j4m3s-s requested a review from thockin Jul 7, 2022
Copy link
Member

@thockin thockin left a comment

Thanks!

/lgtm
/approve

@k8s-ci-robot k8s-ci-robot added the lgtm Indicates that a PR is ready to be merged. label Jul 8, 2022
@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Jul 8, 2022

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: j4m3s-s, thockin

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-triage-robot
Copy link

k8s-triage-robot commented Jul 9, 2022

The Kubernetes project has merge-blocking tests that are currently too flaky to consistently pass.

This bot retests PRs for certain kubernetes repos according to the following rules:

  • The PR does have any do-not-merge/* labels
  • The PR does not have the needs-ok-to-test label
  • The PR is mergeable (does not have a needs-rebase label)
  • The PR is approved (has cncf-cla: yes, lgtm, approved labels)
  • The PR is failing tests required for merge

You can:

/retest

@k8s-ci-robot k8s-ci-robot merged commit 00ea892 into kubernetes:master Jul 9, 2022
14 checks passed
SIG Node PR Triage automation moved this from Triage to Done Jul 9, 2022
@k8s-ci-robot k8s-ci-robot added this to the v1.25 milestone Jul 9, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
approved Indicates a PR has been approved by an approver from all required OWNERS files. area/code-generation cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/api-change Categorizes issue or PR as related to adding, removing, or otherwise changing an API kind/documentation Categorizes issue or PR as related to documentation. lgtm Indicates that a PR is ready to be merged. needs-priority Indicates a PR lacks a `priority/foo` label and requires one. ok-to-test Indicates a non-member PR verified by an org member that is safe to test. release-note Denotes a PR that will be considered when it comes time to generate release notes. sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. sig/network Categorizes an issue or PR as relevant to SIG Network. sig/node Categorizes an issue or PR as relevant to SIG Node. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. triage/accepted Indicates an issue or PR is ready to be actively worked on.
Projects
Development

Successfully merging this pull request may close these issues.

misleading comments in container.Ports