Refresh kube-component reference docs

[tengqm]

This PR updates the generated reference docs for kube-components.
The source used if from the 'release-1.10' branch of
kubernetes/kubernetes.

Close: #8280

[k8sio-netlify-preview-bot]

Deploy preview for kubernetes-io-master-staging ready!

Built with commit d7e2234

https://deploy-preview-8283--kubernetes-io-master-staging.netlify.com

[Bradamant3]

/assign

cc @steveperry-53

@tengqm This PR makes sense, except ... it removes the doc for a deprecated flag that isn't yet fully removed from the code/apiserver (--admission-control). We've now got --enable-admission-plugins properly documented (per issue #8280), but per discussion in PR #7887 we've lost the deprecated flag. And I don't understand the code base well enough to be able to figure out what's going on there. It looks to me as though on master, at https://github.com/kubernetes/kubernetes/blob/master/pkg/kubeapiserver/options/admission.go#L67ff, we should still get doc for --admission-control -- but that's not what's in the release-1.10 branch (code).

I won't hold up this PR for very long, but I'd like to find someone stateside who can explain the code to me, and maybe we can find some not terrible time that works for both of us to chat, too. I'm guessing these aren't the only flags that aren't showing up properly in the doc, but I'm using them as an indicator of the larger problem. Thanks for your patience!

[tengqm]

@Bradamant3 I understand the concern for not showing the "hidden" flags. Those flags are not shown on the command line when you do, for example, kube-apiserver --help. Do you really think it makes senses to list an option in the reference documentation when that option disappeared from the command line? The whole idea of making flags "hidden" is stop advertising them to users. They are not completely removed simply because there are existing users who are still using them. This is my understanding why kubelet has hidden so many flags and kube-apiserver has also hidden a few of them. In my opinion, the "larger" problem you want to solve is at the upstream kubernetes/kubernetes project.

[Bradamant3]

@tengqm absolutely agreed that the larger problem needs to be solved upstream. But if you look at the master branch upstream, these lines are added (the second one NOT in release-1.10 branch), to show the doc for (at this this one) deprecated flag (https://github.com/kubernetes/kubernetes/blob/master/pkg/kubeapiserver/options/admission.go#L76 but also pasted here):

    fs.MarkDeprecated("admission-control", "Use --enable-admission-plugins or --disable-admission-plugins instead. Will be removed in a future version.")
    fs.Lookup("admission-control").Hidden = false

I'm not in a position to test atm, but this also looks to me as though there's at least meant to be some command-line help to indicate that the flag is deprecated. Which is good UX.

So now we (in docs land at least) are in a situation where we can't do the complete right thing if we generate from either master or release-1.10. And I'm guessing the problem exists (upstream) for other flags too, although the code is making my brain hurt trying to chase down just where --enable-admission-plugins lives. All sorts of bits, but it's based on a different model from --admission-control.

I'm overthinking, so assigning a couple of other folks whose judgment I trust to make the final call here.

[Bradamant3]

/assign @heckj

/assign @chenopis

[tengqm]

@Bradamant3 I don't buy in the idea of "hiding" flags at all. It smells like a lie to users. The components is doing things *undocumented". By "undocumented", I mean there are flags not shown on man pages, not meant to show as help messages, not meant to show as markdown docs, but these flags do exist secretly and they work! This design is somehow breaking the convention how things are deprecated (aka. deprecation policy) across the community.

[Bradamant3]

@tengqm I agree. This line: fs.Lookup("admission-control").Hidden = false means the flag documentation is NOT hidden. (It's a weird pattern, and looks pretty brittle, but that's a separate issue.) The line, and therefore the doc, are missing in release-1.10. (There's also not a consistent pattern for implementing flags across the codebase, which doesn't help.) After Kubecon, I want to take the larger issue of flag deprecation and docs up with Jordan.

Not merging this PR yet bc the Travis build is broken this morning, but getting the process started bc better to document only the current flag (which is currently missing) than only the deprecated flag. Bad choice regardless, but there we are.

cc @liggitt

[Bradamant3]

/lgtm

[liggitt]

I think some form of these should be picked to 1.10.x to ensure we don't hide the flags that are currently usable:

• Show help for deprecated Kubelet flags kubernetes#62505
• Show deprecated kube-apiserver flags kubernetes#62621

[zacharysarah]

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: zacharysarah

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:

• OWNERS [zacharysarah]

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