-
Notifications
You must be signed in to change notification settings - Fork 8.2k
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
Try to improve the installation guide #7757
Try to improve the installation guide #7757
Conversation
Welcome @jpetazzo! |
Hi @jpetazzo. 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 Once the patch is verified, the new status will be reflected by the 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. |
Just want to state that personally its an honor and a privilege just to be in conversation with you on a issue/PR. Big fan. On this PR, I looked at https://github.com/jpetazzo/ingress-nginx/blob/rework-installation-guide/docs/deploy/index.md to get a feel of what the end-result would look like and (no surprises, its after all from you), its the kind of improvement that one desires. My first feedback is while it will help to dive into details, I want to help as much as possible, with the context and the uniqueness associated with the project (and hence the implying documentation). Am going to try listing these aspects below ; (1) Because of the deprecation of older ingress api(s) in K8s v1.22, there was a massive + breaking change in code. In short, we now maintain and release 2 editions of the controller. One for pre-K8s-v1.22 specs and one for v1.22 specs and upwards. You can see some reference to that here https://kubernetes.github.io/ingress-nginx/#faq-migration-to-apiversion-networkingk8siov1 . So this effort at improvement of the install guide must make this aspect front & centre. After you incorporate this aspect, I can look at your fork again and comment further. Once again thanks tons for everything from you over the years and absolute joy to be just sending you a message directly :-), (never thought there would be such a day). |
/kind documentation thanks for cleaning this up. |
* move generic instructions to the beginning of the file * add an example of ingress resource creation * simplify a few commands to make them shorter and simpler * add short paragraphs about PROXY protocol and traffic policy This tries to address the concerns I expressed in kubernetes#7701.
266fe5d
to
b6f1f0c
Compare
@longwuyuan Hi! I've added a note at the end of the document explaining the compatibility challenges associated with Ingress Let me know if that works! |
I love this kind of improvement so I think we should merge this for now, and continue with follow up PRs as needed. However, I am of the opinion that the section "Running on Kubernetes versions older than 1.19" is better off, visible at the top of the page, instead of at the bottom. /ok-to-test |
/lgtm |
Also, while you are at it, would you want to take a shot at adding a section for a "kind" cluster. Otherwise, hopefully, we can do it in a new PR. I think it will help users a lot to get a step-by-step proecedure to run kind + metallb + ingress-nginx . |
I have some ideas for KinD but I'll do it in a separate PR. |
Hi @jpetazzo, Different PR is ok. Just an idea I floated. Also, I already put a ok-to-test on this PR and also a lgtm, so we wait for approval. Maybe the title of the PR needs edit to remove the "WIP", if you feel you are done. Also, look forward to your comments on putting that paragraph about older versions on top, instead of at the bottom. Either way is fine I guess but I thought putting it on top gives critical info to new users. |
Thanks for the reminder - I had forgotten to remove the WIP! About "let's put the version warning on top" - I'm on the fence on this; I'm hesitating. Here is my thought process:
I agree that there is a lot of confusion and issues out there with folks trying to install version 0.47 on Kubernetes 1.22; but in my humble opinion, the problem comes from old YAML / old installation guides that are still using version 0.47. In a modern guide, we should focus on version 1.0. Of course we should mention that compatibility issue but I think it should be a small footnote. Within 6-9 months, Kubernetes 1.20 and 1.21 will be deprecated and version 0.47 will only be needed on legacy clusters. That's my thought process; but if you think the note must be put forward more visibly, feel free to amend the PR of course. Thank you for your consideration! |
That is exactly my thought process. As always, a big fan of all your work over the years. Honored to be talking to you :-) . |
/triage accepted Looks great, thanks for that. |
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: jpetazzo, longwuyuan, strongjz 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 |
Hi @jpetazzo , I wanted to double-check that our release process (and likely that script in particular) can still find the text/url in the installation guide and edit accordingly. The version is embedded in the URL to manifests. Just want to be sure we covered that. I ought to check this myself but owing to some unavoidable reasons, I am not up to it just yet, hence asked. Most likely I am being paranoid because we also have to manually change version in docs in a follow up step of the release process. Apologies if this message is not helpful. Thanks, |
Hi, It looks like However, you seem to indicate that there might be another script that perhaps updates the URLs automatically ("our release process (and likely that script in particular) can still find the text/url in the installation guide and edit accordingly") but I couldn't find that script. I did a quick |
* move generic instructions to the beginning of the file * add an example of ingress resource creation * simplify a few commands to make them shorter and simpler * add short paragraphs about PROXY protocol and traffic policy This tries to address the concerns I expressed in kubernetes#7701.
Important: this is a work in progress that should be checked for correctness by someone familiar with the code base. When installing the ingress controller, I found that the documentation was missing, so I opened issue #7701 and this is an attempt to address that, by adding all the information that I wish I had found in the doc in the first place. But I don't know the code base nor the philosophy of the ingress controller, so it is possible that I got a few things wrong here, and since this is the install guide, this is probably the first document that users will read, so I think it should be correct. Thank you!Thanks to @longwuyuan's feedback, this should now hopefully be in a good state :)
What this PR does / why we need it:
Improve installation guide:
This tries to address the concerns I expressed in #7701.
Types of changes
Which issue/s this PR fixes
Fixes #7701.
How Has This Been Tested?
I tested the install instructions on various clusters (minikube, Docker Desktop, Scaleway, and a few others)
Checklist: