[nginx-ingress-controller] Improve docs and examples #1130
Conversation
aledbf
force-pushed
the
improve-docs
branch
6 times, most recently
from
fdbf34f
to
4c43bd1
Compare
|
@simonswine done. Do you have another suggestion/missing thing? |
aledbf
changed the title
|
ping @bprashanth |
|
|
||
| Please check the [tcp services](examples/custom-configuration/README.md) example | ||
| ### Custom NGINX upstream checks |
There was a problem hiding this comment.
I would just call this health checks, instead of using "upstream" in the heading
|
What do you think about breaking this out into 2 docs, a high level readme that just explains ingress as it exists cross-platform (or maybe also has TCP UDP etc but nothing about upstreams, custom health, auth etc) and a customization/nginx specific doc that details each annotation and how to use it? |
aledbf
force-pushed
the
improve-docs
branch
5 times, most recently
from
6bc0c3a
to
f3bfeac
Compare
|
@bprashanth done |
| @@ -0,0 +1,389 @@ | |||
| ## Contents | |||
| * [Custom NGINX configuration](#custom-nginx-configuration) | |||
There was a problem hiding this comment.
Customizing nginx
there are 3 ways to customize nginx
- annoations: annotate the ingress, use this if you want to expose a few site specific features
- config map: create a stand alone config map, use this if you want a lot of completey different features (reword)
- custom template: when do people want this?
Annotations
The following annotaitons are supported:
table of annotations -> links to sections below
Authentication
Rewrite
...
Config Map
Custom Template
| * [Authentication](#authentication) | ||
| * [Rewrite](#rewrite) | ||
| * [Rate limiting](#rate-limiting) | ||
| * [Secure NGINX upstreams](#secure-nginx-upstreams) |
There was a problem hiding this comment.
secure-nginx-upstreams is an annotation name we can't easily adopt to the other controllers. Suggest naming with the assumption that we will bubble these up as fields, no loss if we don't.
There was a problem hiding this comment.
done. Renamed to secure-upstreams
There was a problem hiding this comment.
I can't think of a better term for upstreams, backends maybe? something more generic. I wouldn't know what upstreams is if I only use haproyx.
There was a problem hiding this comment.
Or is there motivation for calling it "upstreams" that I'm missing (either in nginx or if you want to keep upstreams for some reason)?
There was a problem hiding this comment.
No reason. Renamed to secure-backends
|
Getting better with each pass. sorry for the delay, just trying to do a decent review :) |
aledbf
force-pushed
the
improve-docs
branch
4 times, most recently
from
4932274
to
8ba891c
Compare
|
|
||
| 1. config map: create a stand alone config map, use this if you want a different global configuration | ||
| 2. annoations: [annotate the ingress](#annotations), use this if you want a specific configuration for the site defined in the ingress rule | ||
| 3. custom template: when do people want this? |
There was a problem hiding this comment.
i meant actually describe when people might want a cusomt template, maybe give an example?
| |[ingress.kubernetes.io/ssl-redirect](#server-side-https-enforcement-through-redirect)|true or false| | ||
| |[ingress.kubernetes.io/upstream-max-fails](#custom-nginx-upstream-checks)|number| | ||
| |[ingress.kubernetes.io/upstream-fail-timeout](#custom-nginx-upstream-checks)|number| | ||
| |[ingress.kubernetes.io/secure-backends](#secure-backends)|true or false| |
There was a problem hiding this comment.
I believe the annotation is ingress.kubernetes.io/secure-upstream. That's what works for me, anyway.
There was a problem hiding this comment.
@mgoodness the name will change to avoid specific nginx or haproxy terminologies
(suggested by @bprashanth)
There was a problem hiding this comment.
well i guess if it's ingress.kubernetes.io/secure-upstream already we should change the implementation so the new annotation works, deprecate the old one (just document as deprecated, kill after a few releases, maybe send out an even if anyone uses it)?
I will add a note of this in the changelog before the next release |
|
alright, I think we can iterate on this with follow up prs if needed. It's a big step forward for docs! |
[nginx-ingress-controller] Improve docs and examples
No description provided.